== Quick Start

WebAuthn is an authentication method that a user registers a public key generated by an authenticator to the server in advance
and the server verifies the signature generated by the authenticator with the public key at the time of authentication.
The data which contains public key and authenticator configuration and is sent at registration is called "attestation", and
the data which contains signature and is sent at authentication is called "assertion".

=== Attestation verification

To validate an attestation on authenticator registration, call `WebAuthnManager#validate` with a
`RegistrationRequest` instance as an argument.
If you would like to access the parsed data when an validation error occurred, please use `WebAuthnManager#parse` to
parse the registration request and pass the returned `RegistrationData` instance to `WebAuthnManager#validate`
method.

The members of `RegistrationRequest` are the values obtained by the WebAuthn JS API in the front end side.
Transmit from the front end side to the server side in some way.

`RegistrationParameters` is an another argument for `WebAuthnManager#parse` method, and contains
server property and validation conditions.

`serverProperty` has following members.

- For `origin`, please specify Origin of the site that provides WebAuthn authentication. WebAuthn specification tells that 
the authenticator signs the data including Origin recognized by the browser. WebAuthn4J verifies whether
the written Origin (namely, recognized by the browser) matches the specified Origin in `serverProperty` to prevent 
phishing attacks, which is a behavior required in WebAuthn specification.
- For `rpId`, please set the rpId of the site that provides WebAuthn authentication. rpId is a parameter that specifies
the scope of credentials. For more details, please refer to
https://www.w3.org/TR/webauthn-1/#relying-party-identifier[WebAuthn specification rpId definition].

- For `challenge`, please specify the Challenge issued on WebAuthn JS API call. `challenge` is a parameter to prevent
replay attacks. By issuing the random byte sequence `challenge` on server side, signing it with WebAuthn JS API,
and verifying the signature on server side, users are protected from the replay attack.
It is the application's responsibility for retaining the issued Challenge.
- `tokenBindingId` is a parameter for Token binding. If you do not want to use it please specify `null`.

If validation fails, an exception inheriting `ValidationException` is thrown.
If validation succeeds, please create an `Authenticator` instance from the returned value and persist it to the database
or something in your application manner. The instance is required at the time of authentication.

```java
// Client properties
byte[] attestationObject = null /* set attestationObject */;
byte[] clientDataJSON = null /* set clientDataJSON */;
String clientExtensionJSON = null;  /* set clientExtensionJSON */;
Set<String> transports = null /* set transports */;

// Server properties
Origin origin = null /* set origin */;
String rpId = null /* set rpId */;
Challenge challenge = null /* set challenge */;
byte[] tokenBindingId = null /* set tokenBindingId */;
ServerProperty serverProperty = new ServerProperty(origin, rpId, challenge, tokenBindingId);

// expectations
boolean userVerificationRequired = false;
boolean userPresenceRequired = true;
List<String> expectedExtensionIds = Collections.emptyList();

RegistrationRequest registrationRequest = new RegistrationRequest(attestationObject, clientDataJSON, clientExtensionJSON, transports);
RegistrationParameters registrationParameters = new RegistrationParameters(serverProperty, userVerificationRequired, userPresenceRequired, expectedExtensionIds);
RegistrationData registrationData;
try{
    registrationData = webAuthnManager.parse(registrationRequest);
}
catch (DataConversionException e){
    // If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
    throw e;
}
try{
    webAuthnManager.validate(registrationData, registrationParameters);
}
catch (ValidationException e){
    // If you would like to handle WebAuthn data validation error, please catch ValidationException
    throw e;
}

// please persist Authenticator object, which will be used in the authentication process.
Authenticator authenticator =
        new AuthenticatorImpl( // You may create your own Authenticator implementation to save friendly authenticator name
                registrationData.getAttestationObject().getAuthenticatorData().getAttestedCredentialData(),
                registrationData.getAttestationObject().getAttestationStatement(),
                registrationData.getAttestationObject().getAuthenticatorData().getSignCount()
        );
save(authenticator); // please persist authenticator in your manner
```

=== Assertion verification

To parse and validate an assertion on authentication, call `WebAuthnManager#parse` with a `RegistrationRequest`
instance as an argument. If you would like to access the parsed data when an validation error occurred, please use
`WebAuthnManager#parse` to parse the authentication request and pass the returned `AuthenticationData` instance
to `WebAuthnManager#validate` method.

The members of `AuthenticationRequest` are the values obtained by the WebAuthn JS API in the front end side.
Transmit from the front end side to the server side in some way.

AuthenticationParameters is an another argument for WebAuthnManager#parse method,
and contains server property, persisted authenticator and validation conditions.

```java
// Client properties
byte[] credentialId = null /* set credentialId */;
byte[] userHandle = null /* set userHandle */;
byte[] authenticatorData = null /* set authenticatorData */;
byte[] clientDataJSON = null /* set clientDataJSON */;
String clientExtensionJSON = null /* set clientExtensionJSON */;
byte[] signature = null /* set signature */;

// Server properties
Origin origin = null /* set origin */;
String rpId = null /* set rpId */;
Challenge challenge = null /* set challenge */;
byte[] tokenBindingId = null /* set tokenBindingId */;
ServerProperty serverProperty = new ServerProperty(origin, rpId, challenge, tokenBindingId);

// expectations
boolean userVerificationRequired = true;
boolean userPresenceRequired = true;
List<String> expectedExtensionIds = Collections.emptyList();

Authenticator authenticator = load(credentialId); // please load authenticator object persisted in the registration process in your manner

AuthenticationRequest authenticationRequest =
        new AuthenticationRequest(
                credentialId,
                userHandle,
                authenticatorData,
                clientDataJSON,
                clientExtensionJSON,
                signature
        );
AuthenticationParameters authenticationParameters =
        new AuthenticationParameters(
                serverProperty,
                authenticator,
                userVerificationRequired,
                userPresenceRequired,
                expectedExtensionIds
        );

AuthenticationData authenticationData;
try{
    authenticationData = webAuthnManager.parse(authenticationRequest);
}
catch (DataConversionException e){
    // If you would like to handle WebAuthn data structure parse error, please catch DataConversionException
    throw e;
}
try{
    webAuthnManager.validate(authenticationData, authenticationParameters);
}
catch (ValidationException e){
    // If you would like to handle WebAuthn data validation error, please catch ValidationException
    throw e;
}
// please update the counter of the authenticator record
updateCounter(
        authenticationData.getAuthenticatorData().getAttestedCredentialData().getCredentialId(),
        authenticationData.getAuthenticatorData().getSignCount()
);

```

