Keys

Generate, store, and use cryptographic keys.

Overview

Cryptographic keys are strings of bytes that you combine with other data in specialized mathematical operations to enhance security. At the lowest level, this usually means participating in either encryption and decryption or digital signing and verification. You can use these basic operations directly, such as when you encrypt data before sending it through an insecure channel. You also use them implicitly, such as when you verify the digital signature on a certificate as a byproduct of a trust evaluation.

Keys vary based on the operations they support. For example, you use public and private key pairs to perform asymmetric encryption, whereas you use symmetric keys to conduct symmetric encryption. Similarly, one key might work for a 1024-bit RSA algorithm, while another might be suitable for a 256-bit elliptic curve algorithm. Use the functions in this section when you need to handle cryptographic keys.

Topics

Essentials

Getting an Existing Key

Learn how to obtain an existing cryptographic key.

Storing Keys in the Keychain

Store and access cryptographic keys in the keychain.

SecKeyRef

An object that represents a cryptographic key.

SecKeyGetTypeID

Returns the unique identifier of the opaque type to which a key object belongs.

Key Generation

Generating New Cryptographic Keys

Create both asymmetric and symmetric cryptographic keys.

Storing Keys in the Secure Enclave

Create an extra layer of security for your private keys.

SecKeyCreateRandomKey

Generates a new private/public key pair.

SecKeyCopyPublicKey

Gets the public key associated with the given private key.

Key Generation Attributes

Use attribute dictionary keys during cryptographic key generation.

Examining Keys

SecKeyIsAlgorithmSupported

Returns a Boolean indicating whether a key is suitable for an operation using a certain algorithm.

SecKeyGetBlockSize

Gets the block length associated with a cryptographic key.

SecKeyCopyAttributes

Gets the attributes of a given key.

SecKeyAlgorithm

The algorithms that cryptographic keys enable.

SecKeyOperationType

The types of operations that you can use a cryptographic key to perform.

Import and Export

Storing Keys as Data

Create an external representation of a key for transmission.

SecKeyCopyExternalRepresentation

Returns an external representation of the given key suitable for the key's type.

SecKeyCreateWithData

Restores a key from an external representation of that key.

Key Exchange

SecKeyCopyKeyExchangeResult

Performs the Diffie-Hellman style of key exchange with optional key-derivation steps.

SecKeyKeyExchangeParameter

The dictionary keys used to specify Diffie-Hellman key exchange parameters.

Encryption

Using Keys for Encryption

Perform asymmetric and symmetric encryption and decryption using cryptographic keys.

SecKeyCreateEncryptedData

Encrypts a block of data using a public key and specified algorithm.

SecKeyCreateDecryptedData

Decrypts a block of data using a private key and specified algorithm.

Digital Signatures

Signing and Verifying

Create and evaluate digital signatures to establish the validity of code or data.

SecKeyCreateSignature

Creates the cryptographic signature for a block of data using a private key and specified algorithm.

SecKeyVerifySignature

Verifies the cryptographic signature of a block of data using a public key and specified algorithm.

Legacy iOS Key Operations

SecKeyGeneratePair

Creates an asymmetric key pair.

SecKeyEncrypt

Encrypts a block of plaintext.

SecKeyDecrypt

Decrypts a block of ciphertext.

SecKeyRawSign

Generates a digital signature for a block of data.

SecKeyRawVerify

Verifies a digital signature.

SecPadding

The types of padding to use when you create or verify a digital signature.

Legacy macOS Key Operations

SecKeyGeneratePairAsync

Generates a public/private key pair.

SecKeyGenerateSymmetric

Generates a random symmetric key.

SecKeyCreateFromData

Constructs a SecKeyRef object for a symmetric key.

SecKeyDeriveFromPassword

Returns a key object in which the key data is derived from a password.

SecKeyWrapSymmetric

Wraps a symmetric key with another key.

SecKeyUnwrapSymmetric

Unwraps a wrapped symmetric key.

SecKeyGetCredentials

Returns an access credential for a key.

Deprecated
SecKeyGetCSPHandle

Returns the CSSM CSP handle for a key.

Deprecated
SecKeyGetCSSMKey

Retrieves a pointer to the CSSM_KEY structure containing the key stored in a keychain item.

Deprecated
SecKeySizes

The supported sizes for keys of various common types.

SecKeyUsage

The flags that indicate key usage in the KeyUsage extension of a certificate.

SecPublicKeyHash

A container for a 20-byte public key hash.

SecKeyCreatePair

Creates an asymmetric key pair and stores it in a keychain.

Deprecated
SecKeyGenerate

Creates a symmetric key and optionally stores it in a keychain.

Deprecated
SecKeyGeneratePairBlock

A block called with the results of a call to SecKeyGeneratePairAsync.

SecCredentialType

The credential type to be returned by SecKeyGetCredentials.

See Also

API Components

Certificates

Manage digital certificates.

Identities

Combine certificates and cryptographic keys into identities.

Policies

Obtain policies for establishing trust.

Trust

Evaluate trust based on a given policy.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software