Cryptographic Services Guide

Encrypting and Hashing Data

Both symmetric and asymmetric key encryption schemes can be used to encrypt data. Asymmetric encryption is most commonly used for sending data across trust boundaries, such as one person sending another person an encrypted email. It is also often used for sending a symmetric session key across an insecure communication channel so that symmetric encryption can then be used for future communication. Symmetric encryption is most commonly used for data at rest (on your hard drive for example) and as a session key in a number of encrypted networking schemes.

OS X and iOS provide a number of different APIs for encryption and decryption. This chapter describes the recommended APIs.

Encryption Technologies Common to iOS and OS X

OS X and iOS provide a number of encryption technologies. Of these, three APIs are available on both iOS and OS X:

Keychain Services API—provides secure storage for passwords, keys, and so on

Keychain Services

The Keychain Services API is commonly used to store passwords, keys, certificates, and other secrets in a special encrypted file called a keychain. You should always use the keychain to store passwords and other short pieces of data (such as cookies) that are used to grant access to secure web sites, as otherwise this data might be compromised if an unauthorized person gains access to a user’s computer, mobile device, or a backup thereof.

OS X also includes a utility that allows users to store and read the data in the keychain, called Keychain Access. For more information, see Keychain Access in Security Overview.

Cryptographic Message Syntax Services

The Cryptographic Message Syntax Services programming interface allows you to encrypt or add a digital signature to S/MIME messages. (S/MIME is a standard for encrypting and signing messages, most commonly used with email.) It is a good API to use when signing or encrypting data for store-and-forward applications, such as email. See Cryptographic Message Syntax Services Reference for details.

Certificate, Key, and Trust Services

In iOS, this API also provides basic encryption capabilities, as described in Encryption in iOS.

Common Crypto

In OS X v10.5 and later and iOS 5.0 and later, Common Crypto provides low-level C support for encryption and decryption. Common Crypto is not as straightforward as Security Transforms, but provides a wider range of features, including additional hashing schemes, cipher modes, and so on.

Encryption Technologies Specific to OS X

Security Transforms API—a Core-Foundation-level API that provides support for signing and verifying, symmetric cryptography, and Base64 encoding and decoding

Common Crypto—a C-level API that can perform most symmetric encryption and decryption tasks

CDSA/CSSM—a legacy API that should be used only to perform tasks not supported by the other two APIs, such as asymmetric encryption

These APIs are described in the sections that follow.

Security Transforms

In OS X v10.7 and later, the Security Transforms API provides efficient and easy-to-use support for performing cryptographic tasks. Security transforms are the recommended way to perform symmetric encryption and decryption, asymmetric signing and verifying, and Base64 encoding and decoding in OS X.

Based on the concept of data flow programming, the Security Transforms API lets you construct graphs of transformations that feed into one another, transparently using Grand Central Dispatch to schedule the resulting work efficiently across multiple CPUs. As the CFDataRef (or NSData) objects pass through the object graph, callbacks within each individual transform operate on that data, then pass it on to the transform’s output, which may be connected to the input of another transform object, and so on.

The transform API also provides a file reader transform (based on CFReadStreamRef or NSInputStream objects) that can be chained to the input of other transforms.

Using the built-in transforms, the Security Transforms API allows you to read files, perform symmetric encryption and decryption, perform asymmetric signing and verifying, and perform Base64 encoding. The Security Transforms API also provides support for creating custom transforms that perform other operations on data. For example, you might create a transform that byte swaps data prior to encrypting it or a transform that encodes the resulting encrypted data for transport.

CDSA/CSSM

Important: CDSA (including CSSM) is deprecated and should not be used for new development. It is not available in iOS.

CDSA is an Open Source security architecture adopted as a technical standard by the Open Group. Apple has developed its own Open Source implementation of CDSA, available as part of Darwin at Apple’s Open Source site. This API provides a wide array of security services, including fine-grained access permissions, authentication of users’ identities, encryption, and secure data storage.

Although CDSA has its own standard programming interface, it is complex and does not follow standard Apple programming conventions. For this reason, the CDSA API is deprecated as of OS X version 10.7 (Lion) and is not available in iOS. Fortunately, OS X and iOS include their own higher-level security APIs that abstract away much of that complexity.

Where possible, you should use one of the following instead of using CDSA directly:

The Security Transforms API for symmetric encryption and decryption, asymmetric signing and verifying, and other supported tasks in OS X v10.7 and later. See Security Transforms for details.

The Certificate, Key, and Trust Services API for general encryption, key management, and other tasks. See Encryption in iOS for details.

If these APIs do not meet your needs, you can still use CDSA in OS X, but please file bugs at http://bugreport.apple.com/ to request the additional functionality that you need. For more information, read CDSA Overview.

OpenSSL

Although OpenSSL is commonly used in the open source community, OpenSSL does not provide a stable API from version to version. For this reason, although OS X provides OpenSSL libraries, the OpenSSL libraries in OS X are deprecated, and OpenSSL has never been provided as part of iOS. Use of the OS X OpenSSL libraries by apps is strongly discouraged.

If your app depends on OpenSSL, you should compile OpenSSL yourself and statically link a known version of OpenSSL into your app. This use of OpenSSL is possible on both OS X and iOS. However, unless you are trying to maintain source compatibility with an existing open source project, you should generally use a different API.

Common Crypto and Security Transforms are the recommended alternatives for general encryption. CFNetwork and Secure Transport are the recommended alternatives for secure communications.

Encryption in iOS

In iOS, in addition to providing support functions for encoding and decoding keys, the Certificate, Key, and Trust Services API also provides basic encryption, decryption, signing, and verifying of blocks of data using the following SecKey functions: