Custom private key (#282)

## Motivation:

In some cases a developer may want to sign a certificate using a method
other than a private key. For example: if a private key is protected by
hardware which signs asynchronously.

## Modifications:

- Create `CustomPrivateKey` protocol
- Create `async` initializers for `Certificate` and
`CertificateSigningRequest`.
- `CustomPrivateKey` can now back a`Certificate.PrivateKey`
- Make `Certificate.Signature` initializer public

## Result:

Developers can now sign a certificate with greater flexibility.

## Alternatives Considered:

### Implementations

#### Pass the `CustomPrivateKey` into `Certificate` and
`CertificateSigningRequest` initializers directly.
There is concern this could add too much duplication of api.

### Various names for the protocol:
- `Certificate.PrivateKeyProtocol` and
`Certificate.AsyncPrivateKeyProtocol`
- `Certificate.Signer`/`Certificate.AsyncSigner`
- `Certificate.SignatureProvider`/`Certificate.AsyncSignatureProvider`

---------

Co-authored-by: Cory Benfield <cbenfield@apple.com>
This commit is contained in:
Justin OrozandCory Benfield authored and GitHub committed 2026-02-10 14:29:41 +00:00
1 parent 7d5f6124c9
commit 24ccdeeeed
7 files changed
+333 -1

No files matched your search

+1
View File
@@ -35,6 +35,7 @@ add_library(X509
"CryptographicMessageSyntax/CMSSignerInfo.swift"
"CryptographicMessageSyntax/CMSVersion.swift"
"Curve25519+DER.swift"
"CustomPrivateKey.swift"
"Digests.swift"
"DistinguishedName.swift"
"DistinguishedNameBuilder/CommonName.swift"
@@ -150,6 +150,45 @@ public struct CertificateSigningRequest {
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a CSR for a specific private key.
///
/// This API can be used to construct a certificate signing request that can be passed to a certificate
/// authority. It will correctly generate a signature over the request.
///
/// - Parameters:
/// - version: The CSR version.
/// - subject: The ``DistinguishedName`` of the subject of this CSR
/// - asyncPrivateKey: The private key associated with this CSR.
/// - attributes: The attributes associated with this CSR
/// - signatureAlgorithm: The signature algorithm to use for the signature on this CSR.
@inlinable
public init(
version: Version,
subject: DistinguishedName,
asyncPrivateKey: Certificate.PrivateKey,
attributes: Attributes,
signatureAlgorithm: Certificate.SignatureAlgorithm
) async throws {
self.info = CertificationRequestInfo(
version: version,
subject: subject,
publicKey: asyncPrivateKey.publicKey,
attributes: attributes
)
self.signatureAlgorithm = signatureAlgorithm
let infoBytes = try DER.Serializer.serialized(element: self.info)
self.signature = try await asyncPrivateKey.signAsynchronously(
bytes: infoBytes,
signatureAlgorithm: signatureAlgorithm
)
self.infoBytes = infoBytes[...]
self.signatureAlgorithmBytes = try DER.Serializer.serialized(
element: AlgorithmIdentifier(self.signatureAlgorithm)
)[...]
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a CSR for a specific private key.
///
/// This API can be used to construct a certificate signing request that can be passed to a certificate
+60
View File
@@ -214,6 +214,66 @@ public struct Certificate {
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a certificate from constituent parts, signed by an issuer key.
///
/// This API can be used to construct a ``Certificate`` directly, without an intermediary
/// Certificate Signing Request. The ``signature-swift.property`` for this certificate will be produced
/// automatically, using `issuerAsyncPrivateKey`.
///
/// This API can be used to construct a self-signed key by passing the private key for `publicKey` as the
/// `issuerAsyncPrivateKey` argument.
///
/// - Parameters:
/// - version: The X.509 specification version for this certificate.
/// - serialNumber: The serial number of this certificate.
/// - publicKey: The public key associated with this certificate.
/// - notValidBefore: The date before which this certificate is not valid.
/// - notValidAfter: The date after which this certificate is not valid.
/// - issuer: The ``DistinguishedName`` of the issuer of this certificate.
/// - subject: The ``DistinguishedName`` of the subject of this certificate.
/// - signatureAlgorithm: The signature algorithm that will be used to produce `signature`. Must be compatible with the private key type.
/// - extensions: The extensions on this certificate.
/// - issuerAsyncPrivateKey: The private key to use to sign this certificate.
@inlinable
public init(
version: Version,
serialNumber: SerialNumber,
publicKey: PublicKey,
notValidBefore: Date,
notValidAfter: Date,
issuer: DistinguishedName,
subject: DistinguishedName,
signatureAlgorithm: SignatureAlgorithm,
extensions: Extensions,
issuerAsyncPrivateKey: PrivateKey
) async throws {
self.tbsCertificate = TBSCertificate(
version: version,
serialNumber: serialNumber,
signature: signatureAlgorithm,
issuer: issuer,
validity: try Validity(
notBefore: .makeTime(from: notValidBefore),
notAfter: .makeTime(from: notValidAfter)
),
subject: subject,
publicKey: publicKey,
extensions: extensions
)
self.signatureAlgorithm = signatureAlgorithm
let tbsCertificateBytes = try DER.Serializer.serialized(element: self.tbsCertificate)[...]
self.signature = try await issuerAsyncPrivateKey.signAsynchronously(
bytes: tbsCertificateBytes,
signatureAlgorithm: signatureAlgorithm
)
self.tbsCertificateBytes = tbsCertificateBytes
self.signatureAlgorithmBytes = try DER.Serializer.serialized(
element: AlgorithmIdentifier(self.signatureAlgorithm)
)[...]
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a certificate from constituent parts, signed by an issuer key.
///
/// This API can be used to construct a ``Certificate`` directly, without an intermediary
+45
View File
@@ -91,6 +91,13 @@ extension Certificate {
}
#endif
/// Construct a private key wrapping a custom private key.
/// - Parameter custom: The custom private key to wrap.
@inlinable
public init(_ custom: some CustomPrivateKey) {
self.backing = .custom(custom)
}
/// Use the private key to sign the provided bytes with a given signature algorithm.
///
/// - Parameters:
@@ -119,6 +126,27 @@ extension Certificate {
#endif
case .ed25519(let ed25519):
return try ed25519.signature(for: bytes, signatureAlgorithm: signatureAlgorithm)
case .custom(let custom):
return try custom.signSynchronously(bytes: bytes, signatureAlgorithm: signatureAlgorithm)
}
}
/// Use the private key to sign the provided bytes asynchronously with a given signature algorithm.
///
/// - Parameters:
/// - bytes: The data to create the signature for.
/// - signatureAlgorithm: The signature algorithm to use.
/// - Returns: The signature.
@inlinable
public func signAsynchronously<Bytes: DataProtocol & Sendable>(
bytes: Bytes,
signatureAlgorithm: SignatureAlgorithm
) async throws -> Signature {
switch self.backing {
case .custom(let custom):
return try await custom.signAsynchronously(bytes: bytes, signatureAlgorithm: signatureAlgorithm)
default:
return try self.sign(bytes: bytes, signatureAlgorithm: signatureAlgorithm)
}
}
@@ -143,6 +171,8 @@ extension Certificate {
#endif
case .ed25519(let ed25519):
return PublicKey(ed25519.publicKey)
case .custom(let custom):
return custom.publicKey
}
}
@@ -177,6 +207,8 @@ extension Certificate {
#endif
case .ed25519:
return .ed25519
case .custom(let custom):
return custom.defaultSignatureAlgorithm
}
}
}
@@ -208,6 +240,11 @@ extension Certificate.PrivateKey: CustomStringConvertible {
#endif
case .ed25519:
return "Ed25519.PrivateKey"
case .custom(let custom):
if let custom = custom as? CustomStringConvertible {
return custom.description
}
return "CustomPrivateKey"
}
}
}
@@ -225,6 +262,7 @@ extension Certificate.PrivateKey {
case secKey(SecKeyWrapper)
#endif
case ed25519(Crypto.Curve25519.Signing.PrivateKey)
case custom(any CustomPrivateKey)
@inlinable
static func == (lhs: BackingPrivateKey, rhs: BackingPrivateKey) -> Bool {
@@ -245,6 +283,8 @@ extension Certificate.PrivateKey {
#endif
case (.ed25519(let l), .ed25519(let r)):
return l.rawRepresentation == r.rawRepresentation
case (.custom(let l), .custom(let r)):
return l.publicKey == r.publicKey
default:
return false
}
@@ -277,6 +317,8 @@ extension Certificate.PrivateKey {
case .ed25519(let digest):
hasher.combine(6)
hasher.combine(digest.rawRepresentation)
case .custom(let key):
hasher.combine(key)
}
}
}
@@ -350,6 +392,7 @@ extension Certificate.PrivateKey {
case .secKey(let key): return try key.pemDocument()
#endif
case .ed25519(let key): return key.pemRepresentation
case .custom(let key): return try key.serializeAsPEM()
}
}
}
@@ -408,6 +451,8 @@ extension Certificate.PrivateKey {
#endif
case .ed25519:
return [.ed25519]
case .custom(let customKey):
return customKey.supportedSignatureAlgorithms
}
}
}
+77
View File
@@ -0,0 +1,77 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCertificates open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCertificates project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
#if canImport(FoundationEssentials)
import FoundationEssentials
#else
import Foundation
#endif
import SwiftASN1
/// Implement ``CustomPrivateKey`` if you need custom signing logic.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public protocol CustomPrivateKey: Sendable, Hashable, PEMSerializable {
/// Obtain the ``Certificate/PublicKey-swift.struct`` corresponding to
/// this private key.
var publicKey: Certificate.PublicKey { get }
/// The default signature algorithm to use for signing.
var defaultSignatureAlgorithm: Certificate.SignatureAlgorithm { get }
/// Return a list of all supported signature types for this private key. The ordering is not a comment on the
/// preference or security of the contained algorithms.
var supportedSignatureAlgorithms: [Certificate.SignatureAlgorithm] { get }
/// Use the private key to sign the provided bytes with a given signature algorithm.
///
/// - Parameters:
/// - bytes: The data to create the signature for.
/// - signatureAlgorithm: The signature algorithm to use.
/// - Returns: The signature.
/// - Throws: If signing fails or synchronous signing is unsupported.
func signSynchronously(
bytes: some DataProtocol,
signatureAlgorithm: Certificate.SignatureAlgorithm
) throws -> Certificate.Signature
/// Use the private key to sign the provided bytes asynchronously with a given signature algorithm.
///
/// The default implementation calls ``signSynchronously(bytes:signatureAlgorithm:)`` and returns the result.
/// Conforming types may override this method to provide a specialized asynchronous implementation.
///
/// - Parameters:
/// - bytes: The data to create the signature for.
/// - signatureAlgorithm: The signature algorithm to use.
/// - Returns: The signature.
/// - Throws: If signing fails or asynchronous signing is unsupported.
func signAsynchronously(
bytes: some DataProtocol & Sendable,
signatureAlgorithm: Certificate.SignatureAlgorithm
) async throws -> Certificate.Signature
}
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension CustomPrivateKey {
@inlinable
public func signAsynchronously(
bytes: some DataProtocol & Sendable,
signatureAlgorithm: Certificate.SignatureAlgorithm
) async throws -> Certificate.Signature {
try self.signSynchronously(bytes: bytes, signatureAlgorithm: signatureAlgorithm)
}
}
+1 -1
View File
@@ -46,7 +46,7 @@ extension Certificate {
}
@inlinable
internal init(signatureAlgorithm: SignatureAlgorithm, signatureBytes: ASN1BitString) throws {
public init(signatureAlgorithm: SignatureAlgorithm, signatureBytes: ASN1BitString) throws {
switch signatureAlgorithm {
case .ecdsaWithSHA256, .ecdsaWithSHA384, .ecdsaWithSHA512:
let signature = try ECDSASignature(derEncoded: signatureBytes.bytes)
+110
View File
@@ -0,0 +1,110 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCertificates open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCertificates project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Crypto
import Foundation
import SwiftASN1
import Testing
@testable import X509
@Suite
final class CustomPrivateKeyTests {
@Test("CustomPrivateKey Backing Properties")
func testCustomPrivateKeyBackingProperties() {
let keyBacking = TestAsyncKey()
let privateKey = Certificate.PrivateKey(keyBacking)
#expect(privateKey.publicKey == keyBacking.publicKey)
#expect(privateKey.description == "CustomPrivateKey")
#expect(keyBacking.hashValue == privateKey.hashValue)
#expect(keyBacking.defaultSignatureAlgorithm == privateKey.defaultSignatureAlgorithm)
#expect(keyBacking.supportedSignatureAlgorithms == privateKey.supportedSignatureAlgorithms)
}
@Test("CustomPrivateKey Signing")
func testCustomPrivateKeySigning() async throws {
let privateKey = Certificate.PrivateKey(TestAsyncKey())
_ = try await privateKey.signAsynchronously(
bytes: Data(),
signatureAlgorithm: .ecdsaWithSHA256
)
#expect(throws: TestAsyncKey.MyError.self) {
try privateKey.sign(
bytes: Data(),
signatureAlgorithm: .ecdsaWithSHA256
)
}
}
@Test("CustomPrivateKey Equatable")
func testCustomPrivateKeyBackingEquality() {
let keyBacking = TestAsyncKey()
let leftKey = Certificate.PrivateKey(keyBacking)
let rightKey = Certificate.PrivateKey(keyBacking)
#expect(leftKey == rightKey)
}
@Test("CustomPrivateKey Serialization")
func testCustomPrivateKeySerialization() {
let privateKey = Certificate.PrivateKey(TestAsyncKey())
#expect(throws: TestAsyncKey.MyError.self) {
try privateKey.serializeAsPEM()
}
}
}
/// A theoretical private key which only supports asynchronous signing.
private struct TestAsyncKey: CustomPrivateKey {
var publicKey: Certificate.PublicKey { privateKey.publicKey }
// Not required for CustomPrivateKey protocol.
private let privateKey = Certificate.PrivateKey(P256.Signing.PrivateKey())
let defaultSignatureAlgorithm: Certificate.SignatureAlgorithm = .sha256WithRSAEncryption
var supportedSignatureAlgorithms: [Certificate.SignatureAlgorithm] = [.sha256WithRSAEncryption]
func signSynchronously(
bytes: some DataProtocol,
signatureAlgorithm: Certificate.SignatureAlgorithm
) throws -> Certificate.Signature {
throw MyError()
}
func signAsynchronously(
bytes: some DataProtocol & Sendable,
signatureAlgorithm: Certificate.SignatureAlgorithm
) async throws -> Certificate.Signature {
try await Task {
try privateKey.sign(bytes: bytes, signatureAlgorithm: signatureAlgorithm)
}
.value
}
static let defaultPEMDiscriminator: String = "TestKey"
func serializeAsPEM(discriminator: String) throws -> PEMDocument {
throw MyError()
}
func serialize(into coder: inout DER.Serializer) throws {
throw MyError()
}
struct MyError: Error {}
}