Merge branch 'develop'

Author: dm-zharov

README.md

@@ -172,26 +172,35 @@ if case let .persistentReference(data) = try keychain.store(
 
 #### CryptoKit
 
-`SwiftSecurity` lets you natively store `CryptoKit` keys as native `SecKey` instances. [Keys supporting such conversion](https://developer.apple.com/documentation/cryptokit/storing_cryptokit_keys_in_the_keychain), like `P256`/`P384`/`P521.PrivateKey`, conform to `SecKeyConvertible` protocol.
+`SwiftSecurity` lets you natively store `CryptoKit` keys as native `SecKey` instances. [Keys supporting such conversion](https://developer.apple.com/documentation/cryptokit/storing_cryptokit_keys_in_the_keychain), like `P256`/`P384`/`P521`, conform to `SecKeyConvertible` protocol.
 
 ```swift
 // Store private key
 let privateKey = P256.KeyAgreement.PrivateKey()
-try keychain.store(privateKey, query: .privateKey(for: "Alice"))
+try keychain.store(privateKey, query: .key(for: "Alice"))
 
 // Retrieve private key (+ public key)
 let privateKey: P256.KeyAgreement.PrivateKey? = try keychain.retrieve(.privateKey(for: "Alice"))
-let publicKey = privateKey.publicKey
+let publicKey = privateKey.publicKey /* Recommended */
+
+// Store public key. Not recommended, as you can generate it
+try keychain.store(
+    publicKey,
+    query: .key(for: "Alice", descriptor: .ecsecPrimeRandom(.public))
+)
 ```
 
-Other key types, like `Curve25519.PrivateKey`, `SymmetricKey`, `SecureEnclave.P256.PrivateKey`, have no direct keychain corollary. In particular, `SecureEnclave.P256` is a persistent reference to the key inside `Secure Enclave`, not the key itself. These keys conform to `SecDataConvertible`, so store them as follows:
+Other key types from `CryptoKit`, like `SymmetricKey`, `Curve25519`, `SecureEnclave.P256`, have no direct keychain corollary. In particular, `SecureEnclave.P256` is a persistent reference to the key inside `Secure Enclave`, not the key itself. These keys conform to `SecDataConvertible`, so store them as follows:
 
 ```swift
 // Store symmetric key
 let symmetricKey = SymmetricKey(size: .bits256)
 try keychain.store(symmetricKey, query: .credential(for: "Chat"))
 ```
 
+> [!NOTE]
+> `SecKey` is intended for asymmetric key storage. Only `ECPrimeRandom` (`CryptoKit -> P256/384/512`) and `RSA` algorithms are supported. See [On Cryptographic Key Formats](https://developer.apple.com/forums/thread/680554) for more info.
+
 #### Certificate
 
 DER-Encoded X.509 Certificate.
@@ -207,9 +216,9 @@ try keychain.store(certificate, query: .certificate(for: "Root CA"))
 
 If your project uses [apple/swift-certificates](https://github.com/apple/swift-certificates) package, the `Certificate` will offer more functionality. In case of `Swift Package Manager` dependency resolve issues, copy `SecCertificateConvertible` conformance directly to your project.
 
-#### Identity
+#### Digital Identity
 
-A digital identity (`SecIdentity`) is the combination of a certificate and the private key that matches the public key within certificate.
+A digital identity is the combination of a certificate and the private key that matches the public key within certificate.
 
 ```swift
 // Import digital identity from `PKCS #12` data
@@ -369,18 +378,19 @@ You can store, retrieve, and remove various types of values.
 
 ```swift
 Foundation:
-    - Data // GenericPassword, InternetPassword
-    - String // GenericPassword, InternetPassword
+    - Data /* GenericPassword, InternetPassword */
+    - String /* GenericPassword, InternetPassword */
 CryptoKit:
-    - SymmetricKey // GenericPassword
-    - Curve25519 -> PrivateKey // GenericPassword
-    - SecureEnclave.P256 -> PrivateKey // GenericPassword (SE's Key Data is Persistent Reference)
-    - P256, P384, P521 -> PrivateKey // SecKey (ANSI x9.63 Elliptic Curves)
+    - SymmetricKey /* GenericPassword */
+    - Curve25519 -> PrivateKey /* GenericPassword */
+    - SecureEnclave.P256 -> PrivateKey /* GenericPassword (SE's Key Data is Persistent Reference) */
+    - P256, P384, P521 -> PrivateKey /* SecKey (ANSI x9.63 Elliptic Curves) */
 X509 (external package `apple/swift-certificates`):
-    - Certificate // SecCertificate
+    - Certificate /* SecCertificate */
 SwiftSecurity:
-    - Certificate // SecCertificate (Drop-in replacement for X509.Certificate)
-    - PKCS12.Blob // Import as SecIdentity (SecCertificate and SecKey)
+    - Certificate /* SecCertificate */
+    - PKCS12.Blob: /* Import as SecIdentity */
+        - DigitalIdentity /* SecIdentity (The Pair of SecCertificate and SecKey) */
 ```
 
 To add support for custom types, you can extend them by conforming to the following protocols.
@@ -456,6 +466,7 @@ The framework’s default behavior provides a reasonable balance between conveni
 * [Sharing access to keychain items among a collection of apps](https://developer.apple.com/documentation/security/keychain_services/keychain_items/sharing_access_to_keychain_items_among_a_collection_of_apps/)
 * [Storing CryptoKit Keys in the Keychain](https://developer.apple.com/documentation/cryptokit/storing_cryptokit_keys_in_the_keychain)
 * [TN3137: On Mac keychain APIs and implementations](https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains)
+* [On Cryptographic Key Formats](https://developer.apple.com/forums/thread/680554)
 * [SecItem: Fundamentals](https://developer.apple.com/forums/thread/724023)
 * [SecItem: Pitfalls and Best Practices](https://developer.apple.com/forums/thread/724013)
 

Sources/SwiftSecurity/CryptoKit/SecCertificateConvertible.swift

@@ -10,42 +10,21 @@ import Security
 
 // MARK: - DER-Encoded X.509 Certificate
 
-public protocol SecCertificateConvertible {
+public protocol SecCertificateConvertible: SecCertificateRepresentable {
     /// Creates a certificate from an DER-encoded X.509 data representation.
     init<Bytes>(derRepresentation: Bytes) throws where Bytes: ContiguousBytes
 
-    /// Creates a certificate from a raw representation.
-    init(rawRepresentation certificateRef: SecCertificate)
-    
     /// A DER-Encoded X.509 data representation.
     var derRepresentation: Data { get }
-    
-    /// A raw representation of the X.509 Certificate.
-    var rawRepresentation: SecCertificate { get }
 }
 
-extension SecCertificateConvertible {
-    public init(rawRepresentation certificateRef: SecCertificate) {
-        do {
-            try self.init(derRepresentation: SecCertificateCopyData(certificateRef) as Data)
-        } catch{
-            fatalError(error.localizedDescription)
-        }
-    }
-
-    public var rawRepresentation: SecCertificate {
-        guard let certificateRef = SecCertificateCreateWithData(nil, derRepresentation as CFData) else {
-            fatalError("derRepresentation is not a valid DER-encoded data")
-        }
-        return certificateRef
-    }
-}
+extension SwiftSecurity.Certificate: SecCertificateConvertible { }
 
 #if canImport(X509)
 import X509
 import SwiftASN1
 
-extension Certificate: SecCertificateConvertible {
+extension X509.Certificate: SecCertificateConvertible {
     public init<D>(derRepresentation data: D) throws where D: ContiguousBytes {
         try self.init(derEncoded: data.withUnsafeBytes { bytes in
             let contiguousBytes = bytes.bindMemory(to: UInt8.self)
@@ -64,24 +43,32 @@ extension Certificate: SecCertificateConvertible {
         }
     }
 }
-#else
-public struct Certificate: SecCertificateConvertible {
-    public let derRepresentation: Data
-    public let rawRepresentation: SecCertificate
+#endif
+
+// MARK: - SecCertificate
+
+public protocol SecCertificateRepresentable {
+    /// Creates a certificate from a raw representation.
+    init(certificate secCertificate: SecCertificate)
 
-    public init<Bytes>(derRepresentation data: Bytes) throws where Bytes : ContiguousBytes {
-        self.derRepresentation = data.withUnsafeBytes { (bytes: UnsafeRawBufferPointer) in
-            return Data(bytes)
-        }
-        guard let certificateRef = SecCertificateCreateWithData(nil, derRepresentation as CFData) else {
-            throw SwiftSecurityError.invalidParameter
+    /// A certificate reference.
+    var secCertificate: SecCertificate { get }
+}
+
+extension SecCertificateConvertible {
+    public init(certificate secCertificate: SecCertificate) {
+        do {
+            try self.init(derRepresentation: SecCertificateCopyData(secCertificate) as Data)
+        } catch{
+            fatalError(error.localizedDescription)
         }
-        self.rawRepresentation = certificateRef
     }
-    
-    public init(rawRepresentation certificateRef: SecCertificate) {
-        self.derRepresentation = SecCertificateCopyData(certificateRef) as Data
-        self.rawRepresentation = certificateRef
+
+    public var secCertificate: SecCertificate {
+        if let secCertificate = SecCertificateCreateWithData(nil, derRepresentation as CFData) {
+            return secCertificate
+        } else {
+            fatalError("derRepresentation is not a valid DER-encoded data")
+        }
     }
 }
-#endif

Sources/SwiftSecurity/CryptoKit/SecDataConvertible.swift

@@ -19,7 +19,9 @@ public protocol SecDataConvertible {
 // MARK: - CryptoKit
 
 extension Curve25519.KeyAgreement.PrivateKey: SecDataConvertible {}
+extension Curve25519.KeyAgreement.PublicKey: SecDataConvertible {}
 extension Curve25519.Signing.PrivateKey: SecDataConvertible {}
+extension Curve25519.Signing.PublicKey: SecDataConvertible {}
 
 extension SymmetricKey: SecDataConvertible {
     public init<D>(rawRepresentation data: D) throws where D: ContiguousBytes {
@@ -60,7 +62,7 @@ extension SecureEnclave.P256.Signing.PrivateKey: SecDataConvertible {
     }
 }
 
-// MARK: - Other Data Types
+// MARK: - Foundation
 
 extension Data: SecDataConvertible {
     public init<D>(rawRepresentation data: D) throws where D : ContiguousBytes {

Sources/SwiftSecurity/CryptoKit/SecIdentityConvertible.swift

@@ -7,36 +7,22 @@
 
 import Foundation
 
-public protocol SecIdentityConvertible {
-    /// Creates an identity from a raw representation.
-    init(rawRepresentation: SecIdentity)
-    
-    /// A raw representation of the identity.
-    var rawRepresentation: SecIdentity { get throws }
+public protocol SecIdentityConvertible<Certificate>: SecIdentityRepresentable {
+    associatedtype Certificate: SecCertificateConvertible
 }
 
-public struct Identity: SecIdentityConvertible {
-    /// Creates an identity from a raw representation.
-    public init(rawRepresentation identityRef: SecIdentity) {
-        self.rawRepresentation = identityRef
-    }
-    
-    /// Creates an identity from a raw representation.
-    public let rawRepresentation: SecIdentity
+// MARK: - SwiftSecurity
+
+extension DigitalIdentity: SecIdentityConvertible {
+    public typealias Certificate = SwiftSecurity.Certificate
 }
 
-#if os(macOS)
-import Security
+// MARK: - SecIdentity
 
-extension Identity {
-    public init?<T: SecCertificateConvertible>(certificate: T) {
-        var identityRef: SecIdentity?
-        SecIdentityCreateWithCertificate(nil, certificate.rawRepresentation, &identityRef)
-        if let identityRef {
-            self.rawRepresentation = identityRef
-        } else {
-            return nil
-        }
-    }
+public protocol SecIdentityRepresentable {
+    /// Creates an identity from a raw representation.
+    init(identity secIdentity: SecIdentity)
+    
+    /// An identity reference.
+    var secIdentity: SecIdentity { get throws }
 }
-#endif

Sources/SwiftSecurity/CryptoKit/SecKeyConvertible.swift

@@ -10,17 +10,112 @@ import CryptoKit
 
 // MARK: - NIST Key
 
-public protocol SecKeyConvertible {
+public protocol SecKeyConvertible: SecKeyRepresentable {
     /// Creates a key from an X9.63 representation.
     init<Bytes>(x963Representation: Bytes) throws where Bytes: ContiguousBytes
 
     /// An X9.63 representation of the key.
     var x963Representation: Data { get }
 }
 
-extension P256.Signing.PrivateKey: SecKeyConvertible {}
-extension P256.KeyAgreement.PrivateKey: SecKeyConvertible {}
-extension P384.Signing.PrivateKey: SecKeyConvertible {}
-extension P384.KeyAgreement.PrivateKey: SecKeyConvertible {}
-extension P521.Signing.PrivateKey: SecKeyConvertible {}
-extension P521.KeyAgreement.PrivateKey: SecKeyConvertible {}
+// MARK: - CryptoKit
+
+extension P256.Signing.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P256.Signing.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+extension P256.KeyAgreement.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P256.KeyAgreement.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+extension P384.Signing.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P384.Signing.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+extension P384.KeyAgreement.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P384.KeyAgreement.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+extension P521.Signing.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P521.Signing.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+extension P521.KeyAgreement.PrivateKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+}
+
+extension P521.KeyAgreement.PublicKey: SecKeyConvertible {
+    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+}
+
+// MARK: - SecKey
+
+public protocol SecKeyRepresentable {
+    /// A key descriptor for storage.
+    var descriptor: SecKeyDescriptor { get }
+    
+    /// A key reference.
+    var secKey: SecKey { get throws }
+}
+
+extension SecKeyConvertible {
+    public var secKey: SecKey {
+        get throws {
+            precondition(descriptor.keyType == .ecsecPrimeRandom, "RSA is currently unsupported")
+            var error: Unmanaged<CFError>?
+            guard let secKey: SecKey = SecKeyCreateWithData(x963Representation as CFData, [
+                kSecAttrKeyType: descriptor.keyType.rawValue,
+                kSecAttrKeyClass: descriptor.keyClass.rawValue
+            ] as CFDictionary, &error) else {
+                if let error = error?.takeRetainedValue() {
+                    throw SwiftSecurityError(error: error)
+                }
+                throw SwiftSecurityError.invalidParameter
+            }
+            return secKey
+        }
+    }
+}
+
+public struct SecKeyDescriptor {
+    public var keyType: KeyType
+    public var keyClass: KeyClass
+    
+    public static func rsa(_ keyClass: KeyClass) -> SecKeyDescriptor {
+        switch keyClass {
+        case .public:
+            SecKeyDescriptor(keyType: .rsa, keyClass: .public)
+        case .private:
+            SecKeyDescriptor(keyType: .rsa, keyClass: .private)
+        }
+    }
+    
+    public static func ecsecPrimeRandom(_ keyClass: KeyClass) -> SecKeyDescriptor {
+        switch keyClass {
+        case .public:
+            SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .public)
+        case .private:
+            SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .private)
+        }
+    }
+}