ecies

README

ECIES

This package and Go module implements the functions required to encrypt and decrypt data using the Elliptic Curve Integrated Encryption Scheme with X9.63 Key Derivation, and specifically; Apple's implementation as part of Security.framework on iOS & macOS.

It was conceived to simplify the process of exchanging secure encrypted data cross-platform between a Go application and Apple devices. It has been designed to be capable of exchanging encrypted data using keys protected by the Secure Enclave on Apple platforms (with NIST P-256 elliptic curve keys) as well as other curves supported by ecdh.Curve (P-384, P-521, X25519).

This package includes an implementation of the X9.63-KDF Key Derivation Function used by Apple's framework to derive shared AES keys and an optional IV/nonce for GCM.

EC & AES Key Sizes

This package follows Apple's behaviour when it comes to AES key size selection. For <=256 bit EC keys, 16 bits of the derived key are used for AES, leading to AES-128 being used for the symmetric encryption. Where EC key sizes >256 bits are used (384, 521), 32 bits of the derived key are used for AES, resulting in AES-256 symmetric encryption.

Ciphertext Format

Ciphertext is outputted and expected in the following format (to match that outputted and expected by SecKeyCreateEncryptedData and SecKeyCreateDecryptedData):

[ephemeral public key (raw bytes)] + [message ciphertext] + [AES-GCM authentication tag]

Example Usage

Example code showing how to encrypt and decrypt is available here.

Companion Swift Playground

A companion Swift Playground project exists here with instructions and examples of how to encrypt and decrypt data compatible with this package.

Unit Tests

A series of unit tests are included to test the fundamentals as well as some concrete encrypt and decrypt operations. The test TestExternalDecryptSuccess includes test data encrypted by Security.framework on macOS with detailed examples as to configuration and algorithm choice.

Documentation

Overview

Package ecies implements the functions required to encrypt and decrypt data using the Elliptic Curve Integrated Encryption Scheme with X9.63 Key Derivation, and specifically; Apple's implementation as part of the Security framework on iOS & macOS.

Index

• func DecryptECIESX963AESGCM(algorithm hash.Hash, variableIV bool, key *ecdh.PrivateKey, ciphertext []byte, ...) ([]byte, error)
• func DeriveX963KDF(algorithm hash.Hash, length int, key []byte, shared []byte) ([]byte, error)
• func EncryptECIESX963AESGCM(algorithm hash.Hash, variableIV bool, key *ecdh.PublicKey, plaintext []byte, ...) ([]byte, error)

Functions

func DecryptECIESX963AESGCM

func DecryptECIESX963AESGCM(algorithm hash.Hash, variableIV bool, key *ecdh.PrivateKey, ciphertext []byte, additionalData []byte) ([]byte, error)

DecryptECIESX963AESGCM takes a ciphertext []byte slice along with the following parameters and decrypts it to plaintext. The ciphertext data can be created by SecKeyCreateEncryptedData() on Apple platforms.

• algorithm is the underlying hashing algorithm used by the KDF
• variableIV determines if additional bits from the KDF are used as a nonce/IV for AES-GCM
• key is the ecdh.PublicKey used to perform ECDH and determine the shared key
• additionalData is optional data used by AES-GCM to authenticate (it is not used in Apple's implementation)

If successful, it returns plaintext data as a []byte slice, or an error if it fails.

func DeriveX963KDF

func DeriveX963KDF(algorithm hash.Hash, length int, key []byte, shared []byte) ([]byte, error)

DeriveX963KDF derives a key using the ANSI-X9.63-KDF key derivation function outlined in RFC 8418 2.1. It returns a byte slice of chosen length, performing multiple rounds of the chosen hashing algorithm if required.

func EncryptECIESX963AESGCM

func EncryptECIESX963AESGCM(algorithm hash.Hash, variableIV bool, key *ecdh.PublicKey, plaintext []byte, additionalData []byte) ([]byte, error)

EncryptECIESX963AESGCM takes a plaintext []byte slice along with the following parameters and encrypts it to ciphertext. The returned ciphertext data can be decrypted by SecKeyCreateDecryptedData() on Apple platforms.

• algorithm is the underlying hashing algorithm used by the KDF
• variableIV determines if additional bits from the KDF are used as a nonce/IV for AES-GCM
• key is the ecdh.PublicKey used to perform ECDH and determine the shared key
• additionalData is optional data used by AES-GCM to authenticate (it is not used in Apple's implementation)

If successful, it returns ciphertext data as a []byte slice, or an error if it fails.