Merge branch 'develop'

Author: dm-zharov

README.md

@@ -186,7 +186,7 @@ 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))
+    query: .key(for: "Alice", descriptor: .ecPublicKey)
 )
 ```
 

Sources/SwiftSecurity/CryptoKit/SecCertificateConvertible.swift

@@ -48,7 +48,7 @@ extension X509.Certificate: SecCertificateConvertible {
 // MARK: - SecCertificate
 
 public protocol SecCertificateRepresentable {
-    /// Creates a certificate from a raw representation.
+    /// Creates a certificate from a reference.
     init(certificate secCertificate: SecCertificate)
 
     /// A certificate reference.

Sources/SwiftSecurity/CryptoKit/SecKeyConvertible.swift

@@ -20,59 +20,61 @@ public protocol SecKeyConvertible: SecKeyRepresentable {
 
 // MARK: - CryptoKit
 
+/// NIST P-256 (also known as `secp256r1` /  `prime256r1` / `prime256v1`).
+
 extension P256.Signing.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
-
 extension P256.Signing.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
 extension P256.KeyAgreement.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
-
 extension P256.KeyAgreement.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
+/// NIST P-384 (also known as `secp384r1` ).
+
 extension P384.Signing.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
 
 extension P384.Signing.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
 extension P384.KeyAgreement.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
 
 extension P384.KeyAgreement.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
+/// NIST P-521 (also known as `secp521r1` ).
+
 extension P521.Signing.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
-
 extension P521.Signing.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
 extension P521.KeyAgreement.PrivateKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.private) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPrivateKey }
 }
-
 extension P521.KeyAgreement.PublicKey: SecKeyConvertible {
-    public var descriptor: SecKeyDescriptor { .ecsecPrimeRandom(.public) }
+    public var secKeyDescriptor: SecKeyDescriptor { .ecPublicKey }
 }
 
 // MARK: - SecKey
 
 public protocol SecKeyRepresentable {
     /// A key descriptor for storage.
-    var descriptor: SecKeyDescriptor { get }
+    var secKeyDescriptor: SecKeyDescriptor { get }
 
     /// A key reference.
     var secKey: SecKey { get throws }
@@ -81,11 +83,19 @@ public protocol SecKeyRepresentable {
 extension SecKeyConvertible {
     public var secKey: SecKey {
         get throws {
-            precondition(descriptor.keyType == .ecsecPrimeRandom, "RSA is currently unsupported")
+            let keyData: Data
+            switch secKeyDescriptor.keyType {
+            case .ecsecPrimeRandom:
+                keyData = x963Representation
+            case .rsa:
+                // override and use data in PKCS #1 format
+                throw SwiftSecurityError.unimplemented
+            }
+
             var error: Unmanaged<CFError>?
-            guard let secKey: SecKey = SecKeyCreateWithData(x963Representation as CFData, [
-                kSecAttrKeyType: descriptor.keyType.rawValue,
-                kSecAttrKeyClass: descriptor.keyClass.rawValue
+            guard let secKey: SecKey = SecKeyCreateWithData(keyData as CFData, [
+                kSecAttrKeyType: secKeyDescriptor.keyType.rawValue,
+                kSecAttrKeyClass: secKeyDescriptor.keyClass.rawValue
             ] as CFDictionary, &error) else {
                 if let error = error?.takeRetainedValue() {
                     throw SwiftSecurityError(error: error)
@@ -101,21 +111,19 @@ 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)
-        }
-    }
+    /// A private key for elliptic curve cryptography. Suitable for `P256`/`P384`/`P521` keys from `CryptoKit`.
+    public static let ecPrivateKey = SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .private)
+    /// A public key for elliptic curve cryptography. Suitable for `P256`/`P384`/`P521` keys from `CryptoKit`.
+    public static let ecPublicKey = SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .public)
 
-    public static func ecsecPrimeRandom(_ keyClass: KeyClass) -> SecKeyDescriptor {
-        switch keyClass {
-        case .public:
-            SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .public)
-        case .private:
-            SecKeyDescriptor(keyType: .ecsecPrimeRandom, keyClass: .private)
-        }
+    /// A private key for `RSA` cryptography.
+    public static let rsaPrivateKey = SecKeyDescriptor(keyType: .rsa, keyClass: .private)
+    /// A public key for `RSA` cryptography.
+    public static let rsaPublicKey = SecKeyDescriptor(keyType: .rsa, keyClass: .public)
+    
+    /// A descriptor that defines the properties of the key.
+    public init(keyType: KeyType, keyClass: KeyClass) {
+        self.keyType = keyType
+        self.keyClass = keyClass
     }
 }

Sources/SwiftSecurity/Keychain/Keychain.swift

@@ -273,7 +273,7 @@ extension Keychain {
 
     public func retrieve<T: SecDataConvertible>(_ query: SecItemQuery<InternetPassword>, authenticationContext: LAContext? = nil) throws -> T? {
         if let value = try retrieve(.data, query: query, authenticationContext: authenticationContext), case let .data(data) = value {
-            return try T(rawRepresentation: data)  // Convert back to a key.
+            return try T(rawRepresentation: data)
         } else {
             return nil
         }
@@ -298,25 +298,28 @@ extension Keychain: SecKeyStore {
         query: SecItemQuery<SecKey>,
         accessPolicy: AccessPolicy = .default
     ) throws -> SecValue<SecKey>? {
-        if let specifiedKeyType = query.keyType {
-            precondition(specifiedKeyType == key.descriptor.keyType)
-        }
-        if let specifiedKeyClass = query.keyClass {
-            precondition(specifiedKeyClass == key.descriptor.keyClass)
+        guard
+            /// If key type specified in query, it should match with type from key's descriptor.  Refer to `.key(for:descriptor:)`
+            query.keyType == nil || query.keyType == key.secKeyDescriptor.keyType,
+            /// If key class specified in query, it should match with class from key's descriptor.
+            query.keyClass == nil || query.keyClass == key.secKeyDescriptor.keyClass
+        else {
+            /// You most likely tried to store a public key as a private key. While it might be accepted by the keychain, it could lead to confusion.
+            throw SwiftSecurityError.invalidParameter
         }
         return try store(.reference(key.secKey), returning: returnType, query: query, accessPolicy: accessPolicy)
     }
 
     public func retrieve<T: SecKeyConvertible>(_ query: SecItemQuery<SecKey>, authenticationContext: LAContext? = nil) throws -> T? {
         guard
             let value = try retrieve(.reference, query: query, authenticationContext: authenticationContext),
-            case let .reference(reference) = value
+            case let .reference(secKey) = value
         else {
             return nil
         }
 
         var error: Unmanaged<CFError>?
-        guard let data = SecKeyCopyExternalRepresentation(reference as! SecKey, &error) as Data? else {
+        guard let data = SecKeyCopyExternalRepresentation(secKey as! SecKey, &error) as Data? else {
             if let error = error?.takeRetainedValue() {
                 throw SwiftSecurityError(error: error)
             }
@@ -359,7 +362,7 @@ extension Keychain: SecCertificateStore {
         else {
             return nil
         }
-        return try T(certificate: secCertificate as! SecCertificate)
+        return T(certificate: secCertificate as! SecCertificate)
     }
 
     @discardableResult

Sources/SwiftSecurity/Keychain/SecItemAttr/KeyClass.swift

@@ -1,5 +1,5 @@
 //
-//  KeyType.swift
+//  KeyClass.swift
 //
 //
 //  Created by Dmitriy Zharov on 17.01.2024.
@@ -9,7 +9,9 @@ import Foundation
 import Security
 
 public enum KeyClass {
+    /// A public key of a public-private pair.
     case `public`
+    /// A private key of a public-private pair.
     case `private`
 }
 

Sources/SwiftSecurity/Keychain/SecItemAttr/KeyType.swift

@@ -14,7 +14,7 @@ public typealias KeyCipher = KeyType
 public enum KeyType {
     /// RSA.
     case rsa
-    /// Elliptic curve. Suitable for `P256`, `P384`, `P521` from `CryptoKit`.
+    /// Elliptic curve. Suitable for `P256`, `P384`, `P521` keys from `CryptoKit`.
     case ecsecPrimeRandom
 }
 

Sources/SwiftSecurity/Keychain/SecItemStore/SecItemQuery.swift

@@ -78,11 +78,11 @@ public extension SecItemQuery {
     /// - Note: Suitable for `P256`/`P384`/`P521` keys from `CryptoKit` or custom `RSA` keys.
     /// - Parameters:
     ///   - applicationTag: An application tag that you can use to identify the key within store.
-    ///   - descriptor: A key descriptor.  Default value is `.ecsecPrimeRandom(.private)`.
+    ///   - descriptor: A key descriptor.  Defaults to  `.ecPrivateKey`.
     ///   - synchronizable: A boolean value indicating whether the item synchronizes through iCloud.
     ///   See [Developer Documentation](https://developer.apple.com/documentation/security/ksecattrsynchronizable).
     /// - Returns: ``SecItemQuery<SecKey>``.
-    static func key(for applicationTag: String? = nil, descriptor: SecKeyDescriptor = .ecsecPrimeRandom(.private), synchronizable: Bool? = nil) -> SecItemQuery<SecKey> {
+    static func key(for applicationTag: String? = nil, descriptor: SecKeyDescriptor = .ecPrivateKey, synchronizable: Bool? = nil) -> SecItemQuery<SecKey> {
         var query = SecItemQuery<SecKey>()
         query.keyClass = descriptor.keyClass
         query.keyType = descriptor.keyType
@@ -537,6 +537,6 @@ public extension SecItemQuery {
     /// - Returns: ``SecItemQuery<SecKey>``.
     @available(*, deprecated, renamed: "key(for:synchronizable:)")
     static func privateKey(for applicationTag: String? = nil, synchronizable: Bool? = nil) -> SecItemQuery<SecKey> {
-        return key(for: applicationTag, descriptor: .ecsecPrimeRandom(.private), synchronizable: synchronizable)
+        return key(for: applicationTag, descriptor: .ecPrivateKey, synchronizable: synchronizable)
     }
 }

Sources/SwiftSecurity/Security/DigitalIdentity.swift

@@ -12,12 +12,12 @@ import Security
 public typealias Identity = DigitalIdentity
 
 public struct DigitalIdentity {
-    /// Creates an identity from a raw representation.
+    /// Creates an identity from a reference.
     public init(identity secIdentity: SecIdentity) {
         self.secIdentity = secIdentity
     }
 
-    /// Creates an identity from a raw representation.
+    /// An identity reference.
     public let secIdentity: SecIdentity
 }