dependencies: [
.package(url: "https://github.com/leif-ibsen/SwiftECC", from: "4.0.0"),
]
SwiftECC requires Swift 5.0. It also requires that the Int and UInt types be 64 bit types. SwiftECC uses Apple's CryptoKit framework. Therefore, for macOS the version must be at least 10.15, for iOS the version must be at least 13, and for watchOS the version must be at least 8.
There are 18 predefined NIST domains and 14 predefined Brainpool domains in SwiftECC, and it is possible to create your own characteristic 2, and odd prime characteristic domains.
You need a public key in order to encrypt a message or verify a signature, and you need a private key in order to decrypt a message or sign a message. Given a domain, you can generate public/private key pairs or you can load them from the PEM- or DER encoding of existing keys.
let domain = Domain.instance(curve: .EC384r1)
let (pubKey, privKey) = domain.generateKeyPair()
The private key is simply a random positive integer less than the domain order. The public key is the domain generator point multiplied by the private key. Given a private key, say 'privKey', you can generate the corresponding public key, like
let pubKey = ECPublicKey(privateKey: privKey)
Given a domain, say 'dom' and a curve point, say 'pt', you can generate a public key, like
let pubKey = try ECPublicKey(domain: dom, w: pt)
// Public key encoding - EC384r1 domain
let pubKeyPem =
"""
-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEQW/MahMwMTFjwY95uOEdfBVC7HrQhTGG
TwxiPlgDiARqC6y6EQ1Ajkuhe4A02WOltRYQRXKytzspOR25UfgtagURAwxVFYzR
9cmi6FRmvvq/Tsigd/dAi4FNjniR7/Pg
-----END PUBLIC KEY-----
"""
let pubKey = try ECPublicKey(pem: pubKeyPem)
// Private key encoding in PKCS#8 format - EC384r1 domain
let privKeyPem =
"""
-----BEGIN PRIVATE KEY-----
MIG/AgEAMBAGByqGSM49AgEGBSuBBAAiBIGnMIGkAgEBBDBmpNziSYmGoWwl7apJ
M9ZdDBxkJqmxMScHGXG45ZQXSv7fIuJlsSwxK76nUiiO7gigBwYFK4EEACKhZANi
AARBb8xqEzAxMWPBj3m44R18FULsetCFMYZPDGI+WAOIBGoLrLoRDUCOS6F7gDTZ
Y6W1FhBFcrK3Oyk5HblR+C1qBREDDFUVjNH1yaLoVGa++r9OyKB390CLgU2OeJHv
8+A=
-----END PRIVATE KEY-----
"""
let privKey = try ECPrivateKey(pem: privKeyPem)
// See the key ASN1 structures
print(pubKey)
print(privKey)
giving:
Sequence (2):
Sequence (2):
Object Identifier: 1.2.840.10045.2.1
Object Identifier: 1.3.132.0.34
Bit String (776): 00000100 01000001 01101111 11001100 01101010 00010011 00110000 00110001 00110001 01100011 11000001 10001111 01111001 10111000 11100001 00011101 01111100 00010101 01000010 11101100 01111010 11010000 10000101 00110001 10000110 01001111 00001100 01100010 00111110 01011000 00000011 10001000 00000100 01101010 00001011 10101100 10111010 00010001 00001101 01000000 10001110 01001011 10100001 01111011 10000000 00110100 11011001 01100011 10100101 10110101 00010110 00010000 01000101 01110010 10110010 10110111 00111011 00101001 00111001 00011101 10111001 01010001 11111000 00101101 01101010 00000101 00010001 00000011 00001100 01010101 00010101 10001100 11010001 11110101 11001001 10100010 11101000 01010100 01100110 10111110 11111010 10111111 01001110 11001000 10100000 01110111 11110111 01000000 10001011 10000001 01001101 10001110 01111000 10010001 11101111 11110011 11100000
Sequence (4):
Integer: 1
Octet String (48): 66 a4 dc e2 49 89 86 a1 6c 25 ed aa 49 33 d6 5d 0c 1c 64 26 a9 b1 31 27 07 19 71 b8 e5 94 17 4a fe df 22 e2 65 b1 2c 31 2b be a7 52 28 8e ee 08
[0]:
Object Identifier: 1.3.132.0.34
[1]:
Bit String (776): 00000100 01000001 01101111 11001100 01101010 00010011 00110000 00110001 00110001 01100011 11000001 10001111 01111001 10111000 11100001 00011101 01111100 00010101 01000010 11101100 01111010 11010000 10000101 00110001 10000110 01001111 00001100 01100010 00111110 01011000 00000011 10001000 00000100 01101010 00001011 10101100 10111010 00010001 00001101 01000000 10001110 01001011 10100001 01111011 10000000 00110100 11011001 01100011 10100101 10110101 00010110 00010000 01000101 01110010 10110010 10110111 00111011 00101001 00111001 00011101 10111001 01010001 11111000 00101101 01101010 00000101 00010001 00000011 00001100 01010101 00010101 10001100 11010001 11110101 11001001 10100010 11101000 01010100 01100110 10111110 11111010 10111111 01001110 11001000 10100000 01110111 11110111 01000000 10001011 10000001 01001101 10001110 01111000 10010001 11101111 11110011 11100000
let pw = Bytes("MySecret".utf8)
let domain = Domain.instance(curve: .EC384r1)
let (_, priv) = domain.makeKeyPair()
let encryptedKey = priv.pemEncrypted(password: pw, cipher: .AES256)
print(encryptedKey)
giving (for example):
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIBHjBJBgkqhkiG9w0BBQ0wPDAbBgkqhkiG9w0BBQwwDgQI3id2VFlFxXUCAggA
MB0GCWCGSAFlAwQBKgQQlJJQtcZ23p1Q4fXmvpS6hgSB0DBuxL/sCUc/c9NDhrHK
/R2sbtS7rs5a9zUFwcMNV1nVUCK1SSbaCg8/BxHPfqKlAw4RcnsQtN+YD7hz5pxF
YDcYk4mEZo7ODFkRxhKF7vLsUsRZAl2XYGIJflp03+fAWdsiNisjo/4Y/5xxWvCe
OBzfjRpsDT4HjRgcxTtxrzvInzrJkQwyDBAkPMudIshkPOQ1LEoXhi0gVFl9jGN+
eSLv5Wba2chf/kQcw7R4B3iiE5787wE2fWvvh4ek3oSYcLCvO/gkwgUhyA2hk3rn
01k=
-----END ENCRYPTED PRIVATE KEY-----
The implied encryption parameters are cipher block mode = CBC, iteration count = 2048 and salt = 8 random bytes. The password is simply a byte array, any possible interpretation of it as a string is unspecified. The encrypted private key is compatible with, and is readable by OpenSSL.
Private keys can be created from their PEM encodings in encrypted form. In the example the encrypted private key was created by OpenSSL using the AES-256 cipher in CBC mode with password 'abcd'.
let encryptedPem =
"""
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIHeMEkGCSqGSIb3DQEFDTA8MBsGCSqGSIb3DQEFDDAOBAg7pgGVDlE/xgICCAAw
HQYJYIZIAWUDBAEqBBCFF4KWxWqhOB5Q8dOwdcPkBIGQbuj2TvlhtpMZ3ZhLBBBx
kJfY1l09yNcJNEcvS8RX4/STXZkt5gMBgtY2DvGAKI0wkpbim+kXSjM6/hmNxY5b
jhQapm8l8jbVGkETtYfseZXpvIT5lnBy9KtO8o3OmlRTV3xXu3KeDZakDoimfQ8G
N7SldmFRcz171yMoIQ17ZU95uneZoogsRuMVMVUJXEh7
-----END ENCRYPTED PRIVATE KEY-----
"""
let privKey = try ECPrivateKey(pem: encryptedPem, password: Bytes("abcd".utf8))
print(privKey)
giving:
Sequence (4):
Integer: 1
Octet String (32): 1e 4d c5 de 0f 47 66 6b 7e 4c b8 ee e5 0f f9 6c 4a d3 4f 6f 2e 07 f7 fc e7 c8 24 dd 17 18 fd fa
[0]:
Object Identifier: 1.2.840.10045.3.1.7
[1]:
Bit String (520): 00000100 00101110 10100100 10110110 10001111 11111010 00111111 00000111 01011010 01011101 01110000 01100001 10110000 10101110 01011010 10011100 10001111 00110100 11010000 11111101 10010110 11001110 00101011 10001111 11000001 10101001 11000000 00001101 00011101 11011101 11001011 10101110 10011000 11001011 10000101 01110001 10100010 11100000 01100011 01101010 11110100 11011101 00011000 01011101 10010110 01010101 10110011 00101101 01010000 10100010 00110001 10000100 11011001 00111001 00011000 01100100 10001110 11011111 10011100 00010100 10110101 11011010 00111010 10101100 11111100
SwiftECC can read encrypted private key files provided they were encrypted with one of the ciphers AES-128, AES-192 or AES-256 in CBC mode.
Block Mode | Encrypt | Decrypt |
---|---|---|
GCM | 53 MByte/Sec | 53 MByte/Sec |
ECB | 30 MByte/Sec | 30 MByte/Sec |
CBC | 24 MByte/Sec | 25 MByte/Sec |
CFB | 23 MByte/Sec | 23 MByte/Sec |
CTR | 30 MByte/Sec | 30 MByte/Sec |
OFB | 29 MByte/Sec | 29 MByte/Sec |
AES encryption/decryption key = bytes 0 ..< 16
Nonce = bytes 16 ..< 32
AES encryption/decryption key = bytes 0 ..< 24
Nonce = bytes 24 ..< 40
AES encryption/decryption key = bytes 0 ..< 32
Nonce = bytes 32 ..< 48
AES encryption/decryption key = bytes 0 ..< 16
HMAC key = bytes 16 ..< 48
AES encryption/decryption key = bytes 0 ..< 24
HMAC key = bytes 24 ..< 56
AES encryption/decryption key = bytes 0 ..< 32
HMAC key = bytes 32 ..< 64
The AES key and HMAC key can be retrieved with the ECPrivateKey method 'getKeyAndMac'.
For block modes CBC, CFB, CTR, and OFB the initialization vector (IV) is 16 zero bytes.
import SwiftECC
// You need a public key to encrypt a message and the corresponding private key to decrypt it,
// for example from the EC163k1 domain
let pemPublic163k1 =
"""
-----BEGIN PUBLIC KEY-----
MEAwEAYHKoZIzj0CAQYFK4EEAAEDLAAEA6txn7CCae0d9AiGj3Rk5m9XflTCB81oe1fKZi4F4oip
SF2u79k8TD5J
-----END PUBLIC KEY-----
"""
let pemPrivate163k1 =
"""
-----BEGIN EC PRIVATE KEY-----
MFICAQEEFNfflqz2oOd9WpxuMZ9wJTFO1sjgoAcGBSuBBAABoS4DLAAEA6txn7CCae0d9AiGj3Rk
5m9XflTCB81oe1fKZi4F4oipSF2u79k8TD5J
-----END EC PRIVATE KEY-----
"""
let text = "The quick brown fox jumps over the lazy dog!"
do {
let pubKey = try ECPublicKey(pem: pemPublic163k1)
let privKey = try ECPrivateKey(pem: pemPrivate163k1)
let encryptedData = pubKey.encrypt(msg: text.data(using: .utf8)!, cipher: .AES128)
let decryptedData = try privKey.decrypt(msg: encryptedData, cipher: .AES128)
print(String(data: decryptedData, encoding: .utf8)!)
} catch {
print("\(error)")
}
giving
The quick brown fox jumps over the lazy dog!
import SwiftECC
let plainText = "Hi, there!"
let aaData = "This is the additional authenticated data"
let (pub, priv) = Domain.instance(curve: .EC256k1).makeKeyPair()
let cipherText1 = pub.encryptChaCha(msg: Bytes(plainText.utf8), aad: Bytes(aaData.utf8))
let cipherText2 = pub.encryptAESGCM(msg: Bytes(plainText.utf8), cipher: .AES128, aad: Bytes(aaData.utf8))
do {
let text1 = try priv.decryptChaCha(msg: cipherText1, aad: Bytes(aaData.utf8))
print(String(bytes: text1, encoding: .utf8)!)
let text2 = try priv.decryptAESGCM(msg: cipherText2, cipher: .AES128, aad: Bytes(aaData.utf8))
print(String(bytes: text2, encoding: .utf8)!)
} catch {
print("Exception: \(error)")
}
giving:
Hi, there!
Hi, there!
The encryption and decryption speed for domain EC256k1 (the bitcoin domain) measured on an iMac 2021, Apple M1 chip are shown below - units are Megabytes per second.
Algorithm | Encrypt | Decrypt |
---|---|---|
ChaCha20/Poly1305 | 500 MByte/Sec | 425 MByte/Sec |
AES-128/GCM | 2000 MByte/Sec | 1200 MByte/Sec |
Encryption/decryption key = bytes 0 ..< 32
Nonce = bytes 32 ..< 44
AES encryption/decryption key = bytes 0 ..< 16
Nonce = bytes 16 ..< 28
AES encryption/decryption key = bytes 0 ..< 24
Nonce = bytes 24 ..< 36
AES encryption/decryption key = bytes 0 ..< 32
Nonce = bytes 32 ..< 44
The message digest used in the process is determined from the domain field size as follows:
import SwiftECC
// Get a predefined domain - for example brainpool BP160r1
let domain = Domain.instance(curve: .BP160r1)
// Create your own keys
let (pubKey, privKey) = domain.makeKeyPair()
// See how they look
print(pubKey.asn1)
print(privKey.asn1)
// Store them in PEM format for future use
let pubPEM = pubKey.pem
let privPEM = privKey.pem
let message = "The quick brown fox jumps over the lazy dog!".data(using: .utf8)!
let sig = privKey.sign(msg: message)
let ok = pubKey.verify(signature: sig, msg: message)
print("Signature is", ok ? "good" : "wrong")
giving (for example):
Sequence (2):
Sequence (2):
Object Identifier: 1.2.840.10045.2.1
Object Identifier: 1.3.36.3.3.2.8.1.1.1
Bit String (328): 00000100 00000011 00000111 00110011 01010100 00000001 10111100 01101111 10100001 01001000 11101000 01111100 10001111 00000110 00010010 11100111 11111010 10010001 00100100 01001000 11000110 01110001 00110100 01001000 10011110 01011110 11000000 10010001 01000110 01011010 01001110 01110000 00011011 01010111 10101011 01101010 00011011 01101100 01100100 01000100 01111101
Sequence (4):
Integer: 1
Octet String (20): 32 96 e0 c4 d7 f5 cb 03 0c 95 63 b1 a2 c1 2f 64 4c dc d6 4c
[0]:
Object Identifier: 1.3.36.3.3.2.8.1.1.1
[1]:
Bit String (328): 00000100 00000011 00000111 00110011 01010100 00000001 10111100 01101111 10100001 01001000 11101000 01111100 10001111 00000110 00010010 11100111 11111010 10010001 00100100 01001000 11000110 01110001 00110100 01001000 10011110 01011110 11000000 10010001 01000110 01011010 01001110 01110000 00011011 01010111 10101011 01101010 00011011 01101100 01100100 01000100 01111101
Signature is good
import SwiftECC
do {
let domain = Domain.instance(curve: .EC256r1)
// Party A's keys
let (pubA, privA) = domain.makeKeyPair()
// Party B's keys
let (pubB, privB) = domain.makeKeyPair()
let secretA = try privA.sharedSecret(pubKey: pubB)
let secretB = try privB.sharedSecret(pubKey: pubA)
print(secretA)
print(secretB)
} catch {
print("Exception: \(error)")
}
giving (for example):
[44, 218, 188, 109, 139, 24, 227, 22, 116, 197, 147, 194, 138, 107, 105, 11, 236, 67, 236, 110, 42, 26, 250, 151, 111, 236, 60, 98, 210, 121, 243, 44]
[44, 218, 188, 109, 139, 24, 227, 22, 116, 197, 147, 194, 138, 107, 105, 11, 236, 67, 236, 110, 42, 26, 250, 151, 111, 236, 60, 98, 210, 121, 243, 44]
import SwiftECC
do {
let domain = Domain.instance(curve: .EC256r1)
// Party A's keys
let (pubA, privA) = domain.makeKeyPair()
// Party B's keys
let (pubB, privB) = domain.makeKeyPair()
let info: Bytes = [1, 2, 3]
let secretA = try privA.x963KeyAgreement(pubKey: pubB, length: 16, md: .SHA2_256, sharedInfo: info)
let secretB = try privB.x963KeyAgreement(pubKey: pubA, length: 16, md: .SHA2_256, sharedInfo: info)
print(secretA)
print(secretB)
} catch {
print("Exception: \(error)")
}
giving (for example):
[92, 161, 137, 44, 47, 30, 6, 26, 43, 183, 199, 130, 19, 254, 232, 106]
[92, 161, 137, 44, 47, 30, 6, 26, 43, 183, 199, 130, 19, 254, 232, 106]
For the key agreement to work, the two parties must agree on which domain, which message digest and which shared information (possibly none) to use.
import SwiftECC
do {
let domain = Domain.instance(curve: .EC256r1)
// Party A's keys
let (pubA, privA) = domain.makeKeyPair()
// Party B's keys
let (pubB, privB) = domain.makeKeyPair()
let info: Bytes = [1, 2, 3]
let salt: Bytes = [4, 5, 6]
let secretA = try privA.hkdfKeyAgreement(pubKey: pubB, length: 16, md: .SHA2_256, sharedInfo: info, salt: salt)
let secretB = try privB.hkdfKeyAgreement(pubKey: pubA, length: 16, md: .SHA2_256, sharedInfo: info, salt: salt)
print(secretA)
print(secretB)
} catch {
print("Exception: \(error)")
}
giving (for example):
[202, 36, 31, 96, 207, 220, 135, 77, 130, 41, 214, 139, 214, 30, 106, 180]
[202, 36, 31, 96, 207, 220, 135, 77, 130, 41, 214, 139, 214, 30, 106, 180]
For the key agreement to work, the two parties must agree on which domain, which message digest, which shared information (possibly none) and which salt (possibly none) to use.
To convert CryptoKit keys - e.g. ckPubKey, ckPrivKey - to the corresponding SwiftECC keys:
let eccPubKey = try ECPublicKey(pem: ckPubKey.pemRepresentation)
let eccPrivKey = try ECPrivateKey(pem: ckPrivKey.pemRepresentation)
To convert SwiftECC keys - e.g. eccPubKey, eccPrivKey - to the corresponding CryptoKit keys:
let ckPubKey = try P256.KeyAgreement.PublicKey(pemRepresentation: eccPubKey.pem)
let ckPrivKey = try P256.KeyAgreement.PrivateKey(pemRepresentation: eccPrivKey.pem)
This is example 3.5 from [GUIDE]. It shows how to make your own prime characteristic domain.
import SwiftECC
import BigInt
// Create the domain
let domain = try Domain.instance(name: "EC29", p: BInt(29), a: BInt(4), b: BInt(20), gx: BInt(1), gy: BInt(5), order: BInt(37), cofactor: 1)
let p1 = Point(BInt(5), BInt(22))
let p2 = Point(BInt(16), BInt(27))
print("p1 + p2 =", try domain.addPoints(p1, p2))
print("p1 * 2 =", try domain.multiplyPoint(p1, BInt(2)))
// Inspect the domain - please refer [SEC 1] appendix C.2
print(domain.asn1Explicit())
giving
p1 + p2 = Point(13, 6)
p1 * 2 = Point(14, 6)
Sequence (6):
Integer: 1
Sequence (2):
Object Identifier: 1.2.840.10045.1.1
Integer: 29
Sequence (2):
Octet String (1): 04
Octet String (1): 14
Octet String (3): 04 01 05
Integer: 37
Integer: 1
This is example 3.6 from [GUIDE]. It shows how to make your own characteristic 2 domain.
import SwiftECC
import BigInt
// Reduction polynomial for x^4 + x^1 + 1
let rp = RP(4, 1)
// Create the domain
let domain = try Domain.instance(name: "EC4", rp: rp, a: BInt(8), b: BInt(9), gx: BInt(1), gy: BInt(1), order: BInt(22), cofactor: 2)
let p1 = Point(BInt(2), BInt(15))
let p2 = Point(BInt(12), BInt(12))
print("p1 + p2 =", try domain.addPoints(p1, p2))
print("p1 * 2 =", try domain.multiplyPoint(p1, BInt(2)))
// Inspect the domain - please refer [SEC 1] appendix C.2
print(domain.asn1Explicit())
giving
p1 + p2 = Point(1, 1)
p1 * 2 = Point(11, 2)
Sequence (6):
Integer: 1
Sequence (2):
Object Identifier: 1.2.840.10045.1.2
Sequence (2):
Integer: 4
Integer: 1
Sequence (2):
Octet String (1): 08
Octet String (1): 09
Octet String (3): 04 01 01
Integer: 22
Integer: 2
Curve | Sign | Verify | Keypair Generation |
---|---|---|---|
brainpoolP160r1 | 0.7 mSec | 1.3 mSec | 2.9 mSec |
brainpoolP160t1 | 0.7 mSec | 1.4 mSec | 2.9 mSec |
brainpoolP192r1 | 0.96 mSec | 1.8 mSec | 3.9 mSec |
brainpoolP192t1 | 0.96 mSec | 1.9 mSec | 3.9 mSec |
brainpoolP224r1 | 1.3 mSec | 2.6 mSec | 5.7 mSec |
brainpoolP224t1 | 1.3 mSec | 2.6 mSec | 5.7 mSec |
brainpoolP256r1 | 1.7 mSec | 3.3 mSec | 7.4 mSec |
brainpoolP256t1 | 1.7 mSec | 3.3 mSec | 7.4 mSec |
brainpoolP320r1 | 2.9 mSec | 5.7 mSec | 13 mSec |
brainpoolP320t1 | 2.9 mSec | 5.5 mSec | 13 mSec |
brainpoolP384r1 | 4.5 mSec | 8.6 mSec | 21 mSec |
brainpoolP384t1 | 4.4 mSec | 8.7 mSec | 21 mSec |
brainpoolP512r1 | 9.2 mSec | 19 mSec | 44 mSec |
brainpoolP512t1 | 9.3 mSec | 18 mSec | 44 mSec |
secp192k1 | 0.96 mSec | 1.8 mSec | 4.0 mSec |
secp192r1 | 0.96 mSec | 1.9 mSec | 3.9 mSec |
secp224k1 | 1.3 mSec | 2.6 mSec | 5.8 mSec |
secp224r1 | 1.3 mSec | 2.6 mSec | 5.7 mSec |
secp256k1 | 1.7 mSec | 3.2 mSec | 7.4 mSec |
secp256r1 | 1.7 mSec | 3.3 mSec | 7.5 mSec |
secp384r1 | 4.5 mSec | 8.9 mSec | 21 mSec |
secp521r1 | 9.8 mSec | 19 mSec | 47 mSec |
sect163k1 | 1.2 mSec | 2.2 mSec | 5.1 mSec |
sect163r2 | 1.2 mSec | 2.3 mSec | 5.1 mSec |
sect233k1 | 2.3 mSec | 4.5 mSec | 11 mSec |
sect233r1 | 2.3 mSec | 4.5 mSec | 11 mSec |
sect283k1 | 3.5 mSec | 7.0 mSec | 17 mSec |
sect283r1 | 3.5 mSec | 7.1 mSec | 17 mSec |
sect409k1 | 8.0 mSec | 16 mSec | 41 mSec |
sect409r1 | 8.0 mSec | 16 mSec | 42 mSec |
sect571k1 | 17 mSec | 35 mSec | 92 mSec |
sect571r1 | 17 mSec | 34 mSec | 92 mSec |
The SwiftECC package depends on the ASN1 and BigInt packages
dependencies: [
.package(url: "https://github.com/leif-ibsen/ASN1", from: "2.1.0"),
.package(url: "https://github.com/leif-ibsen/BigInt", from: "1.13.0"),
],
Algorithms from the following books and papers have been used in the implementation. There are references in the source code where appropriate.
link |
Stars: 60 |
Last commit: 5 weeks ago |
About SwiftECC release 4.0.0:
The Hybrid Public Key Encryption (HPKE) functionality is removed from SwiftECC.
In order to achieve a cleaner division of functionality it is now implemented in its own package SwiftHPKE.
The remaining functionality in SwiftECC is unchanged.
SwiftECC release 3.9.0 which includes HPKE still exists.
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics