documentation updates (#296)

- **Fix stale DocC disambiguation hash for PrivateKey init**
- **Fix documentation errors, typos, and a bug in
CertificateStore.appending**
- **code example fixes within the existing articles:**
- **Lots of smaller fixes across the board - some copy/pasta errors,
consistency in usage, typos and grammar issues - added documentation
comments where missing to get all public types covered - applied
internal style guidelines for representing the types**

---------

Co-authored-by: David Nadoba <dnadoba@gmail.com>
Co-authored-by: Cory Benfield <lukasa@apple.com>
Co-authored-by: Raphael <josephnoir@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-06-15 13:04:58 -07:00
1 parent a12bcbc0df
commit eaa10d47d1
37 files changed
+223 -177

No files matched your search

+1 -1
View File
@@ -27,7 +27,7 @@ extension CertificateSigningRequest {
public struct Attribute {
/// The identifier for this attribute type.
///
/// Common values are stored in `ASN1ObjectIdentifier.X509ExtensionID`.
/// Common values are stored in `ASN1ObjectIdentifier.CSRAttributes`.
public var oid: ASN1ObjectIdentifier
/// The encoded bytes of the values of this attribute.
@@ -77,7 +77,7 @@ public struct CertificateSigningRequest {
@usableFromInline
let signatureBytes: ArraySlice<UInt8>
/// Construct a Certificate Signing Request from constituent parts.
/// Creates a certificate signing request from constituent parts.
///
/// This API is generally not recommended for use, as it makes it very easy to construct a ``CertificateSigningRequest``
/// whose ``signature`` is not valid. However, for testing and validation purposes it is useful to be
@@ -114,7 +114,7 @@ public struct CertificateSigningRequest {
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a CSR for a specific private key.
/// Creates 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.
@@ -150,7 +150,7 @@ public struct CertificateSigningRequest {
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a CSR for a specific private key.
/// Creates 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.
@@ -189,7 +189,7 @@ public struct CertificateSigningRequest {
self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
}
/// Construct a CSR for a specific private key.
/// Creates 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.
+3 -3
View File
@@ -25,7 +25,7 @@ public struct ExtensionRequest: Hashable, Sendable {
/// Construct an ``ExtensionRequest`` from a given set of extensions.
///
/// - parameters:
/// - Parameters:
/// - extensions: The extensions to attach to this ``ExtensionRequest``.
@inlinable
public init(extensions: Certificate.Extensions) {
@@ -34,7 +34,7 @@ public struct ExtensionRequest: Hashable, Sendable {
/// Unwrap a ``CertificateSigningRequest/Attribute`` that contains an ``ExtensionRequest``.
///
/// - parameters:
/// - Parameters:
/// - attribute: The attribute to unwrap
/// - throws: If the attribute is ill-formed, or does not contain an ``ExtensionRequest``.
@inlinable
@@ -60,7 +60,7 @@ public struct ExtensionRequest: Hashable, Sendable {
extension CertificateSigningRequest.Attribute {
/// Wrap an ``ExtensionRequest`` into a ``CertificateSigningRequest/Attribute``.
///
/// - parameters:
/// - Parameters:
/// - extensionRequest: The ``ExtensionRequest`` to wrap.
@inlinable
public init(_ extensionRequest: ExtensionRequest) throws {
+3 -3
View File
@@ -60,7 +60,7 @@ import SwiftASN1
/// Both of these goals encourage this type to be immutable. A ``Certificate`` represents
/// a specific assertion of identity. Its ``Certificate/signature-swift.property`` is signed
/// across the rest of the data. Allowing users to change this data makes it easy to accidentally modify
/// a ``Certificate`` in one part of your code and not realise that the signature has inevitably
/// a ``Certificate`` in one part of your code and not realize that the signature has inevitably
/// been invalidated.
#if canImport(Security)
///
@@ -146,14 +146,14 @@ public struct Certificate {
/// The bytes of the ``Signature``.
///
/// These are preserved to ensure that we reserialize exactly what we deserialized, regardless
/// of any canonicalisation we might do.
/// of any canonicalization we might do.
@usableFromInline
internal let signatureBytes: ArraySlice<UInt8>
/// The bytes of the ``signatureAlgorithm-swift.property``.
///
/// These are preserved to ensure that we reserialize exactly what we deserialized, regardless of
/// any canonicalisation we might do.
/// any canonicalization we might do.
@usableFromInline
internal let signatureAlgorithmBytes: ArraySlice<UInt8>
+5 -5
View File
@@ -23,14 +23,14 @@ import _CryptoExtras
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// A private key that can be used with a certificate.
/// A private key for use with a certificate.
///
/// This type provides an opaque wrapper around the various private key types
/// provided by `swift-crypto` and `Security`. Users are expected to construct this key from
/// This type is an opaque wrapper around the various private key types
/// provided by `swift-crypto` and `Security`. Construct this key from
/// one of those types.
///
/// As private keys are never sent over the wire, this type does not offer
/// support for being unwrapped back into the underlying key types.
/// As private keys are never sent over the wire, this type does not support
/// unwrapping back into the underlying key types.
public struct PrivateKey {
@usableFromInline
var backing: BackingPrivateKey
+9 -9
View File
@@ -23,11 +23,11 @@ import Foundation
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// A public key that can be used with a certificate.
/// A public key for use with a certificate.
///
/// This type provides an opaque wrapper around the various public key types
/// provided by `swift-crypto`. Users are expected to construct this key from
/// one of those types, or to decode it from the network.
/// This type is an opaque wrapper around the various public key types
/// provided by `swift-crypto`. Construct this key from
/// one of those types, or decode it from the network.
public struct PublicKey {
@usableFromInline
var backing: BackingPublicKey
@@ -311,7 +311,7 @@ extension P256.Signing.PublicKey {
///
/// Fails if the key is not a P256 key.
///
/// - parameters:
/// - Parameters:
/// - key: The key to unwrap.
public init?(_ key: Certificate.PublicKey) {
guard case .p256(let inner) = key.backing else {
@@ -327,7 +327,7 @@ extension P384.Signing.PublicKey {
///
/// Fails if the key is not a P384 key.
///
/// - parameters:
/// - Parameters:
/// - key: The key to unwrap.
public init?(_ key: Certificate.PublicKey) {
guard case .p384(let inner) = key.backing else {
@@ -343,7 +343,7 @@ extension P521.Signing.PublicKey {
///
/// Fails if the key is not a P521 key.
///
/// - parameters:
/// - Parameters:
/// - key: The key to unwrap.
public init?(_ key: Certificate.PublicKey) {
guard case .p521(let inner) = key.backing else {
@@ -359,7 +359,7 @@ extension _RSA.Signing.PublicKey {
///
/// Fails if the key is not an RSA key.
///
/// - parameters:
/// - Parameters:
/// - key: The key to unwrap.
public init?(_ key: Certificate.PublicKey) {
guard case .rsa(let inner) = key.backing else {
@@ -375,7 +375,7 @@ extension Curve25519.Signing.PublicKey {
///
/// Fails if the key is not a Curve25519 key.
///
/// - parameters:
/// - Parameters:
/// - key: The key to unwrap.
public init?(_ key: Certificate.PublicKey) {
guard case .ed25519(let inner) = key.backing else {
+1 -1
View File
@@ -52,7 +52,7 @@ extension Certificate {
///
/// In general this API should only be used for testing, as fixed width integers
/// are not sufficiently large for use in certificates. Using this API for production
/// use-cases may expose users to hash collision attacks on generated certificates.
/// use cases may expose users to hash collision attacks on generated certificates.
///
/// Prefer using ``Certificate/SerialNumber-swift.struct/init(integerLiteral:)``
/// with a `StaticBigInt` which enables arbitrary-precision.
@@ -19,6 +19,7 @@ import Foundation
import SwiftASN1
import Crypto
/// A namespace for Cryptographic Message Syntax (CMS) operations.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public enum CMS: Sendable {
@_spi(CMS)
+1 -1
View File
@@ -20,7 +20,7 @@ import SwiftASN1
/// distinguished names were the primary key, enabling the identification of a specific entity
/// within the directory.
///
/// These use-cases are largely obsolete, but distinguished names continue to be used to identify
/// These use cases are largely obsolete, but distinguished names continue to be used to identify
/// both the subject of and issuer of a given X.509 certificate. In this context, the distinguished
/// name is a largely opaque identifier that just happens to have a human-readable string representation.
///
@@ -87,6 +87,8 @@ public struct DistinguishedNameBuilder: Sendable {
}
}
/// A type that can be converted to a ``RelativeDistinguishedName``.
public protocol RelativeDistinguishedNameConvertible {
/// Creates a ``RelativeDistinguishedName`` from this value.
func makeRDN() throws -> RelativeDistinguishedName
}
+53 -51
View File
@@ -1,25 +1,24 @@
# Creating Certificates
Users often have a need to create certificates. Whether for testing or some other interaction with an
existing system, creating a certificate programmatically is a powerful tool for users.
Create certificates programmatically for testing or other interactions with existing systems.
``X509`` provides a number of conveniences for making this easy. There are two common ways to create
a certificate: directly, or from a CSR.
``X509`` provides a number of conveniences for making this easy. The most common way to create
a certificate is directly, though you can also create one from a ``CertificateSigningRequest``.
## Creating Certificates Directly
## Create certificates directly
There are many kinds of certificates that users may want to create, but the most common is to want
to create a self-signed certificate. These are valuable in testing scenarios, as they can serve
both as a trusted root and as an end-entity certificate.
Many kinds of certificates are useful to create, but the most common is a self-signed certificate.
These are valuable in testing scenarios, as they can serve both as a trusted root and as an
end-entity certificate.
Fortunately, creating a self-signed certificate is very similar to creating an intermediate or leaf
certificate. This document will call out the steps that might need to be different.
certificate. This document calls out the steps that might need to be different.
### Gathering our requirements
### Gather your requirements
To create a certificate directly we're going to call the
To create a certificate directly, call the
``Certificate/init(version:serialNumber:publicKey:notValidBefore:notValidAfter:issuer:subject:signatureAlgorithm:extensions:issuerPrivateKey:)``
initializer. This requires that we put together the following information:
initializer. This requires the following information:
- Version
- Serial number
@@ -31,12 +30,12 @@ initializer. This requires that we put together the following information:
- Public Key
- Issuer private key
### Version
### Choose a version
Working out the version to use is easy. When creating our own certificates, we should always create a
Working out the version to use is easy. When creating your own certificates, always create a
``Certificate/Version-swift.struct/v3`` certificate. There is no reason to use any version older than this.
### Serial Number
### Set a serial number
The certificate serial number forms part of the identifier of the certificate, along with the issuer name. For a given
CA, each certificate it issues must have a unique serial number. Additionally, the
@@ -45,51 +44,51 @@ need to conform to this profile the serial number must contain at least 64-bits
``Certificate/SerialNumber-swift.struct`` has a helper initializer that will create a 20-byte serial number
consisting entirely of randomness: ``Certificate/SerialNumber-swift.struct/init()``. That's a good default choice for
this kind of use-case.
this kind of use case.
### Validity Period
### Define a validity period
The validity period of a certificate is made up of two dates: "not valid before" and "not valid after". The "not valid before" date
The validity period of a certificate consists of two dates: "not valid before" and "not valid after". The "not valid before" date
refers to the point in time before which a certificate must not be trusted, and is typically set to the date and time at which
the certificate was signed by the issuer. The "not valid after" date refers to the point in time after which the certificate has
expired and should not be trusted.
Together these two dates define a validity period. We'll set "not valid before" to the current time (`Date()`), and we'll set the
Together these two dates define a validity period. Set "not valid before" to the current time (`Date()`), and set the
certificate to be valid for a year, making the "not valid after" date `now.addingTimeInterval(60 * 60 * 24 * 365)`.
### Subject Name
### Set a subject name
The subject name identifies the entity to whom the certificate is being issued. This is a hierarchical name type called a
``DistinguishedName``. The full complexity of distinguished names is tackled in the ``DistinguishedName`` API documentation,
but for our use-case it's sufficient to know that we don't need to set anything other than the common name. Additionally, in
all modern use-cases the common name is nothing more than an identifier, so we can set it to whatever we like.
but for this use case it's sufficient to know that you don't need to set anything other than the common name. Additionally, in
all modern use cases the common name is nothing more than an identifier, so you can set it to whatever you like.
```swift
let subjectName = DistinguishedName {
let subjectName = try DistinguishedName {
CommonName("My awesome subject")
}
```
### Issuer Name
### Set an issuer name
Just as the subject name identifies the entity to whom the subject is being issued, the issuer name identifies the entity that
Just as the subject name identifies the entity to whom the certificate is being issued, the issuer name identifies the entity that
issued the certificate. In particular, the issuer name should be exactly equivalent to the subject name in the issuing entity's
certificate.
If we were creating a non-self-signed certificate, we'd set `issuerName` equal to ``Certificate/subject`` from the parent
certificate. For self-signed certificates, the issuer and the subject are identical, so we can set `issuerName = subjectName`.
When creating a non-self-signed certificate, set `issuerName` equal to ``Certificate/subject`` from the parent
certificate. For self-signed certificates, the issuer and the subject are identical, so you can set `issuerName = subjectName`.
### Extensions
### Add extensions
The bulk of the semantic information in a certificate is contained in its extensions. For our case, we care about only a small
few.
The bulk of the semantic information in a certificate is contained in its extensions. For this case, only a small
few matter.
We need ``BasicConstraints`` to be present, and set to
`isCertificateAuthority`. We also need ``KeyUsage`` with the appropriate bits
set. Finally, we want to set ``SubjectAlternativeNames`` to include the domain
name we're going to be self-signing for, which in this case we'll set to `localhost`.
You need ``BasicConstraints`` to be present, and set to
`isCertificateAuthority`. You also need ``KeyUsage`` with the appropriate bits
set. Finally, set ``SubjectAlternativeNames`` to include the domain
name you're going to be self-signing for, which in this case is `localhost`.
We can use the helpful builder syntax for this:
You can use the helpful builder syntax for this:
```swift
let extensions = try Certificate.Extensions {
@@ -97,33 +96,33 @@ let extensions = try Certificate.Extensions {
BasicConstraints.isCertificateAuthority(maxPathLength: nil)
)
Critical(
KeyUsage(digitalSignature: true, keyCertSign: true)
KeyUsage(keyCertSign: true)
)
SubjectAlternativeNames([.dnsName("localhost")])
}
```
### Cryptographic Material
### Provide cryptographic material
In our case, the public key, signature algorithm, and issuer private key are intimately bound together. For self-signed certs, the
In this case, the public key, signature algorithm, and issuer private key are intimately bound together. For self-signed certs, the
public key is the public key that belongs to the issuer private key. Relatedly, the signature algorithm is constrained to only those
that are supported by our private key, as that'll be the one doing the signing.
supported by the private key, as that key does the signing.
If we weren't creating a self-signed certificate, the issuer private key would be the private key for the issuing certificate,
When creating a non-self-signed certificate, the issuer private key would be the private key for the issuing certificate,
and the signature algorithm would be constrained to what that key is capable of. The public key could be anything, but it needs to
match the private key that the subject entity has attested to possessing.
We can use the keys from `swift-crypto` for this operation. We'll select `P256.Signing.PrivateKey` as our private key, which
we can wrap up in ``Certificate/PrivateKey/init(_:)-6xkmz`` to get `issuerPrivateKey`. We can then derive `publicKey` via
``Certificate/PrivateKey/publicKey``. Finally, we'll pick the only signature algorithm compatible with that key, which is
You can use the keys from `swift-crypto` for this operation. Select `P256.Signing.PrivateKey` as the private key, which
you can wrap in ``Certificate/PrivateKey/init(_:)-(P256.Signing.PrivateKey)`` to get `issuerPrivateKey`. Then derive `publicKey` via
``Certificate/PrivateKey/publicKey``. Finally, pick the only signature algorithm compatible with that key, which is
``Certificate/SignatureAlgorithm-swift.struct/ecdsaWithSHA256``.
### Serializing
### Serialize the certificate
Once the certificate is created, we'll want to write it out to a file so we can use it! We can easily output this in DER format,
Once the certificate is created, you'll want to write it out to a file so you can use it. You can easily output this in DER format,
which is commonly indicated using a `.crt` file extension.
We get the DER representation by using code from `SwiftASN1`. ``Certificate`` conforms to `DERSerializable`, so we can serialize
Get the DER representation by using code from `SwiftASN1`. ``Certificate`` conforms to `DERSerializable`, so you can serialize
it like this:
```swift
@@ -131,9 +130,12 @@ var serializer = DER.Serializer()
try serializer.serialize(certificate)
```
### Putting it all together
You may also want to save the private key for later use. You can obtain its DER representation from the
original `swift-crypto` key via its `derRepresentation` property.
That leaves us with the following code for generating a self-signed certificate.
### Put it all together
Here is the complete code for generating a self-signed certificate.
```swift
import Crypto
@@ -179,7 +181,7 @@ let derEncodedCertificate = serializer.serializedBytes
let derEncodedPrivateKey = swiftCryptoKey.derRepresentation
```
### Creating Certificates from SecCertificate and vice versa
### Convert between Certificate and SecCertificate
An instance of ``Certificate`` can be created from `Security/SecCertificate` (from the `Security` framework) with `Certificate/init(_:)`.
The opposite, that is, creating an instance of `Security/SecCertificate` from `Certificate`, can be achieved with `Security/SecCertificate/makeWithCertificate(_:)`.
Create an instance of ``Certificate`` from `SecCertificate` (from the `Security` framework) with `Certificate.init(_: SecCertificate)`.
To create an instance of `SecCertificate` from ``Certificate``, use `SecCertificate.makeWithCertificate(_:)`.
@@ -2,15 +2,15 @@
Decoding and introspecting certificates.
A common use-case is to have received an X.509 certificate from some source, and to want
to inspect it and make decisions based on its content. X.509 certificates are complex
objects with highly dynamic and nested content, so this article attempts to outline
how to work with ``Certificate`` in order to get the most out of the content of an
A common use case is to receive an X.509 certificate from some source and
inspect it to make decisions based on its content. X.509 certificates are complex
objects with highly dynamic and nested content. This article outlines
how to work with ``Certificate`` to get the most out of the content of an
X.509 certificate.
## Parsing
## Parse certificates
Certificates are commonly provided in two formats: PEM and DER. The two formats are closely
Two formats are common for certificates: PEM and DER. The two formats are closely
related. PEM stands for "Privacy Enhanced Mail", and a PEM certificate commonly looks like
this:
@@ -30,20 +30,20 @@ FGgfAiEA1PMpcTTeK8Hi17N0oaNNIWERLqDketPZG5E3OdEDw9E=
```
This format is the DER representation of a certificate, base64-encoded, line wrapped at 64
bytes, and bracketed by the `BEGIN X`/`END X` delimiter. As PEMs can easily be translated
bytes, and bracketed by the `BEGIN X`/`END X` delimiters. As PEMs can easily be translated
to DER bytes and vice-versa, the rest of this document will focus on the DER format.
To parse a certificate from DER, we can construct it with a helper initializer from `SwiftASN1`:
To parse a certificate from DER, construct it with a helper initializer from `SwiftASN1`:
```swift
let derBytes: [UInt8] = // get these from somewhere
let certificate = try Certificate(derEncoded: derBytes)
```
Assuming the certificate is well-formed, this constructor will build us a ``Certificate`` object
that we can work with.
Assuming the certificate is well-formed, this constructor builds a ``Certificate`` object
that you can work with.
## Introspecting Certificates
## Inspect certificate fields
Certificates have a wide range of fields. Many of them are not that interesting (for example,
``Certificate/version-swift.property``). However, a number of them make useful attestations about the
@@ -57,39 +57,39 @@ Certificates have at least two names attached to them: ``Certificate/issuer`` an
these names are represented using ``DistinguishedName``.
``DistinguishedName`` is a fairly complex type that is described in more detail in its API documentation.
In short, it's a hierarchical collection of ``RelativeDistinguishedName``s, each of which is made up
of a set of equivalent ``RelativeDistinguishedName/Attribute``s. These ``RelativeDistinguishedName``s
In short, it's a hierarchical collection of ``RelativeDistinguishedName`` values, each of which is made up
of a set of equivalent ``RelativeDistinguishedName/Attribute`` values. These ``RelativeDistinguishedName`` values
are arranged in order from least specific to most specific, typically ending with a relative
distinguished name containing a ``CommonName`` ``RelativeDistinguishedName/Attribute``.
A string representation of a ``DistinguishedName`` can be obtained by using `String(describing:)`. This
uses the common [RFC4514 format](https://www.rfc-editor.org/rfc/rfc4514) for textual ``DistinguishedName``s.
Generally speaking the specific content of the names in these fields are unimportant to end users, though they do
Generally speaking the specific content of the names in these fields is unimportant to end users, though they do
play a vital role in validating certificates.
### Keys
Certificates are bound to a specific private key, which can be used to authenticate that a specific entity is
the one to whom the certificate was issued. This binding is achieved by embedding the public key corresponding
to the underlying private key into the certificate object itself. This is modelled in the ``Certificate/publicKey-swift.property``
to the underlying private key into the certificate object itself. This is modeled in the ``Certificate/publicKey-swift.property``
field.
In ``X509`` the ``Certificate/PublicKey-swift.struct`` type is opaque, but they can be compared for equality.
In ``X509`` the ``Certificate/PublicKey-swift.struct`` type is opaque, but values of this type can be compared for equality.
### Extensions
The majority of the semantic information in certificate objects is stored in their X509v3 extensions.
The majority of the semantic information in certificate objects is stored in their X.509v3 extensions.
These are a typed key-value dictionary that contain additional information about both the subject of the
certificate and about much of its content.
``X509`` stores the extension information in a ``Certificate/Extensions-swift.struct`` collection. This
is a full-fidelity representation of all extensions found in the certificate. This stores the extensions
as ``Certificate/Extension`` objects, an opaque raw-bytes representation of the extension.
as ``Certificate/Extension`` values, an opaque raw-bytes representation of the extension.
Implementations are generally not required to understand all extensions in a certificate, as many are
strictly informational. However, some extensions must be understood in order for the certificate to safely
fulfil their function. As a result, users of a certificate should always search for extensions that have
strictly informational. However, some extensions must be understood for the certificate to safely
fulfill their function. As a result, users of a certificate should always search for extensions that have
the ``Certificate/Extension/critical`` bit set to `true` and, if they do not understand those extensions,
should refuse to trust the certificate.
@@ -109,21 +109,21 @@ Out of the box, ``X509`` ships support for the following extension types:
- ``SubjectKeyIdentifier``
To decode an extension usually requires examining its ``Certificate/Extension/oid`` field. For example, to search
for the ``SubjectAlternativeNames``, the typical code would be:
for the ``SubjectAlternativeNames``, you would typically write:
```swift
let opaqueSanExtension = certificate.extensions.first(where: { $0.oid == .X509ExtensionID.subjectAlternativeName })
if let opaqueSanExtension {
let unwrappedSanExtension = try SubjectAlternativeName(opaqueSanExtension)
let unwrappedSanExtension = try SubjectAlternativeNames(opaqueSanExtension)
}
```
This is verbose and repetitive code, so users are encouraged to use the helper function ``Certificate/Extensions-swift.struct/subscript(oid:)``
to search for a specific extension. The above code could be replaced by:
This is verbose and repetitive code, so consider using the helper function ``Certificate/Extensions-swift.struct/subscript(oid:)``
to search for a specific extension. The above code becomes:
```swift
if let opaqueSanExtension = certificate.extensions[oid: .X509ExtensionID.subjectAlternativeName] {
let unwrappedSanExtension = try SubjectAlternativeName(opaqueSanExtension)
let unwrappedSanExtension = try SubjectAlternativeNames(opaqueSanExtension)
}
```
@@ -139,14 +139,14 @@ that can be used to get a specific typed extension:
- ``Certificate/Extensions-swift.struct/subjectAlternativeNames``
- ``Certificate/Extensions-swift.struct/subjectKeyIdentifier``
This lets us reduce the above code to a single line:
This reduces the above code to a single line:
```swift
let unwrappedSanExtension = try certificate.extensions.subjectAlternativeName
let unwrappedSanExtension = try certificate.extensions.subjectAlternativeNames
```
This shorthand is most useful when searching for a specific extension. When attempting to work with an entire certificate,
users are encouraged to iterate the ``Certificate/Extensions-swift.struct`` and unwrap each extension in turn. This ensures
This shorthand is most useful when searching for a specific extension. When working with an entire certificate,
iterate the ``Certificate/Extensions-swift.struct`` and unwrap each extension in turn. This ensures
that unknown or invalid ``Certificate/Extension/critical`` extensions are not incorrectly tolerated.
### Signatures
@@ -166,5 +166,5 @@ Together these objects make it possible to validate that a signature was correct
``Certificate/PublicKey-swift.struct/isValidSignature(_:for:)-3cbor``.
> Warning: While this is a necessary condition for determining the issuer of a certificate, it is not a sufficient one.
> Users are strongly discouraged from hand-rolling their own verification logic, and should instead prefer using an
> Don't hand-roll your own verification logic. Instead, prefer using an
> existing verifier. Wherever possible, prefer to use the platform verifier.
+4 -4
View File
@@ -12,7 +12,7 @@
//
//===----------------------------------------------------------------------===//
/// Represents an error that may be thrown from the ``Certificate`` module.
/// An error thrown by the ``Certificate`` module.
///
/// This object contains both an error ``code`` and a textual reason for the error,
/// as well as source code context for the error. When attempting to process a specific
@@ -79,8 +79,8 @@ public struct CertificateError: Error, Hashable, CustomStringConvertible {
)
}
/// The private key algorithm used in a ``Certificate`` is not supported by this library.
/// - Parameter reason: A detailed reason explaining what private key algorithm was not supported.
/// The public key algorithm used in a ``Certificate`` is not supported by this library.
/// - Parameter reason: A detailed reason explaining what public key algorithm was not supported.
/// - Parameter file: The file where the error occurs.
/// - Parameter line: The line where the error occurs.
/// - Returns: A ``CertificateError`` with ``code`` set to ``ErrorCode/unsupportedPublicKeyAlgorithm``.
@@ -163,7 +163,7 @@ public struct CertificateError: Error, Hashable, CustomStringConvertible {
)
}
/// A digest private key isn't supported
/// The private key isn't supported by this library.
/// - Parameter reason: A detailed reason indicating the unsupported private key.
/// - Parameter file: The file where the error occurs.
/// - Parameter line: The line where the error occurs.
@@ -14,7 +14,7 @@
import SwiftASN1
/// Provides details on how to access information about the certificate issuer.
/// Describes how to access information about the certificate issuer.
///
/// This extension behaves as a collection of ``AuthorityInformationAccess/AccessDescription`` objects.
///
@@ -15,7 +15,7 @@
import SwiftASN1
/// Indicates one or more purposes for which the certified public key
/// may be used, in addition to or instead of the the purposes indicated
/// may be used, in addition to or instead of the purposes indicated
/// in the ``KeyUsage`` extension.
public struct ExtendedKeyUsage {
@usableFromInline
@@ -155,7 +155,7 @@ extension ExtendedKeyUsage {
///
/// - Returns: A pair `(inserted, index)`, where `inserted` is a Boolean value
/// indicating whether the operation added a new element, and `index` is
/// the index of `item` in the resulting set. If `inserted` is false, then
/// the index of `usage` in the resulting set. If `inserted` is false, then
/// the returned `index` may be different from the index requested.
@inlinable
@discardableResult
@@ -15,7 +15,7 @@
import SwiftASN1
extension ASN1ObjectIdentifier {
/// OIDs that identify known X509 extensions.
/// OIDs that identify known X.509 extensions.
public enum X509ExtensionID: Sendable {
/// Identifies the authority key identifier extension, corresponding to
/// ``AuthorityKeyIdentifier``.
@@ -14,7 +14,7 @@
import SwiftASN1
/// Constraints the namespace within which all subject names issued by a given CA must reside.
/// Constrains the namespace within which all subject names issued by a given CA must reside.
///
/// These constraints apply both to the ``Certificate/subject`` and also to any
/// ``SubjectAlternativeNames`` that may be present. Restrictions are applied to
@@ -25,6 +25,7 @@ import SwiftASN1
/// the same name is also matched in a permitted tree.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public struct NameConstraints {
/// A collection of DNS domain name constraints.
public struct DNSNames: Hashable, Sendable, Collection, ExpressibleByArrayLiteral, CustomStringConvertible {
public typealias Element = String
@@ -123,6 +124,7 @@ public struct NameConstraints {
}
}
/// A collection of IP address range constraints, encoded as ASN.1 octet strings.
public struct IPRanges: Hashable, Sendable, Collection, ExpressibleByArrayLiteral, CustomStringConvertible {
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
@@ -219,6 +221,7 @@ public struct NameConstraints {
}
}
/// A collection of email address constraints.
public struct EmailAddresses: Hashable, Sendable, Collection, ExpressibleByArrayLiteral, CustomStringConvertible {
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
@@ -315,6 +318,7 @@ public struct NameConstraints {
}
}
/// A collection of URI domain constraints.
public struct URIDomains: Hashable, Sendable, Collection, ExpressibleByArrayLiteral, CustomStringConvertible {
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
@@ -433,7 +437,7 @@ public struct NameConstraints {
/// The DNS name trees that are forbidden in certificates issued by this CA.
///
/// These restrictions are expressed in forms like `host.example.com`. Any DNS name that can be
/// constructed by adding zero or more labels to the left-hand side of the name satifies the constraint.
/// constructed by adding zero or more labels to the left-hand side of the name satisfies the constraint.
public internal(set) var excludedDNSDomains: DNSNames {
get {
DNSNames(subtrees: excludedSubtrees)
@@ -452,7 +456,7 @@ public struct NameConstraints {
/// The IP ranges that are permitted in certificates issued by this CA.
///
/// These restrictions are expressed as a subnet, represented in an ASN.1 octet string.
/// Due to the absence of a currency subnet and IP address type in Swift, these are preserved
/// Due to the absence of a standard subnet and IP address type in Swift, these are preserved
/// as octet strings.
///
/// As an example, the subnet 192.0.2.0/24 is encoded as the bytes `0xC0, 0x00, 0x02, 0x00, 0xFF, 0xFF, 0xFF, 0x00`.
@@ -477,7 +481,7 @@ public struct NameConstraints {
/// The IP ranges that are forbidden in certificates issued by this CA.
///
/// These restrictions are expressed as a subnet, represented in an ASN.1 octet string.
/// Due to the absence of a currency subnet and IP address type in Swift, these are preserved
/// Due to the absence of a standard subnet and IP address type in Swift, these are preserved
/// as octet strings.
///
/// As an example, the subnet 192.0.2.0/24 is encoded as the bytes `0xC0, 0x00, 0x02, 0x00, 0xFF, 0xFF, 0xFF, 0x00`.
@@ -519,7 +523,7 @@ public struct NameConstraints {
}
}
/// The email addresses that are permitted in certificates issued by this CA.
/// The email addresses that are excluded in certificates issued by this CA.
///
/// This form may contain a specific mailbox (e.g. `user@example.com`), all
/// addresses on a given host (e.g. `example.com`), or all mailboxes within a
@@ -14,7 +14,7 @@
import SwiftASN1
/// Allows identities to be bound to the subject of a certificate.
/// Binds identities to the subject of a certificate.
///
/// The identities attested in this extension belong to the subject of the certificate.
/// Users of the certificate may validate that these names correspond to a name they are
@@ -20,7 +20,7 @@ import struct FoundationEssentials.Data
import struct Foundation.Data
#endif
/// Provides a means of identifying a certificate that contains a particular public key.
/// Identifies a certificate by its public key.
///
/// This extension contains a value derived from the public key of the certificate in which it appears.
/// That value can be used to build the ``AuthorityKeyIdentifier/keyIdentifier`` field in
+1 -1
View File
@@ -16,7 +16,7 @@ import SwiftASN1
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// A general-purpose representation of a specific X.509 extension.
/// A type-erased representation of a specific X.509 extension.
///
/// X.509 extensions are a general representation, with three properties: an identifier, a critical flag, and the encoded value.
/// The specific data contained in the encoded value is determined by the value of the identifier stored in ``oid``.
+5 -5
View File
@@ -16,7 +16,7 @@ import SwiftASN1
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// A representation of a collection of X.509 extensions.
/// An ordered collection of X.509 certificate extensions.
///
/// The majority of semantic information in an X.509 certificate is contained within its
/// collection of extensions. These extensions can add additional constraints or capabilities
@@ -197,10 +197,10 @@ extension Certificate.Extensions {
}
/// Updates the ``Certificate/Extension`` stored in the dictionary for the ``Certificate/Extension/oid`` of the `extension`,
/// or appends `extension` if an ``Certificate/Extension`` with same ``Certificate/Extension/oid`` does not exist.
/// or appends `extension` if a ``Certificate/Extension`` with the same ``Certificate/Extension/oid`` does not exist.
///
/// - Parameter extension: The ``Certificate/Extension`` to update or append.
/// - Returns: The old ``Certificate/Extension`` that was replaced or `nil` if no ``Certificate/Extension`` with same ``Certificate/Extension/oid`` was present
/// - Returns: The old ``Certificate/Extension`` that was replaced, or `nil` if no ``Certificate/Extension`` with the same ``Certificate/Extension/oid`` was present.
@inlinable
@discardableResult
public mutating func update(_ extension: Certificate.Extension) -> Certificate.Extension? {
@@ -214,9 +214,9 @@ extension Certificate.Extensions {
}
/// Removes the ``Certificate/Extension`` with the given `oid`.
/// - Parameter oid: The ``Certificate/Extension/oid`` of the``Certificate/Extension`` to remove.
/// - Parameter oid: The ``Certificate/Extension/oid`` of the ``Certificate/Extension`` to remove.
/// - Returns: The ``Certificate/Extension`` that was removed,
/// or `nil` if an ``Certificate/Extension`` was not present in with the given `oid`.
/// or `nil` if a ``Certificate/Extension`` was not present with the given `oid`.
@inlinable
@discardableResult
public mutating func remove(_ oid: ASN1ObjectIdentifier) -> Certificate.Extension? {
+4 -4
View File
@@ -12,9 +12,9 @@
//
//===----------------------------------------------------------------------===//
/// Provides a result-builder style DSL for constructing ``Certificate/Extensions-swift.struct`` values.
/// A result-builder DSL for constructing ``Certificate/Extensions-swift.struct`` values.
///
/// This DSL allows us to construct extensions straightforwardly, using their high-level representation instead of
/// This DSL allows constructing extensions straightforwardly, using their high-level representation instead of
/// the erased representation provided by ``Certificate/Extension``. For example, a simple set of
/// extensions can be produced like this:
///
@@ -114,9 +114,9 @@ public struct ExtensionsBuilder: Sendable {
}
}
/// Conforming types are capable of being erased into ``Certificate/Extension`` values.
/// A type that converts to a ``Certificate/Extension`` value.
///
/// Note that for most extension types, the returned ``Certificate/Extension`` should have its
/// For most extension types, the returned ``Certificate/Extension`` should have its
/// ``Certificate/Extension/critical`` value set to `false`. This allows the ``Critical`` helper
/// type to fulfill its function as expected.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+13
View File
@@ -14,15 +14,25 @@
import SwiftASN1
/// A general-purpose name type used in X.509 certificate extensions.
public enum GeneralName: Hashable, Sendable, DERParseable, DERSerializable {
/// A name in a form not directly supported by the other cases.
case otherName(OtherName)
/// An RFC 822 email address, such as `user@example.com`.
case rfc822Name(String)
/// A DNS domain name, such as `example.com`.
case dnsName(String)
/// An X.400 address, preserved as a raw ASN.1 value.
case x400Address(ASN1Any)
/// An X.500 directory name.
case directoryName(DistinguishedName)
/// An EDI party name, preserved as a raw ASN.1 value.
case ediPartyName(ASN1Any)
/// A URI, such as `https://example.com`.
case uniformResourceIdentifier(String)
/// An IP address, encoded as an ASN.1 octet string.
case ipAddress(ASN1OctetString)
/// A registered object identifier.
case registeredID(ASN1ObjectIdentifier)
@usableFromInline
@@ -153,14 +163,17 @@ extension GeneralName: CustomStringConvertible {
// partyName [1] DirectoryString }
extension GeneralName {
/// A name identified by an OID and an arbitrary ASN.1 value.
public struct OtherName: Hashable, Sendable, DERImplicitlyTaggable {
@inlinable
public static var defaultIdentifier: ASN1Identifier {
.sequence
}
/// The OID that identifies the name form.
public var typeID: ASN1ObjectIdentifier
/// The name value, encoded as a raw ASN.1 element.
public var value: ASN1Any?
@inlinable
+2 -2
View File
@@ -32,7 +32,7 @@ public protocol OCSPRequester: Sendable {
/// - Parameters:
/// - request: DER-encoded request bytes
/// - uri: uri of the OCSP responder
/// - Returns: DER-encoded response bytes if they request was successful or a terminal or non-terminal error.
/// - Returns: DER-encoded response bytes if the request was successful, or a terminal or non-terminal error.
func query(request: [UInt8], uri: String) async -> OCSPRequesterQueryResult
}
@@ -164,7 +164,7 @@ enum OCSPRequestHashAlgorithm {
}
}
/// Defines the behaviour of ``OCSPVerifierPolicy`` in the event of a failure.
/// Defines the behavior of ``OCSPVerifierPolicy`` in the event of a failure.
/// ``soft`` should be used most of the time and will only fail verification if a verified OCSP response reports a status of revoked.
public struct OCSPFailureMode: Hashable, Sendable {
/// ``soft`` failure mode will only fail verification if a verified and valid OCSP response reports a status of revoked.
+3 -3
View File
@@ -348,11 +348,11 @@ extension ASN1ObjectIdentifier {
/// avenue, and the house number).
public static let streetAddress: ASN1ObjectIdentifier = [2, 5, 4, 9]
/// The `domainComponent` attribute type contains parts (labels) of a DNS domain name
/// The `domainComponent` attribute type contains parts (labels) of a DNS domain name.
public static let domainComponent: ASN1ObjectIdentifier = [0, 9, 2342, 19_200_300, 100, 1, 25]
/// The `emailAddress` attribute type contains email address defined in PCKS#9 (RFC2985).
/// Be aware that, modern best practices (e.g., RFC 5280) discourage embedding email addresses in the `Subject DN` instead it should be in `Subject Alternative Name (SAN)
/// The `emailAddress` attribute type contains an email address defined in PKCS#9 (RFC 2985).
/// Modern best practices (e.g., RFC 5280) discourage embedding email addresses in the `Subject DN`; use the `Subject Alternative Name` (SAN) instead.
public static let emailAddress: ASN1ObjectIdentifier = [1, 2, 840, 113549, 1, 9, 1]
}
}
+2 -2
View File
@@ -26,8 +26,8 @@ import _CertificateInternals
/// contains one or more ``RelativeDistinguishedName/Attribute`` which are considered equivalent: that is, they
/// are each a representation of the same piece of information.
///
/// ``RelativeDistinguishedName``s are organised into a hierarchy in a ``DistinguishedName``, in order from least
/// to most specific. In almost all current use-cases a ``RelativeDistinguishedName`` will contain only a single
/// ``RelativeDistinguishedName``s are organized into a hierarchy in a ``DistinguishedName``, in order from least
/// to most specific. In almost all current use cases a ``RelativeDistinguishedName`` will contain only a single
/// ``Attribute``.
///
/// Note that ``RelativeDistinguishedName`` does not have a stable ordering of its elements. Inserting an element
+6 -5
View File
@@ -23,19 +23,19 @@ import Foundation
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// An abstract representation of the cryptographic signature on a certificate.
/// A cryptographic signature on a certificate.
///
/// Certificates may have a wide range of signature types. This type provides a runtime
/// abstraction across these types. It ensures that we understand the algorithm used to
/// sign the certificate, and enables us to provide verification logic, without forcing
/// users to wrestle with the wide variety of runtime types that may represent a
/// abstraction across these types. It ensures that the algorithm used to
/// sign the certificate is understood, and enables verification logic, without forcing
/// you to wrestle with the wide variety of runtime types that may represent a
/// signature.
///
/// This type is almost entirely opaque. It can be validated by way of
/// ``Certificate/PublicKey-swift.struct/isValidSignature(_:for:)-3cbor``, and it
/// can be generated by ``Certificate/PrivateKey``s automatically when
/// used by ``Certificate/init(version:serialNumber:publicKey:notValidBefore:notValidAfter:issuer:subject:signatureAlgorithm:extensions:issuerPrivateKey:)``.
/// Otherwise, this type has essentially no behaviours.
/// Otherwise, this type has essentially no behaviors.
public struct Signature {
@usableFromInline
var backing: BackingSignature
@@ -45,6 +45,7 @@ extension Certificate {
self.backing = backing
}
/// Creates a signature from an algorithm identifier and raw signature bytes.
@inlinable
public init(signatureAlgorithm: SignatureAlgorithm, signatureBytes: ASN1BitString) throws {
switch signatureAlgorithm {
+2 -2
View File
@@ -14,13 +14,13 @@
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension Certificate {
/// A representation of a kind of signature algorithm.
/// A signature algorithm identifier.
///
/// X.509 certificates support a wide range of signature algorithms. This type
/// identifies the algorithm, independently of the signature itself.
///
/// This type represents an unbounded enumeration. There are potentially infinite
/// signature algorithms. Users are able to create representations of the signature
/// signature algorithms. You can create representations of the signature
/// algorithms this library supports by using static fields on this type.
public struct SignatureAlgorithm {
@usableFromInline
+4 -5
View File
@@ -14,7 +14,7 @@
import _CertificateInternals
/// A collection of ``Certificate`` objects for use in a verifier.
/// A collection of certificates for use in verification.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public struct CertificateStore: Sendable, Hashable {
@@ -27,7 +27,7 @@ public struct CertificateStore: Sendable, Hashable {
}
/// Wrap a ``CustomCertificateStore`` in a ``CertificateStore`` so the custom
/// implementation it can be used interchangeably. For details on why one
/// implementation can be used interchangeably. For details on why one
/// may decide to implement a ``CustomCertificateStore``, please see the
/// documentation on that protocol.
@inlinable
@@ -63,9 +63,8 @@ public struct CertificateStore: Sendable, Hashable {
}
@inlinable
public func appending(_ certificate: Certificate) -> Self {
var copy = self
copy.append(certificate)
public consuming func appending(_ certificate: Certificate) -> Self {
append(certificate)
return self
}
@@ -12,23 +12,23 @@
//
//===----------------------------------------------------------------------===//
/// Implement the ``CustomCertificateStore`` if you want to perform dynamic
/// certificate lookup, or if you need custom logic when matching the
/// ``DistinguishedName`` of an Issuer with the Subject of the issuer
/// certificate, then implement a custom certificate store used by the
/// ```Verifier```.
/// A protocol for certificate stores that perform dynamic lookup or custom matching logic.
///
/// Implement this protocol if you need to perform dynamic certificate lookup
/// or custom logic when matching the ``DistinguishedName`` of an issuer with
/// the subject of the issuer certificate.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public protocol CustomCertificateStore: Sendable, Hashable {
/// Obtain a list of certificates which has a given subject. Note that this
/// is an async method so that database lookups can be performed
/// asynchronously.
/// Returns the certificates that have the given subject, if any.
///
/// This is an async method so that database lookups can be performed asynchronously.
subscript(subject: DistinguishedName) -> [Certificate]? {
get async
}
/// Validate if a given certificate is known to exist in this certificate
/// store. Note that this is an async method so that the existence check
/// can be performed against a database.
/// Returns a Boolean value that indicates whether this store contains the given certificate.
///
/// This is an async method so that the existence check can be performed against a database.
func contains(_ certificate: Certificate) async -> Bool
/// Add a certificate to this certificate store.
+2 -2
View File
@@ -14,9 +14,9 @@
import SwiftASN1
/// Provides a result-builder style DSL for constructing a ``VerifierPolicy``.
/// A result-builder DSL for constructing a ``VerifierPolicy``.
///
/// This DSL allows us to construct dynamic ``VerifierPolicy`` at runtime without using type erasure.
/// This DSL allows constructing dynamic ``VerifierPolicy`` values at runtime without using type erasure.
/// The resulting ``VerifierPolicy`` will use the listed policy in the order of declaration to check if a chain meets all policies.
/// For Example, a simple ``Verifier`` with a simple policy can be constructed like this:
/// ```swift
@@ -18,7 +18,7 @@ import Foundation
#endif
import SwiftASN1
/// A ``VerifierPolicy`` that implements the core chain verifying policies from RFC 5280.
/// A ``VerifierPolicy`` that implements the core chain verification policies from RFC 5280.
///
/// Almost all verifiers should use this policy as the initial component of their policy set. The policy checks the
/// following things:
@@ -28,7 +28,7 @@ import Glibc
import Musl
#endif
/// A ``VerifierPolicy`` that validates that the leaf certificate is authoritative
/// A ``VerifierPolicy`` that checks whether the leaf certificate is authoritative
/// for a given hostname or IP address.
///
/// This policy is most commonly used to validate the leaf certificate presented by a server
@@ -48,7 +48,7 @@ public struct ServerIdentityPolicy: Sendable {
/// Constructs a new ``ServerIdentityPolicy``.
///
/// - parameters:
/// - Parameters:
/// - serverHostname: The hostname used to connect to the server.
/// - serverIP: The IP address of the server, if known.
@inlinable
@@ -12,9 +12,9 @@
//
//===----------------------------------------------------------------------===//
/// A validated certificate chain that traces the trust from a leaf to a root certificate. This type does not perform any validation
/// itself. It is a container that gives information about the contained certificates. The safe method to acquire it goes through
/// the certificate validation processes in a `Verifier`.
/// A validated certificate chain from leaf to root. This type does not perform any validation
/// itself. It gives information about the contained certificates. Acquire it through
/// the certificate validation process in a ``Verifier``.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public struct ValidatedCertificateChain: Sendable, Collection, RandomAccessCollection, Hashable {
@usableFromInline
@@ -34,8 +34,7 @@ public struct ValidatedCertificateChain: Sendable, Collection, RandomAccessColle
self.validatedChain[index]
}
/// Creates a `ValidatedCertificateChain` that represents a chain of trust. The chain should be ordered
/// from leaf to root and (with the exception of the root) each certificate should be issued by the owner of the subsequent
/// Creates a `ValidatedCertificateChain`. Order the chain from leaf to root; each certificate (except the root) should be issued by the owner of the subsequent
/// certificate. Since the leaf and root certificate can be identical, a certificate chain must have at least one element.
///
/// It is recommended to go through the verification process using `X509/Verifier/Verifier` with a
@@ -69,7 +69,7 @@ public struct VerificationDiagnostic: Sendable {
}
/// - Note: all ``LoadingTrustRootsFailed`` are considered equal,
/// best we can because the underlying storage type ``Error`` doesn't conform to Eqautable
/// best we can because the underlying storage type ``Error`` doesn't conform to Equatable
struct LoadingTrustRootsFailed: Hashable, Sendable {
var error: any Error
+21
View File
@@ -13,18 +13,33 @@
//===----------------------------------------------------------------------===//
import SwiftASN1
/// Validates an X.509 certificate chain against a set of root certificates and a ``VerifierPolicy``.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public struct Verifier<Policy: VerifierPolicy> {
/// The trusted root certificates used to anchor chain validation.
public var rootCertificates: CertificateStore
/// The policy applied to candidate chains during validation.
public var policy: Policy
/// Creates a verifier with the given root certificates and policy.
///
/// - Parameters:
/// - rootCertificates: The trusted root certificates.
/// - policy: A ``PolicyBuilder`` closure that returns the verification policy.
@inlinable
public init(rootCertificates: CertificateStore, @PolicyBuilder policy: () throws -> Policy) rethrows {
self.rootCertificates = rootCertificates
self.policy = try policy()
}
/// Validates a leaf certificate by building chains through intermediate certificates to the root store.
///
/// - Parameters:
/// - leaf: The leaf certificate to validate.
/// - intermediates: A store of intermediate certificates that may form part of the chain.
/// - diagnosticCallback: An optional closure invoked with diagnostic events during validation.
/// - Returns: A ``CertificateValidationResult`` indicating whether the certificate is valid.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public mutating func validate(
leaf: Certificate,
@@ -244,16 +259,22 @@ extension VerificationResult {
}
}
/// The result of validating a certificate chain.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public enum CertificateValidationResult: Hashable, Sendable {
/// The certificate chain is valid and trusted.
case validCertificate(ValidatedCertificateChain)
/// The certificate chain could not be validated, with the associated policy failures.
case couldNotValidate([PolicyFailure])
}
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension CertificateValidationResult {
/// A candidate chain that failed to meet a verification policy.
public struct PolicyFailure: Hashable, Sendable {
/// The candidate certificate chain that failed validation.
public var chain: UnverifiedCertificateChain
/// The reason the policy rejected this chain.
public var policyFailureReason: PolicyFailureReason
@inlinable
+7 -3
View File
@@ -13,7 +13,7 @@
//===----------------------------------------------------------------------===//
import SwiftASN1
/// A ``VerifierPolicy`` implements a series of checks on an ``UnverifiedCertificateChain`` in order to determine
/// A ``VerifierPolicy`` implements a series of checks on an ``UnverifiedCertificateChain`` to determine
/// whether that chain should be trusted.
///
/// Certificate verification is split into two parts: chain building and policy enforcement. Chain building is general:
@@ -21,13 +21,13 @@ import SwiftASN1
/// the form of ``UnverifiedCertificateChain``.
///
/// Each of these candidate chains is then handed to a ``VerifierPolicy`` to be checked against the certificate policy.
/// The reason for this is to allow different use-cases to share the same chain building code, but to enforce
/// The reason for this is to allow different use cases to share the same chain building code, but to enforce
/// different requirements on the chain.
///
/// Some ``VerifierPolicy`` objects are used frequently and are very common, such as ``RFC5280Policy`` which implements
/// the basic checks from that RFC. Other objects are less common, such as ``OCSPVerifierPolicy``, which performs live
/// revocation checking. Users can also implement their own policies to enable swift-certificates to support other
/// use-cases.
/// use cases.
@preconcurrency
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
public protocol VerifierPolicy: _X509SendableMetatype {
@@ -55,8 +55,11 @@ public protocol VerifierPolicy: _X509SendableMetatype {
mutating func chainMeetsPolicyRequirements(chain: UnverifiedCertificateChain) async -> PolicyEvaluationResult
}
/// The result of evaluating a ``VerifierPolicy`` against a candidate certificate chain.
public enum PolicyEvaluationResult: Sendable {
/// The chain meets the policy requirements.
case meetsPolicy
/// The chain fails to meet the policy requirements, with the associated reason.
case failsToMeetPolicy(PolicyFailureReason)
public static func failsToMeetPolicy(reason makeReason: @autoclosure @Sendable @escaping () -> String) -> Self {
@@ -68,6 +71,7 @@ public enum PolicyEvaluationResult: Sendable {
}
}
/// A description of why a certificate chain failed to meet a verification policy.
public struct PolicyFailureReason: Sendable {
var storage: @Sendable () -> String