Refactor tests, add documentation and fix bugs (#19)

* add swiftlint package plugin

* remove deprecated (by WebAuthn) token bindings

* add packed attestation format

* add comment

* remove lint plugin since its broken

* clean up authentication flow

* add authentication tests

* add wip tpm attestation format

* first readme draft

* add more content

* Update README.md

* update readme

* wip tpm verify

* add TPM pubArea parsing

* add wip fuzzying

* wip TPM attestation format

* add attestation option

* add swift certificates

* drop rsa and okp support temporarily

* wip refactor tests

* update tests

* fix authentication succeeds test

* rename User to WebAuthnUser

* fix ci

* fix ci

* fix happy path test

* add coments and refactor WebAuthnConfig

* make VerifiedAuthentication properties public

* add limitations

* add comments

* Split tests into two classes

* Add WebAuthnConfig comments

* small fixes

Author: marius-se

.swiftlint.yml

@@ -1,4 +1,12 @@
 disabled_rules:
- - comment_spacing
+  - comment_spacing
 excluded:
- - .build
+  - .build
+
+
+identifier_name:
+  excluded:
+    - id
+
+line_length:
+  ignores_comments: true

Package.swift

@@ -26,7 +26,8 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/unrelentingtech/SwiftCBOR.git", from: "0.4.5"),
         .package(url: "https://github.com/apple/swift-crypto.git", from: "2.0.0"),
-        .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0")
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-certificates.git", branch: "main")
     ],
     targets: [
         .target(
@@ -35,7 +36,8 @@ let package = Package(
                 "SwiftCBOR",
                 .product(name: "Crypto", package: "swift-crypto"),
                 .product(name: "_CryptoExtras", package: "swift-crypto"),
-                .product(name: "Logging", package: "swift-log")
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "X509", package: "swift-certificates")
             ]
         ),
         .testTarget(name: "WebAuthnTests", dependencies: [

README.md

@@ -45,6 +45,21 @@ interface with a client that will handle calling the WebAuthn API:
    - `public typealias URLEncodedBase64 = String`
    - `public typealias EncodedBase64 = String`
 
+## Limitations
+
+There are a few things this library currently does **not** support:
+
+1. Currently RSA public keys are not support, we do however plan to add support for that. RSA keys are necessary for
+   compatibility with Microsoft Windows platform authenticators.
+
+2. Octet key pairs are not supported.
+
+3. Attestation verification is currently not supported, we do however plan to add support for that. Some work has been
+   done already, but there are more pieces missing. In most cases attestation verification is not recommended since it
+   causes a lot of overhead. [From Yubico](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html):
+   > "If a service does not have a specific need for attestation information, namely a well defined policy for what to
+     do with it and why, it is not recommended to verify authenticator attestations"
+
 ### Setup
 
 Configure your backend with a `WebAuthnManager` instance:

Sources/WebAuthn/Ceremonies/Authentication/AuthenticatorAssertionResponse.swift

@@ -12,6 +12,9 @@
 //
 //===----------------------------------------------------------------------===//
 
+import Foundation
+import Crypto
+
 /// This is what the authenticator device returned after we requested it to authenticate a user.
 public struct AuthenticatorAssertionResponse: Codable {
     /// Representation of what we passed to `navigator.credentials.get()`
@@ -29,3 +32,72 @@ public struct AuthenticatorAssertionResponse: Codable {
     /// data is provided directly in an AuthenticatorAssertionResponse structure.
     public let attestationObject: String?
 }
+
+struct ParsedAuthenticatorAssertionResponse {
+    let rawClientData: Data
+    let clientData: CollectedClientData
+    let rawAuthenticatorData: Data
+    let authenticatorData: AuthenticatorData
+    let signature: URLEncodedBase64
+    let userHandle: String?
+
+    init(from authenticatorAssertionResponse: AuthenticatorAssertionResponse) throws {
+        guard let clientDataData = authenticatorAssertionResponse.clientDataJSON.urlDecoded.decoded else {
+            throw WebAuthnError.invalidClientDataJSON
+        }
+        rawClientData = clientDataData
+        clientData = try JSONDecoder().decode(CollectedClientData.self, from: clientDataData)
+
+        guard let authenticatorDataBytes = authenticatorAssertionResponse.authenticatorData.urlDecoded.decoded else {
+            throw WebAuthnError.invalidAuthenticatorData
+        }
+        rawAuthenticatorData = authenticatorDataBytes
+        authenticatorData = try AuthenticatorData(bytes: authenticatorDataBytes)
+        signature = authenticatorAssertionResponse.signature
+        userHandle = authenticatorAssertionResponse.userHandle
+    }
+
+    // swiftlint:disable:next function_parameter_count
+    func verify(
+        expectedChallenge: URLEncodedBase64,
+        relyingPartyOrigin: String,
+        relyingPartyID: String,
+        requireUserVerification: Bool,
+        credentialPublicKey: [UInt8],
+        credentialCurrentSignCount: UInt32
+    ) throws {
+        try clientData.verify(
+            storedChallenge: expectedChallenge,
+            ceremonyType: .assert,
+            relyingPartyOrigin: relyingPartyOrigin
+        )
+
+        guard let expectedRpIDData = relyingPartyID.data(using: .utf8) else {
+            throw WebAuthnError.invalidRelyingPartyID
+        }
+        let expectedRpIDHash = SHA256.hash(data: expectedRpIDData)
+        guard expectedRpIDHash == authenticatorData.relyingPartyIDHash else {
+            throw WebAuthnError.relyingPartyIDHashDoesNotMatch
+        }
+
+        guard authenticatorData.flags.userPresent else { throw WebAuthnError.userPresentFlagNotSet }
+        if requireUserVerification {
+            guard authenticatorData.flags.userVerified else { throw WebAuthnError.userVerifiedFlagNotSet }
+        }
+
+        if authenticatorData.counter > 0 || credentialCurrentSignCount > 0 {
+            guard authenticatorData.counter > credentialCurrentSignCount else {
+                // This is a signal that the authenticator may be cloned, i.e. at least two copies of the credential
+                // private key may exist and are being used in parallel.
+                throw WebAuthnError.potentialReplayAttack
+            }
+        }
+
+        let clientDataHash = SHA256.hash(data: rawClientData)
+        let signatureBase = rawAuthenticatorData + clientDataHash
+
+        let credentialPublicKey = try CredentialPublicKey(publicKeyBytes: credentialPublicKey)
+        guard let signatureData = signature.urlDecoded.decoded else { throw WebAuthnError.invalidSignature }
+        try credentialPublicKey.verify(signature: signatureData, data: signatureBase)
+    }
+}

Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift

@@ -16,31 +16,49 @@ import Foundation
 
 /// The `PublicKeyCredentialRequestOptions` gets passed to the WebAuthn API (`navigator.credentials.get()`)
 public struct PublicKeyCredentialRequestOptions: Codable {
+    /// A challenge that the authenticator signs, along with other data, when producing an authentication assertion
     public let challenge: EncodedBase64
+    /// A `TimeInterval`, that the Relying Party is willing to wait for the call to complete. The value is treated
+    /// as a hint, and may be overridden by the client.
     public let timeout: TimeInterval?
+    /// The Relying Party ID.
     public let rpId: String?
+    /// Optionally used by the client to find authenticators eligible for this authentication ceremony.
     public let allowCredentials: [PublicKeyCredentialDescriptor]?
+    /// Specifies whether the user should be verified during the authentication ceremony.
     public let userVerification: UserVerificationRequirement?
-    public let attestation: String?
-    public let attestationFormats: [String]?
     // let extensions: [String: Any]
 }
 
-public struct PublicKeyCredentialDescriptor: Codable {
-    public enum AuthenticatorTransport: String, Codable {
+/// Information about a generated credential.
+public struct PublicKeyCredentialDescriptor: Codable, Equatable {
+    /// Defines hints as to how clients might communicate with a particular authenticator in order to obtain an
+    /// assertion for a specific credential
+    public enum AuthenticatorTransport: String, Codable, Equatable {
+        /// Indicates the respective authenticator can be contacted over removable USB.
         case usb
+        /// Indicates the respective authenticator can be contacted over Near Field Communication (NFC).
         case nfc
+        /// Indicates the respective authenticator can be contacted over Bluetooth Smart (Bluetooth Low Energy / BLE).
         case ble
+        /// Indicates the respective authenticator can be contacted using a combination of (often separate)
+        /// data-transport and proximity mechanisms. This supports, for example, authentication on a desktop
+        /// computer using a smartphone.
         case hybrid
+        /// Indicates the respective authenticator is contacted using a client device-specific transport, i.e., it is
+        /// a platform authenticator. These authenticators are not removable from the client device.
         case `internal`
     }
 
     enum CodingKeys: String, CodingKey {
         case type, id, transports
     }
 
+    /// Will always be 'public-key'
     public let type: String
+    /// The sequence of bytes representing the credential's ID
     public let id: [UInt8]
+    /// The types of connections to the client/browser the authenticator supports
     public let transports: [AuthenticatorTransport]
 
     public init(type: String, id: [UInt8], transports: [AuthenticatorTransport] = []) {
@@ -58,8 +76,15 @@ public struct PublicKeyCredentialDescriptor: Codable {
     }
 }
 
+/// The Relying Party may require user verification for some of its operations but not for others, and may use this
+/// type to express its needs.
 public enum UserVerificationRequirement: String, Codable {
+    /// The Relying Party requires user verification for the operation and will fail the overall ceremony if the
+    /// user wasn't verified.
     case required
+    /// The Relying Party prefers user verification for the operation if possible, but will not fail the operation.
     case preferred
+    /// The Relying Party does not want user verification employed during the operation (e.g., in the interest of
+    /// minimizing disruption to the user interaction flow).
     case discouraged
 }

Sources/WebAuthn/Ceremonies/Authentication/VerifiedAuthentication.swift

@@ -7,8 +7,13 @@ public struct VerifiedAuthentication {
         case multiDevice = "multi_device"
     }
 
-    let credentialID: URLEncodedBase64
-    let newSignCount: UInt32
-    let credentialDeviceType: CredentialDeviceType
-    let credentialBackedUp: Bool
+    /// The credential id associated with the public key
+    public let credentialID: URLEncodedBase64
+    /// The updated sign count after the authentication ceremony
+    public let newSignCount: UInt32
+    /// Whether the authenticator is a single- or multi-device authenticator. This value is determined after
+    /// registration and will not change afterwards.
+    public let credentialDeviceType: CredentialDeviceType
+    /// Whether the authenticator is known to be backed up currently
+    public let credentialBackedUp: Bool
 }

Sources/WebAuthn/Ceremonies/Registration/AttestationConveyancePreference.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the WebAuthn Swift open source project
+//
+// Copyright (c) 2022 the WebAuthn Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of WebAuthn Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// Options to specify the Relying Party's preference regarding attestation conveyance during credential generation.
+///
+/// Currently only supports `none`.
+public enum AttestationConveyancePreference: String, Codable {
+    /// Indicates the Relying Party is not interested in authenticator attestation.
+    case none
+    // case indirect
+    // case direct
+    // case enterprise
+}

Sources/WebAuthn/Ceremonies/Registration/AttestationObject.swift

@@ -12,17 +12,24 @@
 //
 //===----------------------------------------------------------------------===//
 
+import Foundation
 import Crypto
 import SwiftCBOR
 
 /// Contains the cryptographic attestation that a new key pair was created by that authenticator.
-public struct AttestationObject: Equatable {
+public struct AttestationObject {
     let authenticatorData: AuthenticatorData
-    let rawAuthenticatorData: [UInt8]
+    let rawAuthenticatorData: Data
     let format: AttestationFormat
     let attestationStatement: CBOR
 
-    func verify(relyingPartyID: String, verificationRequired: Bool, clientDataHash: SHA256.Digest) throws {
+    func verify(
+        relyingPartyID: String,
+        verificationRequired: Bool,
+        clientDataHash: SHA256.Digest,
+        supportedPublicKeyAlgorithms: [PublicKeyCredentialParameters],
+        pemRootCertificatesByFormat: [AttestationFormat: [Data]] = [:]
+    ) async throws -> AttestedCredentialData {
         let relyingPartyIDHash = SHA256.hash(data: relyingPartyID.data(using: .utf8)!)
 
         guard relyingPartyIDHash == authenticatorData.relyingPartyIDHash else {
@@ -39,14 +46,44 @@ public struct AttestationObject: Equatable {
             }
         }
 
+        guard let attestedCredentialData = authenticatorData.attestedData else {
+            throw WebAuthnError.attestedCredentialDataMissing
+        }
+
+        // Step 17.
+        let credentialPublicKey = try CredentialPublicKey(publicKeyBytes: attestedCredentialData.publicKey)
+        guard supportedPublicKeyAlgorithms.map(\.alg).contains(credentialPublicKey.key.algorithm) else {
+            throw WebAuthnError.unsupportedCredentialPublicKeyAlgorithm
+        }
+
+        // let pemRootCertificates = pemRootCertificatesByFormat[format] ?? []
         switch format {
         case .none:
             // if format is `none` statement must be empty
             guard attestationStatement == .map([:]) else {
                 throw WebAuthnError.attestationStatementMustBeEmpty
             }
+        // case .packed:
+        //     try await PackedAttestation.verify(
+        //         attStmt: attestationStatement,
+        //         authenticatorData: rawAuthenticatorData,
+        //         clientDataHash: Data(clientDataHash),
+        //         credentialPublicKey: credentialPublicKey,
+        //         pemRootCertificates: pemRootCertificates
+        //     )
+        // case .tpm:
+        //     try TPMAttestation.verify(
+        //         attStmt: attestationStatement,
+        //         authenticatorData: rawAuthenticatorData,
+        //         attestedCredentialData: attestedCredentialData,
+        //         clientDataHash: Data(clientDataHash),
+        //         credentialPublicKey: credentialPublicKey,
+        //         pemRootCertificates: pemRootCertificates
+        //     )
         default:
             throw WebAuthnError.attestationVerificationNotSupported
         }
+
+        return attestedCredentialData
     }
 }

Sources/WebAuthn/Ceremonies/Registration/AttestedCredentialData.swift

@@ -13,7 +13,7 @@
 //===----------------------------------------------------------------------===//
 
 // Contains the new public key created by the authenticator.
-struct AttestedCredentialData: Codable, Equatable {
+struct AttestedCredentialData: Equatable {
     let aaguid: [UInt8]
     let credentialID: [UInt8]
     let publicKey: [UInt8]

Sources/WebAuthn/Ceremonies/Registration/AuthenticatorAttestationResponse.swift

@@ -56,7 +56,7 @@ struct ParsedAuthenticatorAttestationResponse {
 
         attestationObject = AttestationObject(
             authenticatorData: try AuthenticatorData(bytes: Data(authDataBytes)),
-            rawAuthenticatorData: authDataBytes,
+            rawAuthenticatorData: Data(authDataBytes),
             format: attestationFormat,
             attestationStatement: attestationStatement
         )