diff --git a/Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift b/Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift index fb09703..0eed662 100644 --- a/Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift +++ b/Sources/WebAuthn/Ceremonies/Authentication/PublicKeyCredentialRequestOptions.swift @@ -19,7 +19,7 @@ import Foundation /// /// - SeeAlso: https://www.w3.org/TR/webauthn-2/#dictionary-assertion-options public struct PublicKeyCredentialRequestOptions: Sendable { - /// A challenge that the authenticator signs, along with other data, when producing an authentication assertion + /// A challenge that the authenticator signs, along with other data, when producing an authentication assertion. /// /// When encoding using `Encodable` this is encoded as base64url. public var challenge: [UInt8] @@ -45,6 +45,16 @@ public struct PublicKeyCredentialRequestOptions: Sendable { // let extensions: [String: Any] + /// Initialize a credential request options dictionary directly. + /// + /// - Warning: Manually initializing options dictionaries can easily lead to insecure implementations of the WebAuthn protocol. Whenever possible, create an options dictionary using ``WebAuthnManager/beginAuthentication(timeout:allowCredentials:userVerification:)`` instead. + /// + /// - Parameters: + /// - challenge: A challenge that the authenticator signs, along with other data, when producing an authentication assertion. + /// - timeout: A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client. + /// - relyingPartyID: The ID of the Relying Party making the request. + /// - allowCredentials: Optionally used by the client to find authenticators eligible for this authentication ceremony. + /// - userVerification: Specifies whether the user should be verified during the authentication ceremony. public init( challenge: [UInt8], timeout: Duration?, diff --git a/Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift b/Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift index dfa7242..7a37164 100644 --- a/Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift +++ b/Sources/WebAuthn/Ceremonies/Registration/PublicKeyCredentialCreationOptions.swift @@ -27,26 +27,34 @@ public struct PublicKeyCredentialCreationOptions: Sendable { /// encoding using `Encodable`, the challenge is base64url encoded. public let challenge: [UInt8] - /// Contains names and an identifier for the user account performing the registration + /// Contains names and an identifier for the user account performing the registration. public var user: PublicKeyCredentialUserEntity - /// Contains a name and an identifier for the Relying Party responsible for the request + /// Contains a name and an identifier for the Relying Party responsible for the request. public var relyingParty: PublicKeyCredentialRelyingPartyEntity - /// A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least - /// preferred. + /// A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least preferred. public var publicKeyCredentialParameters: [PublicKeyCredentialParameters] - /// A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a - /// hint, and may be overridden by the client. + /// A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client. /// /// - Note: When encoded, this value is represented in milleseconds as a ``UInt32``. public var timeout: Duration? - /// Sets the Relying Party's preference for attestation conveyance. At the time of writing only `none` is - /// supported. + /// Sets the Relying Party's preference for attestation conveyance. At the time of writing only ``AttestationConveyancePreference/none`` is supported. public var attestation: AttestationConveyancePreference + /// Initialize a credential creation options dictionary directly. + /// + /// - Warning: Manually initializing options dictionaries can easily lead to insecure implementations of the WebAuthn protocol. Whenever possible, create an options dictionary using ``WebAuthnManager/beginRegistration(user:timeout:attestation:publicKeyCredentialParameters:)`` instead. + /// + /// - Parameters: + /// - challenge: A byte array randomly generated by the Relying Party. Should be at least 16 bytes long to ensure sufficient entropy. + /// - user: Contains names and an identifier for the user account performing the registration. + /// - relyingParty: Contains a name and an identifier for the Relying Party responsible for the request. + /// - publicKeyCredentialParameters: A list of key types and signature algorithms the Relying Party supports. Ordered from most preferred to least preferred. + /// - timeout: A time, in seconds, that the caller is willing to wait for the call to complete. This is treated as a hint, and may be overridden by the client. + /// - attestation: Sets the Relying Party's preference for attestation conveyance. At the time of writing only `none` is supported. public init( challenge: [UInt8], user: PublicKeyCredentialUserEntity, diff --git a/Sources/WebAuthn/WebAuthnManager.swift b/Sources/WebAuthn/WebAuthnManager.swift index 299089b..feebb20 100644 --- a/Sources/WebAuthn/WebAuthnManager.swift +++ b/Sources/WebAuthn/WebAuthnManager.swift @@ -46,7 +46,10 @@ public struct WebAuthnManager: Sendable { /// Generate a new set of registration data to be sent to the client. /// - /// This method will use the Relying Party information from the WebAuthnManager's configuration to create ``PublicKeyCredentialCreationOptions`` + /// This method will use the Relying Party information from the WebAuthnManager's configuration to create a ready-to-consume ``PublicKeyCredentialCreationOptions`` on the client. + /// + /// - Important: You must store the ``PublicKeyCredentialCreationOptions/challenge`` value returned by this method and validate against it during the ``finishRegistration(challenge:credentialCreationData:requireUserVerification:supportedPublicKeyAlgorithms:pemRootCertificatesByFormat:confirmCredentialIDNotRegisteredYet:)`` phase of registration. + /// /// - Parameters: /// - user: The user to register. /// - timeout: How long the browser should give the user to choose an authenticator. This value @@ -126,7 +129,9 @@ public struct WebAuthnManager: Sendable { ) } - /// Generate options for retrieving a credential via navigator.credentials.get() + /// Generate options for retrieving a credential via `navigator.credentials.get()`. + /// + /// - Important: You must store the ``PublicKeyCredentialRequestOptions/challenge`` value returned by this method and validate against it during the ``finishAuthentication(credential:expectedChallenge:credentialPublicKey:credentialCurrentSignCount:requireUserVerification:)`` phase of authentication. /// /// - Parameters: /// - timeout: How long the browser should give the user to choose an authenticator. This value