Article

Storing Keys in the Secure Enclave

Create an extra layer of security for your private keys.

Overview

Keeping a private key in a keychain is a great way to secure it. The key data is encrypted on disk and accessible only to your app or the apps you authorize. However, to use the key, you must briefly copy a plain-text version of it into system memory. While this presents a reasonably small attack surface, there’s still the chance that if your app is compromised, the key could also become compromised. As an added layer of protection, you can store a private key in the Secure Enclave.

The Secure Enclave is a hardware-based key manager that’s isolated from the main processor to provide an extra layer of security. When you store a private key in the Secure Enclave, you never actually handle the key, making it difficult for the key to become compromised. Instead, you instruct the Secure Enclave to create the key, securely store it, and perform operations with it. You receive only the output of these operations, such as encrypted data or a cryptographic signature verification outcome.

The benefits of the Secure Enclave are balanced against a few restrictions. In particular, the Secure Enclave:

  • Is a hardware feature of the Apple A7 or later A-series processor. Only iOS devices with one of these processors or a MacBook Pro with the Touch Bar and Touch ID support this feature.

  • Stores only 256-bit elliptic curve private keys. These keys can only be used for creating and verifying cryptographic signatures, or for elliptic curve Diffie-Hellman key exchange (and by extension, symmetric encryption).

  • Can’t import preexisting keys. You must create keys directly inside the Secure Enclave. Not having a mechanism to transfer key data into or out of the Secure Enclave is fundamental to its security.

The steps required to create a private key in the Secure Enclave (and its corresponding public key outside the Secure Enclave) are similar to those for creating a key pair in the usual way, as described in Generating New Cryptographic Keys. The following sections highlight the differences.

Specify Access Control

You start by using an attribute dictionary to describe the key, but in this case, one of the attributes is an access control object. Use SecAccessControlCreateWithFlags(_:_:_:_:) to create a suitable object:

let access =
    SecAccessControlCreateWithFlags(kCFAllocatorDefault,
                                    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
                                    .privateKeyUsage,
                                    nil)!   // Ignore error

This particular object includes a protection parameter of kSecAttrAccessibleWhenUnlockedThisDeviceOnly. As a result, the associated keychain item is only accessible on the device that created it (a feature that’s also inherent to using the Secure Enclave), and only when the device is unlocked. Other less restrictive options are possible, but this option is generally preferred unless your app operates in the background.

A critical aspect of this access control object is its privateKeyUsage flag. This flag indicates that the private key should be available for use in signing and verification operations inside the Secure Enclave. Without the flag, key generation still succeeds, but signing operations that attempt to use it fail.

You could also combine the privateKeyUsage flag with other flags, using a bitwise OR to obtain additional protection for your key. For example, if you include the touchIDAny flag, you instruct the system to make the key available only when the system can authenticate the user with Touch ID (or a fallback passcode). See SecAccessControlCreateFlags for the complete list of available flags.

Assemble the Attributes

Using the access control object, you then create an attribute dictionary:

let attributes: [String, Any] = [
  kSecAttrKeyType as String:            type,
  kSecAttrKeySizeInBits as String:      256,
  kSecAttrTokenID as String:            kSecAttrTokenIDSecureEnclave,
  kSecPrivateKeyAttrs as String: [
    kSecAttrIsPermanent as String:      true,
    kSecAttrApplicationTag as String:   <# a tag #>,
    kSecAttrAccessControl as String:    access
  ]
]

The attribute dictionary above is structurally similar to the one described in Creating an Asymmetric Key Pair. In particular, it indicates that the private key should be stored in the keychain and tagged for later retrieval. However, it differs in a few critical ways:

  • A new attribute, kSecAttrTokenID, with the value kSecAttrTokenIDSecureEnclave, indicates that the generation operation should take place inside the Secure Enclave.

  • The type and size attributes reflect that Secure Enclave only stores 256-bit elliptic curve keys.

  • The private key attribute dictionary includes the access control object generated in the previous step to indicate how the key can be used.

Create A Key Pair

With the attributes dictionary in hand, you create the key pair just as you do outside the Secure Enclave, with a call to the SecKeyCreateRandomKey(_:_:) function:

var error: Unmanaged<CFError>?
guard let privateKey = SecKeyCreateRandomKey(attributes as CFDictionary, &error) else {
    throw error!.takeRetainedValue() as Error
}

Notice that you still receive a reference to the private key object, even though it’s stored in the Secure Enclave. The private key is logically part of the keychain, and you can later obtain a reference to it in the usual way. But because its backing storage is physically part of the Secure Enclave, you can never inspect the key’s data.

Use the Secured Key

In most respects, key management proceeds as usual. You rely on the SecKeyCopyPublicKey(_:) function to obtain the public key from the private key, as described in Getting an Existing Key. You handle and release errors in the usual way. And while Swift manages the memory for you, in Objective-C, after you’re done with any generated items, you release their memory:

if (privateKey) { CFRelease(privateKey); }
if (access)     { CFRelease(access);     }

When you want to retrieve the key, you do it in the usual way, as described in Storing Keys in the Keychain. You also use the key to sign a block of code exactly as you would normally, as described in Signing and Verifying. Alternatively, you can use the key for encryption, as described in Using Keys for Encryption and in particular, for symmetric encryption using the eciesEncryptionCofactorX963SHA256AESGCM algorithm. Note that in these cases, you’re restricted to the elliptic curve algorithms because the Secure Enclave holds only elliptic curve keys.

See Also

Key Generation

Generating New Cryptographic Keys

Create both asymmetric and symmetric cryptographic keys.

func SecKeyCopyPublicKey(SecKey) -> SecKey?

Gets the public key associated with the given private key.

Key Generation Attributes

Use attribute dictionary keys during cryptographic key generation.