https://github.com/jedda/ecies
A Go module to implement the ECIES encryption scheme with various keys. Compatible with Apple's Security framework implementation & the Secure Enclave on Apple platforms.
https://github.com/jedda/ecies
apple ecies go security
Last synced: 6 months ago
JSON representation
A Go module to implement the ECIES encryption scheme with various keys. Compatible with Apple's Security framework implementation & the Secure Enclave on Apple platforms.
- Host: GitHub
- URL: https://github.com/jedda/ecies
- Owner: jedda
- License: mit
- Created: 2024-04-09T04:12:37.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-10T02:07:47.000Z (about 2 years ago)
- Last Synced: 2025-05-01T08:46:03.850Z (about 1 year ago)
- Topics: apple, ecies, go, security
- Language: Go
- Homepage:
- Size: 36.1 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# ECIES
[](https://pkg.go.dev/github.com/jedda/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](https://developer.apple.com/documentation/security/1643957-seckeycreateencrypteddata) 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](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/protecting_keys_with_the_secure_enclave) (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](https://github.com/jedda/ecies/blob/main/ecies.go#L154) of the [X9.63-KDF](https://datatracker.ietf.org/doc/html/rfc8418#section-2.1) 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`](https://developer.apple.com/documentation/security/1643957-seckeycreateencrypteddata) and [`SecKeyCreateDecryptedData`](https://developer.apple.com/documentation/security/1644043-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](https://github.com/jedda/ecies-example).
### Companion Swift Playground
A [companion Swift Playground project exists here](https://github.com/jedda/ecies-swift-playground) 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.