• Home
• com.yubico
• webauthn-server-core
• 2.6.0-alpha7
• source code
• package-info.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.yubico.webauthn.package-info Maven / Gradle / Ivy

/**
 * This package and its subpackages make up the public API of the webauthn-server-core library.
 *
 * 
The main entry point is the {@link com.yubico.webauthn.RelyingParty} class. It provides
 * methods for generating inputs to the navigator.credentials.create() and 
 * navigator.credentials.get() methods and for processing the return values from those same
 * methods. In order to do this, the {@link com.yubico.webauthn.RelyingParty} needs an instance of
 * the {@link com.yubico.webauthn.CredentialRepository} interface to use for looking up the
 * credential IDs and public keys registered to each user, among other things.
 *
 * 
What this library does not do
 *
 * 
This library has no concept of accounts, sessions, permissions or identity federation - it
 * only deals with executing the Web Authentication authentication mechanism. Sessions,
 * account management and other higher level concepts can make use of this authentication mechanism,
 * but the authentication mechanism alone does not make a security system.
 *
 * 
Usage overview
 *
 * 
At its core, the library provides four operations:
 *
 * 

 *   
Initiate a registration operation given a user and some settings for the credential to be
 *       created
 *   
Finish a registration operation given the initiation request and the authenticator response
 *   
Initiate an authentication operation given a username
 *   
Finish an authentication operation given the initiation request and the authenticator
 *       response
 * 
 *
 * 
The "start" methods return request objects containing the parameters to be used in the call to
 * navigator.credentials.create() or navigator.credentials.get(), and the
 * "finish" methods expect a pair of such a request object and the response object returned from the
 * browser. The library itself is stateless; once constructed, a {@link
 * com.yubico.webauthn.RelyingParty} instance never modifies its fields, and the "finish" methods
 * return plain object representations of the results. These methods perform all the verification
 * logic specified by Web Authentication, but it is your responsibility as the library user to store
 * pending requests and act upon the returned results - including enforcing policies and updating
 * databases.
 *
 * 
Data classes and builders
 *
 * 
Logic classes as well as data classes in this library are all immutable, and provide builders for their construction. Most
 * builders have required parameters, which is encoded in the type system - the build()
 * method will be made available only once all required parameters have been set. The data classes
 * also each have a toBuilder() method which can be used to create a modified copy of
 * the instance.
 *
 * 
Instantiating the library
 *
 * 
The main entry point to the library is the {@link com.yubico.webauthn.RelyingParty} class,
 * which can be instantiated via its {@link com.yubico.webauthn.RelyingParty#builder() builder}.
 * Refer to the {@link com.yubico.webauthn.RelyingParty.RelyingPartyBuilder} documentation for
 * descriptions of the parameters. Of particular note is the {@link
 * com.yubico.webauthn.RelyingParty.RelyingPartyBuilder#credentialRepository(com.yubico.webauthn.CredentialRepository)
 * credentialRepository} parameter, which takes an application-specific database adapter to use for
 * looking up users' credentials. You'll need to implement the {@link
 * com.yubico.webauthn.CredentialRepository} interface with your own database access logic.
 *
 * 
Like all other classes in the library, {@link com.yubico.webauthn.RelyingParty} is stateless
 * and therefore thread safe.
 *
 * 
Registration
 *
 * 
To initiate a registration operation, construct a {@link
 * com.yubico.webauthn.StartRegistrationOptions} instance using its {@link
 * com.yubico.webauthn.StartRegistrationOptions#builder() builder} and pass that into {@link
 * com.yubico.webauthn.RelyingParty#startRegistration(StartRegistrationOptions)}. The only required
 * parameter is a {@link com.yubico.webauthn.data.UserIdentity} describing the user for which to
 * create a credential. One noteworthy part of {@link com.yubico.webauthn.data.UserIdentity} is the
 * {@link com.yubico.webauthn.data.UserIdentity#getId() id} field, containing the user handle for the
 * user. This should be a stable, unique identifier for the user - equivalent to a username, in most
 * cases. However, due to privacy
 * considerations it is recommended to set the user handle to a random byte array rather than,
 * say, the username encoded in UTF-8.
 *
 * 
The {@link com.yubico.webauthn.RelyingParty#startRegistration(StartRegistrationOptions)
 * startRegistration} method returns a {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions} which can be serialized to JSON and
 * passed as the publicKey argument to navigator.credentials.create(). You
 * can use the {@link com.yubico.webauthn.data.PublicKeyCredentialCreationOptions#toBuilder()
 * toBuilder()} method to make any modifications you need, then the {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions#toCredentialsCreateJson()} method is
 * suitable for converting the value to JSON to send to the client.
 *
 * 
You should also store the {@link com.yubico.webauthn.data.PublicKeyCredentialCreationOptions}
 * object in temporary storage so that it can later be passed as an argument to {@link
 * com.yubico.webauthn.RelyingParty#finishRegistration(FinishRegistrationOptions)}. If you need to
 * serialize the object for storage, the {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions#toJson()} and {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions#fromJson(java.lang.String)} methods
 * are suitable for serializing to and from a string value.
 *
 * 
After receiving the response from the client, use the {@link
 * com.yubico.webauthn.data.PublicKeyCredential#parseRegistrationResponseJson(java.lang.String)}
 * function to parse the response and wrap it in a {@link
 * com.yubico.webauthn.FinishRegistrationOptions} along with the {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions} used to initiate the request. Pass
 * that as the argument to {@link
 * com.yubico.webauthn.RelyingParty#finishRegistration(FinishRegistrationOptions)}, which will
 * return a {@link com.yubico.webauthn.RegistrationResult} if successful and throw an exception if
 * not. Regardless of whether it succeeds, you should remove the {@link
 * com.yubico.webauthn.data.PublicKeyCredentialCreationOptions} from the pending requests storage to
 * prevent retries.
 *
 * 
Finally, use the {@link com.yubico.webauthn.RegistrationResult} to update any database(s) and
 * take other actions depending on your application's needs. In particular:
 *
 * 

 *   
Store the {@link com.yubico.webauthn.RegistrationResult#getKeyId() keyId} and {@link
 *       com.yubico.webauthn.RegistrationResult#getPublicKeyCose() publicKeyCose} as a new
 *       credential for the user. The {@link com.yubico.webauthn.CredentialRepository} will need to
 *       look these up for authentication.
 *   
Store the {@link com.yubico.webauthn.RegistrationResult#getSignatureCount() signature
 *       counter} value in the new credential. If available, this will be used in future
 *       authentication ceremonies do detect authenticator cloning.
 *   
Optionally, store the {@link com.yubico.webauthn.RegistrationResult#isDiscoverable()
 *       isDiscoverable} flag, if present, in the new credential. This may help you determine which
 *       user interaction flows are possible with which credential.
 *   
If you care about authenticator attestation, check that the {@link
 *       com.yubico.webauthn.RegistrationResult#isAttestationTrusted() attestationTrusted} field
 *       satisfies your attestation policy. For this you will likely need to configure the {@link
 *       com.yubico.webauthn.RelyingParty.RelyingPartyBuilder#attestationTrustSource(com.yubico.webauthn.attestation.AttestationTrustSource)
 *       attestationTrustSource} setting on your {@link com.yubico.webauthn.RelyingParty} instance.
 *       See also the webauthn-server-attestation for an implementation of such an
 *       attestation trust and metadata source.
 *   
If you care about authenticator attestation, it is recommended to also store the raw {@link
 *       com.yubico.webauthn.data.AuthenticatorAttestationResponse#getAttestationObject()
 *       attestation object} as part of the credential. This enables you to retroactively inspect
 *       credential attestations in response to policy changes and/or compromised authenticators.
 * 
 *
 * 
Authentication
 *
 * 
Authentication works much like registration, except less complex because of the fewer
 * parameters and the absence of authenticator attestation complications.
 *
 * 
To initiate an authentication operation, call {@link
 * com.yubico.webauthn.RelyingParty#startAssertion(StartAssertionOptions)}. The main parameter you
 * need to set here is the {@link
 * com.yubico.webauthn.StartAssertionOptions.StartAssertionOptionsBuilder#username(java.util.Optional)
 * username} or {@link
 * com.yubico.webauthn.StartAssertionOptions.StartAssertionOptionsBuilder#userHandle(java.util.Optional)
 * user handle} of the user to authenticate, but even these parameters are optional. If neither is
 * set, then the {@link
 * com.yubico.webauthn.data.PublicKeyCredentialRequestOptions#getAllowCredentials()
 * allowCredentials} parameter will not be set. This means the user must use a client-side-discoverable
 * credential to authenticate; also known as "first-factor authentication". This use case has
 * both advantages and disadvantages; see the Web Authentication specification for an extended
 * discussion of this.
 *
 * 
The {@link com.yubico.webauthn.RelyingParty#startAssertion(StartAssertionOptions)
 * startAssertion} method returns an {@link com.yubico.webauthn.AssertionRequest} containing the
 * username, if any, and a {@link com.yubico.webauthn.data.PublicKeyCredentialRequestOptions}
 * instance which can be serialized to JSON and passed as the publicKey argument to
 * navigator.credentials.get(). Again, use {@link
 * com.yubico.webauthn.AssertionRequest#toBuilder()} to make any necessary changes, {@link
 * com.yubico.webauthn.AssertionRequest#toCredentialsGetJson()} to convert it to JSON for sending to
 * the client, and store the {@link com.yubico.webauthn.AssertionRequest} in temporary storage so it
 * can be passed as an argument to {@link
 * com.yubico.webauthn.RelyingParty#finishAssertion(com.yubico.webauthn.FinishAssertionOptions)}.
 * Again, {@link com.yubico.webauthn.AssertionRequest#toJson()} and {@link
 * com.yubico.webauthn.AssertionRequest#fromJson(java.lang.String)} can be used to convert to and
 * from JSON for storage.
 *
 * 
After receiving the response from the client, use {@link
 * com.yubico.webauthn.data.PublicKeyCredential#parseAssertionResponseJson(java.lang.String)} to
 * parse the response, then wrap that in a {@link com.yubico.webauthn.FinishAssertionOptions} along
 * with the {@link com.yubico.webauthn.AssertionRequest} used to initiate the request. Pass that as
 * the argument to {@link
 * com.yubico.webauthn.RelyingParty#finishAssertion(com.yubico.webauthn.FinishAssertionOptions)},
 * which will return an {@link com.yubico.webauthn.AssertionResult} if successful and throw an
 * exception if not. Regardless of whether it succeeds, you should remove the {@link
 * com.yubico.webauthn.AssertionRequest} from the pending requests storage to prevent retries.
 *
 * 
Finally, use the {@link com.yubico.webauthn.AssertionResult} to update any database(s) and
 * take other actions depending on your application's needs. In particular:
 *
 * 

 *   
Use the {@link com.yubico.webauthn.AssertionResult#getUsername() username} and/or {@link
 *       com.yubico.webauthn.AssertionResult#getUserHandle() userHandle} results to initiate a user
 *       session.
 *   
Update the stored signature count for the credential (identified by the {@link
 *       com.yubico.webauthn.AssertionResult#getCredentialId() credentialId} result) to equal the
 *       value returned in the {@link com.yubico.webauthn.AssertionResult#getSignatureCount()
 *       signatureCount} result.
 * 
 */
package com.yubico.webauthn;