Documentation
¶
Overview ¶
Package enclave provides access to the Apple Secure Enclave (SEP) for hardware-backed key management and ECIES encryption.
On darwin with CGO enabled, keys are generated inside the Secure Enclave co-processor and never leave hardware. On all other platforms the package returns ErrNotSupported for every operation so the rest of the codebase can compile and be tested cross-platform.
Encryption scheme:
ephemeral P-256 key pair → ECDH with SE public key → HKDF-SHA-256 (32-byte key) → AES-256-GCM
Wire format (Encrypt / Decrypt):
[1 byte ] version (0x01) [65 bytes ] uncompressed ephemeral public key [12 bytes ] AES-GCM nonce [n bytes ] ciphertext [16 bytes ] AES-GCM authentication tag
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrKeyNotFound = errors.New("enclave: key not found in keychain")
ErrKeyNotFound is returned when no key with the requested tag exists in the keychain.
var ErrNotSupported = errors.New("enclave: Secure Enclave not supported on this platform")
ErrNotSupported is returned on non-darwin builds or when CGO is disabled.
var ErrSIPDisabled = errors.New("enclave: System Integrity Protection (SIP) is disabled")
ErrSIPDisabled is returned by CheckSIP when System Integrity Protection is not active, indicating the host cannot provide the expected isolation guarantees.
Functions ¶
func CheckSIP ¶
func CheckSIP() error
CheckSIP verifies that System Integrity Protection is enabled on the host. Returns nil when SIP is active, ErrSIPDisabled when it is not, or another error when the check itself fails.
func Decrypt ¶
Decrypt decrypts a ciphertext produced by Encrypt using the SE private key identified by tag.
func Encrypt ¶
Encrypt encrypts plaintext so that only the holder of the SE key identified by recipientPubKey can decrypt it.
recipientPubKey must be the uncompressed (65-byte) SEC1 public key returned by Key.PublicKeyBytes().
The returned ciphertext uses the wire format described in the package doc.
Types ¶
type Key ¶
type Key interface {
// PublicKeyBytes returns the uncompressed (65-byte) SEC1 encoding of the
// public key: 0x04 || X || Y.
PublicKeyBytes() []byte
// Sign signs digest (a raw SHA-256 hash) using the SE private key and
// returns the DER-encoded ECDSA signature.
Sign(digest []byte) ([]byte, error)
// ECDH performs a Diffie-Hellman key exchange with the provided
// uncompressed peer public key and returns the raw shared secret bytes.
ECDH(peerPubKeyBytes []byte) ([]byte, error)
// Decrypt decrypts a ciphertext produced by Encrypt using this key's
// SE-backed private component directly. Callers that hold a Key handle
// should prefer this over the package-level Decrypt so that the key
// does not need to be re-loaded from the keychain.
Decrypt(ciphertext []byte) ([]byte, error)
// Tag returns the keychain application tag that identifies this key.
Tag() string
// Persistent reports whether this key is durably stored in the keychain.
// An ephemeral key (created when keychain write permissions are absent)
// is valid for the lifetime of the process only.
Persistent() bool
// Delete removes the key from the Secure Enclave / keychain permanently.
Delete() error
}
Key is a handle to a P-256 key whose private component lives inside the Secure Enclave. The public key is accessible; the private key is not.
Source Files