Wherein I Write Apple’s Technote About OpenSSL on OS X For Them

Technical Note TNNaN: OpenSSL on OS X

Long story short: we screwed up when we included OpenSSL (libcrypto) in OS X in the first place.

(We learned our lesson and didn’t repeat the mistake with iOS.)

Now there’s some transitionin’ to do.


  • New Code Should Use SecTransform. SecTransform is cool: it’s high-level, rather declarative, fast and even leverages GCD. It solves OpenSSL’s issues described below in the Backgrounder section.

  • Code That Uses OpenSSL Just for Hashing Should Switch to CommonCrypto. CommonCrypto provides a thin OpenSSL compatibility shim for common cryptographic message digests. It’s called COMMON_DIGEST_FOR_OPENSSL and lives in CommonDigest.h.

  • Apps That Need OpenSSL Should Include Their Own Copy. You should stop using the system’s supplied libcrypto.dylib, build your own and link it into your app.

    We know that’s a pain, but this project should help you out.

    Add -isystem "$(SRCROOT)/openssl-1.0.1c/include" to OTHER_C_FLAGS to pick up your project’s local OpenSSL headers instead of the system’s headers (which are outdated and throb with deprecation attributes).


The crux of the problem is OpenSSL doesn’t offer API compatibility between versions.

We’d love to ship updated versions of OpenSSL, but there’s only two feasible routes, both of which are seriously problematic:

  • Apps link to /usr/lib/libcrypto.dylib symlink. In theory we should be able to always point that to the latest version of libcrypto.dylib and apps get free security + capability updates.

    In practice we’d break shipping apps since the APIs are different. So it’s kinda stuck. (Notice we’re still shipping v0.9.8r when v1.0.1c is the latest.)

  • Apps link to a specific version of libcrypto. For example: /usr/lib/libcrypto.0.9.8.dylib.

    Now your app doesn’t get security + capability updates for free. When there’s a security hole, it’s now our job to backport the fixes in the latest OpenSSL into the old-ass version your app is linked against.

    Nobody wins in this case.

Ideally the OpenSSL project would do a better job at API compatibility, but it’s really not in their unixy source-code-oriented worldview. Sure we could get big into the project to try to improve it, but we’d rather put the resources into making OS X rock harder.

Both SecTransform and lowly CommonCrypto offer API compatibility, allowing us to add functionality and fix security problems even in shipping apps, which is awesome for users.

openssl Oct 16 2012