Class WebAuthnRelyingPartyOperations

java.lang.Object
com.codename1.backend.security.webauthn.WebAuthnRelyingPartyOperations
public final class WebAuthnRelyingPartyOperations extends Object

The two passkey ceremonies, as the relying party performs them: making the options a client starts from, and verifying what the authenticator answered. Registration follows section 7.1 of the WebAuthn specification and sign-in section 7.2.

http.webAuthn(...) makes one and puts it behind the endpoints. An application that serves the ceremonies itself uses it directly:

WebAuthnRelyingPartyOperations passkeys = new WebAuthnRelyingPartyOperations(
        new PublicKeyCredentialRpEntity("example.com", "Example"),
        Arrays.asList("https://example.com"), userEntities, credentials);

PublicKeyCredentialCreationOptions options =
        passkeys.createPublicKeyCredentialCreationOptions("ada");
// ... keep options.toMap() for this user, send it, and with the answer:
CredentialRecord made = passkeys.registerCredential(options, answer, "Ada's phone");

What this class does not do is keep a ceremony's options between its two requests, give a challenge a lifetime, or see that it is used once: the caller holds the options and hands them back. The endpoints of http.webAuthn(...) keep them in the session, for five minutes, and take them out before they look at the answer.

What is verified

Both ceremonies: that the client data is of the right ceremony, carries this challenge, and names an origin among those allowed -- compared as text, in full -- and no frame of another origin; that the authenticator answered for this relying party; that the user was present, and verified when the options required it; that the backup flags are possible.

Registration: that the credential's key is ES256 or RS256; the attestation, which must be none, or packed signed by the credential's own key -- any other is refused by name unless setAllowUnverifiedAttestation(boolean); and that no credential has this id.

Sign-in: that the credential is registered and, when the user said who they are first, is one of theirs; that the user the answer names owns it; the signature, over the authenticator data and the hash of the client data; that the signature counter moved forward; that the credential is as eligible for backup as when it was made.

A refusal is a WebAuthnException whose reason says which of these it was.

  • Constructor Details

  • Method Details

    • setUserVerification

      public void setUserVerification(String userVerification)
      Whether the authenticator must verify the user -- required -- should when it can -- preferred, the default -- or need not: discouraged.

    • setResidentKey

      public void setResidentKey(String residentKey)
      Whether a new credential must be one a sign-in can find without being told the user: required, the default, which is what makes it a passkey; preferred; or discouraged.

    • setAuthenticatorAttachment

      public void setAuthenticatorAttachment(String authenticatorAttachment)
      platform for the device's own authenticator, cross-platform for a security key, or null -- the default -- for either.

    • setTimeoutMillis

      public void setTimeoutMillis(long timeoutMillis)
      The timeout the options carry, in milliseconds; five minutes unless set.

    • setAllowUnverifiedAttestation

      public void setAllowUnverifiedAttestation(boolean allowUnverifiedAttestation)

      Whether a registration whose attestation this server cannot verify -- packed with a certificate chain, tpm, apple, android-key, fido-u2f and the rest -- is accepted as if it carried none. Off unless set: such a registration is refused with a message that names the format.

      Accepting one loses nothing a server that asks for no attestation relies on: the statement vouches for the authenticator's make, and the credential is verified at every sign-in either way. It is off so that a format nobody looked at is noticed rather than waved through.

    • setAllowCrossOrigin

      public void setAllowCrossOrigin(boolean allowCrossOrigin)
      Whether a ceremony may run inside a frame of another origin than the page around it. Off unless set.

    • setClock

      public void setClock(Clock clock)
      The clock records are dated from; for tests.

    • setSignatureCounterListener

      public void setSignatureCounterListener(WebAuthnRelyingPartyOperations.SignatureCounterListener listener)
      What is told of a signature counter that did not advance.

    • getRp

      public PublicKeyCredentialRpEntity getRp()

    • getUserEntities

      public PublicKeyCredentialUserEntityRepository getUserEntities()
      The user entities this was made with.

    • getUserCredentials

      public UserCredentialRepository getUserCredentials()
      The credentials this was made with.

    • createPublicKeyCredentialCreationOptions

      public PublicKeyCredentialCreationOptions createPublicKeyCredentialCreationOptions(String username)
      The options for username to make a passkey with. Gives the user a handle if they have none, and lists the credentials they have so that an authenticator holding one of them makes no second.

    • registerCredential

      public CredentialRecord registerCredential(PublicKeyCredentialCreationOptions options, Map credential, String label)
      Verifies the answer to options and stores the credential.
      Parameters:
      options - what the client was given, as kept since
      credential - the client's answer, parsed: the WebAuthn RegistrationResponseJSON
      label - what the user calls the passkey; may be null
      Returns:
      the credential as stored
      Throws:
      WebAuthnException - when the answer is refused

    • createCredentialRequestOptions

      public PublicKeyCredentialRequestOptions createCredentialRequestOptions(String username)
      The options to sign in with.
      Parameters:
      username - the user, when they said who they are first: the options then list their credentials, and only one of those is accepted. Null for a sign-in that names nobody, which any passkey of this relying party may answer. A name with no passkey gets the same options as null.

    • authenticate

      public WebAuthnRelyingPartyOperations.Assertion authenticate(PublicKeyCredentialRequestOptions options, Map credential)
      Verifies the answer to options, and records the sign-in on the credential.
      Parameters:
      options - what the client was given, as kept since
      credential - the client's answer, parsed: the WebAuthn AuthenticationResponseJSON
      Throws:
      WebAuthnException - when the answer is refused