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

First Steps

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.

class SecKey

An object that represents a cryptographic key.

func SecKeyGetTypeID() -> CFTypeID

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.

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.

Examining Keys

func SecKeyIsAlgorithmSupported(SecKey, SecKeyOperationType, SecKeyAlgorithm) -> Bool

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

func SecKeyGetBlockSize(SecKey) -> Int

Gets the block length associated with a cryptographic key.

func SecKeyCopyAttributes(SecKey) -> CFDictionary?

Gets the attributes of a given key.

struct SecKeyAlgorithm

The algorithms that cryptographic keys enable.

enum 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.

func SecKeyCopyExternalRepresentation(SecKey, UnsafeMutablePointer<Unmanaged<CFError>?>?) -> CFData?

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

Key Exchange

struct 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.

Digital Signatures

Signing and Verifying

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

func SecKeyCreateSignature(SecKey, SecKeyAlgorithm, CFData, UnsafeMutablePointer<Unmanaged<CFError>?>?) -> CFData?

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

func SecKeyVerifySignature(SecKey, SecKeyAlgorithm, CFData, CFData, UnsafeMutablePointer<Unmanaged<CFError>?>?) -> Bool

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

Legacy macOS Key Operations

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.