# WebAuthn Component

The WebAuthn component provides a simple way to implement a WebAuthn Relying Party server in your web application.

## Syntax

```text
TipaWebAuthn
```

## Remarks

The WebAuthn component provides a simple way to implement a WebAuthn Relying Party server, enabling passwordless authentication in your web application.

A typical Relying Party consists of two entities: the server-side logic and the front-end script. The WebAuthn component implements the server-side logic. The implementation and communication between these two key entities is up to the application. For a simple example, please refer to the demo in the installation directory.

## Setup

### Credential Storage

Before utilizing the component the application should implement some credential repository, storage, or database used to store and retrieve user credentials. The exact implementation of this storage is up to the application. For example, in the included demo, user credential information is stored in a text file on disk. Other implementations could store credentials in memory, a database, etc.

For more information on when to store and retrieve user credentials, and what information is necessary, please refer to the registration and authentication sections below.

### Configuring the Relying Party Server

A Relying Party Server has multiple properties that serve as identifiers to WebAuthn clients. These can be configured in the WebAuthn component by using the following properties:

- [Origin](#origin-property-webauthn-component)
- [RelyingPartyId](#relyingpartyid-property-webauthn-component)
- [RelyingPartyName](#relyingpartyname-property-webauthn-component)

The [Origin](#origin-property-webauthn-component) is a **required** property and specifies the full web origin, including the protocol (http or https) and domain, of the Relying Party. For example, this property may be set to *https://login.example.com:7112*. This property, along with [RelyingPartyId](#relyingpartyid-property-webauthn-component), ensures the application's security by restricting requests to valid origins and domains, preventing unauthorized entities from attempting to use credentials.

The [RelyingPartyId](#relyingpartyid-property-webauthn-component) is a valid domain string used to identify the Relying Party during registration or authentication. By default, this value is empty, and will be calculated by parsing the default effective domain of the specified [Origin](#origin-property-webauthn-component). Using the previous example, this would mean *login.example.com* would be used as the [RelyingPartyId](#relyingpartyid-property-webauthn-component).

The [RelyingPartyId](#relyingpartyid-property-webauthn-component) can be manually specified, though it should be ensured that a valid effective domain is defined for the given [Origin](#origin-property-webauthn-component). Using the previous example, *example.com* would suffice, however, *m.login.example.com* would be an invalid identifier.

The [RelyingPartyName](#relyingpartyname-property-webauthn-component) is a user-friendly identifier for the component, intended only for display. For example, this could be set to a company name, such as *ACME Corporation*.

**Related Origins**

If manually specified, the [RelyingPartyId](#relyingpartyid-property-webauthn-component) must be equal to an effective domain of the [Origin](#origin-property-webauthn-component). However, singular domains can prove difficult for deployments in larger environments, where multiple country-specific domains are in use.

As such, the [Origin](#origin-property-webauthn-component) property may be used to specify a comma-separated list of possible origins, for example, *https://example.com:7112,https://example.co.uk:7112*. Implementations can allow clients to create and use a credential across this set of origins.

In this case, implementations **must** manually specify a [RelyingPartyId](#relyingpartyid-property-webauthn-component) to use across all operations from related origins. Additionally, a JSON document **must** be hosted at the webauthn well-known URL for the [RelyingPartyId](#relyingpartyid-property-webauthn-component) (e.g., hosted at https://RelyingPartyId/.well-known/webauthn) as described [here](https://w3c.github.io/webauthn/#sctn-related-origins). This document should contain all origins specified in [Origin](#origin-property-webauthn-component).

Please see below for a simple example of configuring the mentioned properties. Note that at the very least, [Origin](#origin-property-webauthn-component) must be set for each step of the registration and authentication processes below.

```csharp
WebAuthn server = new WebAuthn();

// Automatically set RelyingPartyId to default effective domain
server.Origin = "https://login.example.com:7112";
server.RelyingPartyName = "Example Name";

Console.WriteLine(server.RelyingPartyId); // Prints "login.example.com"

// Manually set RelyingPartyId to a different effective domain
server.Origin = "https://login.example.com:7112";
server.RelyingPartyId = "example.com";
server.RelyingPartyName = "Example Name";

// Specify related origins
server.Origin = "https://login.example.com:7112,https://login.example.co.uk:7112";
server.RelyingPartyId = "example.com";
server.RelyingPArtyName = "Example Name";
```

## Registration

### Creating Registration Options

To create a new user credential, a user must first initiate the registration process. Typically, the user initiates a request to the front-end script, which should then communicate with the component to start this process.

During registration, the component is first required to build options for creating, or registering, a new user credential by calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). After receiving a request from a front-end, several relevant properties should be set before building these options.

In addition to setting the Relying Party properties, as mentioned in the previous section, the only other **required** property to set is the [UserName](#username-property-webauthn-component). The [UserName](#username-property-webauthn-component) property should be set to the user-friendly identifier for the user account attempting registration. Typically, the [UserName](#username-property-webauthn-component) is provided by the client in the front-end request. The client may also provide the [UserDisplayName](#userdisplayname-property-webauthn-component), specifying a name associated with the user account intended only for display.

The [UserId](#userid-property-webauthn-component) property may be set to some unique identifier for the relevant [UserName](#username-property-webauthn-component). By default, the [UserId](#userid-property-webauthn-component) is empty, and will be calculated by the component as the SHA256 hash of the provided [UserName](#username-property-webauthn-component). If manually specified, implementations should ensure that this identifier is unique to the user, and available in future operations related to this user.

Lastly, it may be that the specified [UserName](#username-property-webauthn-component) has existing credentials previously obtained from various authenticators. Before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component), implementations should query their existing credential database for credentials associated with the specified [UserName](#username-property-webauthn-component). Once identified, the UserCredentials collection should be populated by calling [AddUserCredential](#addusercredential-method-webauthn-component) for each credential. Doing so will ensure that a new credential is not created on an authenticator containing a credential mapped to this [UserName](#username-property-webauthn-component). While not explicitly required, this step should be performed.

The following properties may also be set or modified for additional configuration of the produced registration options:

- [AttestationType](#attestationtype-property-webauthn-component)
- [AuthenticatorAttachment](#authenticatorattachment-property-webauthn-component)
- [DiscoverableCredentials](#discoverablecredentials-property-webauthn-component)
- Extensions
- [PublicKeyAlgorithms](#publickeyalgorithms-property-webauthn-component)
- [Timeout](#timeout-property-webauthn-component)
- [UserVerification](#userverification-property-webauthn-component)

Once the component is configured, [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) should be called, producing a JSON string of the relevant options that should be returned to the client. Implementations should store the created options somewhere for use during verification (see below). For example, these options could be stored in the HTTP session context, which should persist during registration.

The client should pass these options to the JavaScript function *navigator.credentials.create()*. After doing so, the client will then interact with the authenticator. For example, the client may enter a PIN or touch a security key. Assuming this is successful, *navigator.credentials.create()* will return the authenticator response, which should then be returned to the component.

Please see below for an example of configuring the component in this case, and storing the options in the HTTP context:

```csharp
server.UserName = "test";
server.UserDisplayName = "Test User";

// Some List of WACredential type, search by UserName
List<WACredential> existingCredentials = QueryCredentialsByUser(server.UserName);

for (int i = 0; i < existingCredentials.Count; i++) {
  server.AddUserCredential(existingCredentials[i].IdB, existingCredentials[i].PublicKey, existingCredentials[i].SignCount, existingCredentials[i].SignAlgorithm)
}

// JSON options string that should be returned to the client and passed to navigator.credentials.create()
string ret = server.CreateRegistrationRequest();

// Store the options in the same context for later use during registration.
context.Session.SetString("registrationOptions", ret);
```

### Verifying the Registration Response

Assuming a response has been received from the authenticator, to complete registration, the client must provide this response to the component. To verify the authenticator response, [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) should be called, taking the options previously generated with [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) and the recently received response as parameters.

After calling [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component), the [RegistrationInfo](#registrationinfo-event-webauthn-component) event will fire, providing the Id of the recently created credential. During this event, implementations should search for the provided credential Id in their database. Credential Ids must be unique, i.e., no existing credential in the database may have the provided credential Id. If the provided credential Id exists for **any** user, verification should fail, and the *Cancel* parameter of [RegistrationInfo](#registrationinfo-event-webauthn-component) should be set to true to do so.

Assuming the credential Id does not exist for any other user and the additional verification performed by the component succeeds, [RegistrationComplete](#registrationcomplete-event-webauthn-component) will fire. This event will provide various information about the newly created credential record. During this event, implementations should save this information to their existing credential database for use during future registration or authentication ceremonies. Specifically, implementations should save the following values associated with the credential record.

1. The current [UserName](#username-property-webauthn-component) associated with the credential.
2. If manually specified, the associated [UserId](#userid-property-webauthn-component).
3. The *CredentialId* parameter of [RegistrationComplete](#registrationcomplete-event-webauthn-component).
4. The *PublicKey* parameter of [RegistrationComplete](#registrationcomplete-event-webauthn-component).
5. The *SignCount* parameter of [RegistrationComplete](#registrationcomplete-event-webauthn-component).
6. The *Algorithm* parameter of [RegistrationComplete](#registrationcomplete-event-webauthn-component).

Additionally, implementations **may** wish to store the [BackupEligible](#BackupEligible), [BackupState](#BackupState), and [UvInitialized](#UvInitialized) configs as well.

Once the relevant credential information is saved, registration is officially complete, and the registered credential may be used in future authentication ceremonies.

Please see below for an example of the verification process:

```csharp
server.OnRegistrationInfo += (o, e) => {
  // Some List of WACredential type, search by Credential Id
  existingCredentials = QueryCredentialsById(e.CredentialId);

  if (existingCredentials.Count != 0) {
    // Registration should fail since CredentialId exists
    e.Cancel = true;
  }
};

server.OnRegistrationComplete += (o, e) => {
  // Save credential info for authentication
  SaveCredential(server.UserName, e.CredentialIdB, e.PublicKey, e.SignCount, e.Algorithm);
};

string response = StreamReader(context.Request.Body).ReadToEnd();
string cachedOptions = context.Session.GetString("registrationOptions") ?? String.Empty;

server.VerifyRegistrationResponse(response, options);

Console.WriteLine("Registration Successful.");
```

## Authentication

### Creating Authentication Options

To log in using an existing credential, a user must first initiate the authentication process. Typically, the user initiates a request to the front end which should communicate directly with the component to start this process.

During authentication, the component is first required to build options for logging in using an existing user credential by calling [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component). After receiving a request from a front-end, several relevant properties should be set before building these options.

In addition to setting the Relying Party properties, as mentioned in the first section, there are no required properties that must be set before calling [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component).

Typically, the user attempting to log in will provide the username associated with their account, however, this is not a requirement. If the username is provided, implementations should query their existing credential database for any credentials associated with this username. Once identified, the UserCredentials collection should be populated by calling [AddUserCredential](#addusercredential-method-webauthn-component) for each user credential. When sending the options to the client in a later step, the authenticator will then allow the client to select from these credentials during authentication. Note that the [UserName](#username-property-webauthn-component) property should not be specified in this case, as it is not included in the options.

If the client does not specify a username, implementations should leave the UserCredentials collection empty. When sending the options to the client in a later step, the authenticator will then allow the client to utilize any discoverable credentials that were previously created. Discoverable credentials are made available to the client in this specific case, and the client may choose any of the existing discoverable credentials as presented by the authenticator. A discoverable credential can be created during registration. The component can indicate its preference regarding whether a discoverable credential is created using the [DiscoverableCredentials](#discoverablecredentials-property-webauthn-component) property during this step. If no discoverable credentials exist, this will result in an error.

The following properties may also be set or modified for additional configuration of the produced login options:

- Extensions
- [Timeout](#timeout-property-webauthn-component)

Once the component is configured, [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component) should be called, producing a JSON string of the relevant options that should be returned to the client. Implementations should store the created options somewhere for use during verification (see below). For example, these options could be stored in the HTTP session context, which should persist during authentication.

The client should pass these options to the JavaScript function *navigator.credentials.get()*. After doing so, the client will then interact with the authenticator. For example, the client may enter a PIN or touch a security key. Assuming this is successful, *navigator.credentials.get()* will return the authenticator response, which should then be returned to the component.

Please see below for an example of configuring the component in this case, and storing the options in the HTTP context:

```csharp
string userName = "test"; // If provided, optional
List<existingCredentials> = QueryCredentialsByUser(userName);

for (int i = 0; i < existingCredentials.Count; i++) {
  server.AddUserCredential(existingCredentials[i].IdB, existingCredentials[i].PublicKey, existingCredentials[i].SignCount, existingCredentials[i].SignAlgorithm)
}

// JSON options string that should be returned to the client and passed to navigator.credentials.create()
string ret = server.CreateAuthenticationRequest();

// Store the options in the same context for later use during login.
context.Session.SetString("loginOptions", ret);
```

### Verifying the Authentication Response

Assuming a response has been received from the authenticator, to complete the login process, the client must provide this response to the component. To verify the authenticator response, [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component) should be called, taking the recently received response, and the options previously generated with [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component) (stored in the HTTP context).

After calling [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component), the [AuthenticationInfo](#authenticationinfo-event-webauthn-component) event will fire, providing the Id of the recently created credential. During this event, implementations should search for the provided credential Id in their database. Since a user is attempting to use an existing credential, it is assumed this credential exists in the database. If the provided credential Id does not exist, the *Cancel* parameter of [AuthenticationInfo](#authenticationinfo-event-webauthn-component) should be set to true, and verification should fail.

Assuming the credential exists in the database, the following properties and event parameters should be set during [AuthenticationInfo](#authenticationinfo-event-webauthn-component):

- The current [UserName](#username-property-webauthn-component) associated with the credential.
- If manually specified, the associated [UserId](#userid-property-webauthn-component).
- The *PublicKey* parameter of [AuthenticationInfo](#authenticationinfo-event-webauthn-component).
- The *SignCount* parameter of [AuthenticationInfo](#authenticationinfo-event-webauthn-component).
- The *Algorithm* parameter of [AuthenticationInfo](#authenticationinfo-event-webauthn-component).

Assuming this information is correct, the component will continue the verification process accordingly, and [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) will fire. This event will provide necessary information regarding any updates to the existing credential. During this event, implementations should update the credential in their database for future use. Specifically, implementations should update the signature counter associated with the credential record by utilizing the *SignCount* parameter of [AuthenticationComplete](#authenticationcomplete-event-webauthn-component).

Implementations **may** wish to query the values of the [BackupState](#BackupState) and [UvInitialized](#UvInitialized) configs to update the stored credential record accordingly.

Once the relevant credential information is updated, authentication is complete.

Please see below for an example of the verification process:

```csharp
server.OnAuthenticationInfo += (o, e) => {
  // Search for single Credential Id
  existingCredential = QueryCredentialById(e.CredentialId);
  string user = QueryUserById(e.CredentialId);

  if (existingCredential == null) {
    // Authentication should fail since CredentialId does not exist
    e.Cancel = true;
  }

  server.UserName = user;
  e.PublicKey = existingCredential.PublicKey;
  e.SignCount = existingCredential.SignCount;
  e.Algorithm = existingCredential.SignAlgorithm;
};

server.OnAuthenticationComplete += (o, e) => {
  // Update credential info
  SaveCredential(e.CredentialIdB, e.SignCount);
};

string response = new StreamReader(context.Request.Body).ReadToEnd();
string cachedOptions = context.Session.GetString("loginOptions") ?? String.Empty;

server.VerifyAuthenticationResponse(response, options);

Console.WriteLine("Authentication Successful.");
```

## Property List

*The following is the full list of the properties of the component with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [AttestationType](#attestationtype-property-webauthn-component) | Specifies the preference regarding attestation conveyance during registration. |
| [AuthenticatorAttachment](#authenticatorattachment-property-webauthn-component) | Specifies the preference regarding authenticator attachment modality during registration. |
| [DiscoverableCredentials](#discoverablecredentials-property-webauthn-component) | Specifies whether the Relying Party wishes to create a client-side discoverable credential during registration. |
| [WAExtensionCount](#waextensioncount-property-webauthn-component) | The number of records in the WAExtension arrays. |
| [WAExtensionName](#waextensionname-property-webauthn-component) | Specifies the name of the extension. |
| [WAExtensionValue](#waextensionvalue-property-webauthn-component) | Specifies the value of the extension. |
| [WAExtensionValueType](#waextensionvaluetype-property-webauthn-component) | Specifies the type of the Value of the current extension. |
| [Origin](#origin-property-webauthn-component) | Specifies the full web origin, including the protocol (http or https) and domain, of the component (WebAuthn Relying Party). |
| [PublicKeyAlgorithms](#publickeyalgorithms-property-webauthn-component) | Specifies an ordered, comma-separated list of acceptable algorithms for the public key during registration. |
| [RelyingPartyId](#relyingpartyid-property-webauthn-component) | Specifies the unique identifier of the Relying Party. |
| [RelyingPartyName](#relyingpartyname-property-webauthn-component) | Specifies a user-friendly name for the WebAuthn Relying Party. |
| [Timeout](#timeout-property-webauthn-component) | Specifies a time, in seconds, that the Relying Party is willing to wait for the operation to complete. |
| [WACredentialCount](#wacredentialcount-property-webauthn-component) | The number of records in the WACredential arrays. |
| [WACredentialId](#wacredentialid-property-webauthn-component) | Specifies the credential Id of the credential. |
| [WACredentialPublicKey](#wacredentialpublickey-property-webauthn-component) | Specifies the public key of the credential. |
| [WACredentialSignAlgorithm](#wacredentialsignalgorithm-property-webauthn-component) | Specifies the signing algorithm of the credential. |
| [WACredentialSignCount](#wacredentialsigncount-property-webauthn-component) | Specifies the signature count of the credential. |
| [UserDisplayName](#userdisplayname-property-webauthn-component) | Specifies a user-friendly name for the associated user account intended only for display. |
| [UserId](#userid-property-webauthn-component) | Specifies the user Id, or user handle, for the associated user account. |
| [UserName](#username-property-webauthn-component) | Specifies a user-friendly name for the associated user account. |
| [UserVerification](#userverification-property-webauthn-component) | Specifies the Relying Party's requirements regarding user verification during registration. |

## Method List

*The following is the full list of the methods of the component with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [AddExtension](#addextension-method-webauthn-component) | Used to add an extension to include when building the options for registration or authentication. |
| [AddUserCredential](#addusercredential-method-webauthn-component) | Used to add a user credential to the UserCredentials collection. |
| [Config](#config-method-webauthn-component) | Sets or retrieves a configuration setting. |
| [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component) | Used to build the request options for a user attempting to login, or authenticate, using an existing credential. |
| [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) | Used to build the request options for a user attempting to register a new credential. |
| [Reset](#reset-method-webauthn-component) | Resets the component properties. |
| [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component) | Used to log in, or authenticate, using an existing credential. |
| [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) | Used to register a new credential. |

## Event List

*The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) | Fired when a user successfully logs in. |
| [AuthenticationInfo](#authenticationinfo-event-webauthn-component) | Fired when the component requests additional information regarding the existing credential. |
| [Error](#error-event-webauthn-component) | Fired when information is available about errors during data delivery. |
| [Extension](#extension-event-webauthn-component) | Fired when an extension is found while verifying an authenticator response. |
| [Log](#log-event-webauthn-component) | Fired once for each log message. |
| [RegistrationComplete](#registrationcomplete-event-webauthn-component) | Fired when a user is successfully registered. |
| [RegistrationInfo](#registrationinfo-event-webauthn-component) | Fired when the component requests additional information regarding the new credential. |

## Config Settings

*The following is a list of config settings for the component with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [BackupEligible](#BackupEligible) | Indicates or specifies the backup eligibility of a credential. |
| [BackupState](#BackupState) | Indicates the backup state of a credential. |
| [Hints](#Hints) | Specifies any hints to communicate to the user-agent about how a request may be completed. |
| [ServerChallenge](#ServerChallenge) | Specifies the cryptographic challenge associated with the current options, as specified by the component. |
| [UvInitialized](#UvInitialized) | Indicates whether user verification has been performed for a new or existing credential. |
| [BuildInfo](#BuildInfo) | Information about the product's build. |
| [CodePage](#CodePage) | The system code page used for Unicode to Multibyte translations. |
| [LicenseInfo](#LicenseInfo) | Information about the current license. |
| [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. |
| [UseFIPSCompliantAPI](#UseFIPSCompliantAPI) | Tells the component whether or not to use FIPS certified APIs. |
| [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. |

# AttestationType Property ([WebAuthn](#webauthn-component) Component)

Specifies the preference regarding attestation conveyance during registration.

## Syntax

*C++ Builder Syntax*

```text
__property TipaWebAuthnAttestationTypes AttestationType = { read=FAttestationType, write=FSetAttestationType };
enum TipaWebAuthnAttestationTypes {
  atNone=0,
  atIndirect=1,
  atDirect=2,
  atEnterprise=3
};
```

## Default Value

atNone

## Remarks

This property specifies the preference regarding attestation conveyance during registration. This value may be set prior to calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). Possible values include:

|  |  |
| --- | --- |
| 0 (atNone - default) | Indicates the Relying Party is not interested in an attestation. |
| 1 (atIndirect) | Indicates the Relying Party wants to receive a verifiable attestation, but allows the client to decide how to obtain such an attestation statement. |
| 2 (atDirect) | Indicates the Relying Party wants to receive the attestation statement as generated by the authenticator. |
| 3 (atEnterprise) | Indicates the Relying Party wants to receive an attestation statement that may include uniquely identifying information. |

## Data Type

Integer

# AuthenticatorAttachment Property ([WebAuthn](#webauthn-component) Component)

Specifies the preference regarding authenticator attachment modality during registration.

## Syntax

*C++ Builder Syntax*

```text
__property TipaWebAuthnAuthenticatorAttachments AuthenticatorAttachment = { read=FAuthenticatorAttachment, write=FSetAuthenticatorAttachment };
enum TipaWebAuthnAuthenticatorAttachments {
  atAny=0,
  atPlatform=1,
  atCrossPlatform=2
};
```

## Default Value

atAny

## Remarks

This property specifies the preference regarding authenticator attachment modality. This value may be set prior to calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). Possible values include:

|  |  |
| --- | --- |
| 0 (atAny - default) | Indicates the Relying Party does not have a preference between platform and cross-platform authenticators. |
| 1 (atPlatform) | Indicates the Relying Party prefers the use of a platform authenticator, i.e., a non-removable authenticator. |
| 2 (atCrossPlatform) | Indicates the Relying Party prefers the use of a cross-platform attachment, i.e., a roaming authenticator. |

Note that this value may not affect which types of authenticators (platform or cross-platform) are presented to the client, as it only indicates server-side preference.

This property is not available at design time.

## Data Type

Integer

# DiscoverableCredentials Property ([WebAuthn](#webauthn-component) Component)

Specifies whether the Relying Party wishes to create a client-side discoverable credential during registration.

## Syntax

*C++ Builder Syntax*

```text
__property TipaWebAuthnDiscoverableCredentials DiscoverableCredentials = { read=FDiscoverableCredentials, write=FSetDiscoverableCredentials };
enum TipaWebAuthnDiscoverableCredentials {
  dcUnspecified=0,
  dcDiscouraged=1,
  dcPreferred=2,
  dcRequired=3
};
```

## Default Value

dcUnspecified

## Remarks

This property specifies whether the Relying Party wishes to create a client-side discoverable credential during registration. This value may be set prior to calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). Possible values include:

|  |  |
| --- | --- |
| 0 (dcUnspecified - default) | The option will not be specified in the returned value of [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). |
| 1 (dcDiscouraged) | The Relying Party prefers creating a server-side credential, but will accept a client-side discoverable credential. |
| 2 (dcPreferred) | The Relying Party strongly prefers creating a client-side discoverable credential, but will accept a server-side credential. |
| 3 (dcRequired) | The Relying Party requires a client-side discoverable credential. |

As some background, a discoverable credential is a credential that is discoverable and usable during authentication ceremonies where the UserCredentials is empty, i.e., when no existing credential Ids are specified. In this case, the Relying Party does not necessarily need to first identify the user. On the client-side, the user will be able to select some appropriate credential to log in with.

Assuming the authentication on the client-side is successful, the authenticator should return a response to the application, which will contain the relevant credential Id used to log in. The associated credential Id will be provided in [AuthenticationInfo](#authenticationinfo-event-webauthn-component), and assuming the credential exists, relevant credential information should be provided.

This property is not available at design time.

## Data Type

Integer

# WAExtensionCount Property ([WebAuthn](#webauthn-component) Component)

The number of records in the WAExtension arrays.

## Syntax

*C++ Builder Syntax*

```text
__property int WAExtensionCount = { read=FWAExtensionCount };
```

## Default Value

0

## Remarks

This property controls the size of the following arrays:

- [WAExtensionName](#waextensionname-property-webauthn-component)
- [WAExtensionValue](#waextensionvalue-property-webauthn-component)
- [WAExtensionValueType](#waextensionvaluetype-property-webauthn-component)

The array indices start at *0* and end at *WAExtensionCount - 1*.

This property is read-only and not available at design time.

## Data Type

Integer

# WAExtensionName Property ([WebAuthn](#webauthn-component) Component)

Specifies the name of the extension.

## Syntax

*C++ Builder Syntax*

```text
__property String WAExtensionName[int WAExtensionIndex] = { read=FWAExtensionName };
```

## Default Value

""

## Remarks

Specifies the name of the extension.

The *WAExtensionIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WAExtensionCount](#waextensioncount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

String

# WAExtensionValue Property ([WebAuthn](#webauthn-component) Component)

Specifies the value of the extension.

## Syntax

*C++ Builder Syntax*

```text
__property String WAExtensionValue[int WAExtensionIndex] = { read=FWAExtensionValue };
```

## Default Value

""

## Remarks

Specifies the value of the extension. See [WAExtensionValueType](#waextensionvaluetype-property-webauthn-component) for information regarding this properties type.

The *WAExtensionIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WAExtensionCount](#waextensioncount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

String

# WAExtensionValueType Property ([WebAuthn](#webauthn-component) Component)

Specifies the type of the Value of the current extension.

## Syntax

*C++ Builder Syntax*

```text
__property int WAExtensionValueType[int WAExtensionIndex] = { read=FWAExtensionValueType };
```

## Default Value

0

## Remarks

Specifies the type of the [WAExtensionValue](#waextensionvalue-property-webauthn-component) of the current extension. Possible values are:

- 0 (Object)
- 1 (Array)
- 2 (String)
- 3 (Number)
- 4 (Bool)
- 5 (Null)
- 6 (Raw)

The *WAExtensionIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WAExtensionCount](#waextensioncount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

Integer

# Origin Property ([WebAuthn](#webauthn-component) Component)

Specifies the full web origin, including the protocol (http or https) and domain, of the component (WebAuthn Relying Party).

## Syntax

*C++ Builder Syntax*

```text
__property String Origin = { read=FOrigin, write=FSetOrigin };
```

## Default Value

""

## Remarks

This property specifies the full web origin, including the protocol (http or https) and domain, of the component (WebAuthn Relying Party). The origin must be specified before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component), [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component), [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), and [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component).

This property ensures the security of the application by restricting requests to valid origins, preventing unauthorized entities from attempting to use credentials. For example, setting the Origin property to *https://login.example.com:7112* limits requests to that specific domain.

By default, after setting this property, the [RelyingPartyId](#relyingpartyid-property-webauthn-component) will be set to the default effective domain of the origin. In the above example, [RelyingPartyId](#relyingpartyid-property-webauthn-component) would be set to *login.example.com*.

The [RelyingPartyId](#relyingpartyid-property-webauthn-component) can be manually specified, though it should be ensured that a valid effective domain is specified for the given Origin. Using the previous example, *example.com* would suffice, however, *m.login.example.com* would be an invalid identifier.

**Related Origins**

If manually specified, the [RelyingPartyId](#relyingpartyid-property-webauthn-component) must be equal to an effective domain of the Origin. However, singular domains can prove difficult for deployments in larger environments, where multiple country-specific domains are in use.

As such, the Origin property may be used to specify a comma-separated list of possible origins, for example, *https://example.com:7112,https://example.co.uk:7112*. Implementations can allow clients to create and use a credential across this set of origins.

In this case, implementations **must** manually specify a [RelyingPartyId](#relyingpartyid-property-webauthn-component) to use across all operations from related origins. Additionally, a JSON document **must** be hosted at the webauthn well-known URL for the [RelyingPartyId](#relyingpartyid-property-webauthn-component) (e.g., hosted at https://RelyingPartyId/.well-known/webauthn) as described [here](https://w3c.github.io/webauthn/#sctn-related-origins). This document should contain all origins specified in Origin.

## Data Type

String

# PublicKeyAlgorithms Property ([WebAuthn](#webauthn-component) Component)

Specifies an ordered, comma-separated list of acceptable algorithms for the public key during registration.

## Syntax

*C++ Builder Syntax*

```text
__property String PublicKeyAlgorithms = { read=FPublicKeyAlgorithms, write=FSetPublicKeyAlgorithms };
```

## Default Value

"ES256,RS256"

## Remarks

This property specifies an ordered, comma-separated list of acceptable algorithms for the public key during registration. By default, this value is *ES256,RS256*, and must be specified before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component).

Though those elements are sorted by preference (the first element being the most preferred), it is up to the client to choose among those elements for building the credential.

Possible values to include in this property are:

- ES256 (default)
- RS256 (default)
- ES384
- ES512
- EdDSA
- PS256
- PS384
- PS512
- RS1

The selected algorithm will be made available in [RegistrationComplete](#registrationcomplete-event-webauthn-component), after verifying the authenticator response using [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component).

## Data Type

String

# RelyingPartyId Property ([WebAuthn](#webauthn-component) Component)

Specifies the unique identifier of the Relying Party.

## Syntax

*C++ Builder Syntax*

```text
__property String RelyingPartyId = { read=FRelyingPartyId, write=FSetRelyingPartyId };
```

## Default Value

""

## Remarks

This property specifies the unique identifier of the WebAuthn Relying Party.

A Relying Party identifier is a valid domain string identifying the WebAuthn Relying Party on whose behalf registration or authentication is being performed.

By default, this value is empty, and will be set as the default effective domain of the [Origin](#origin-property-webauthn-component). For example, if the [Origin](#origin-property-webauthn-component) is specified as *https://example.com*, this property will be set to *example.com*.

The RelyingPartyId can be manually specified after setting [Origin](#origin-property-webauthn-component), though it should be ensured that a valid effective domain is specified for the given origin. Using the previous example, *example.com* would suffice, however, *m.login.example.com* would be an invalid identifier.

NOTE: If the [Origin](#origin-property-webauthn-component) is specified as a comma-separated list of valid origins, this property **must** be manually specified, otherwise, it will remain empty.

## Data Type

String

# RelyingPartyName Property ([WebAuthn](#webauthn-component) Component)

Specifies a user-friendly name for the WebAuthn Relying Party.

## Syntax

*C++ Builder Syntax*

```text
__property String RelyingPartyName = { read=FRelyingPartyName, write=FSetRelyingPartyName };
```

## Default Value

""

## Remarks

This property specifies a user-friendly identifier for the Relying Party, intended only for display. For example, "ACME Corporation", "Wonderful Widgets, Inc.".

This property may be specified before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component), [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component), [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), and [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component).

## Data Type

String

# Timeout Property ([WebAuthn](#webauthn-component) Component)

Specifies a time, in seconds, that the Relying Party is willing to wait for the operation to complete.

## Syntax

*C++ Builder Syntax*

```text
__property int Timeout = { read=FTimeout, write=FSetTimeout };
```

## Default Value

60

## Remarks

This property specifies a time, in seconds, that the Relying Party is willing to wait for the operation to complete. By default, this is set to *60* seconds.

When calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) or [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), this value simply represents a hint for the time the component is willing to wait for the completion of the operation. This property is optional and merely is a hint which may be overridden by the browser.

## Data Type

Integer

# WACredentialCount Property ([WebAuthn](#webauthn-component) Component)

The number of records in the WACredential arrays.

## Syntax

*C++ Builder Syntax*

```text
__property int WACredentialCount = { read=FWACredentialCount };
```

## Default Value

0

## Remarks

This property controls the size of the following arrays:

- [WACredentialId](#wacredentialid-property-webauthn-component)
- [WACredentialPublicKey](#wacredentialpublickey-property-webauthn-component)
- [WACredentialSignAlgorithm](#wacredentialsignalgorithm-property-webauthn-component)
- [WACredentialSignCount](#wacredentialsigncount-property-webauthn-component)

The array indices start at *0* and end at *WACredentialCount - 1*.

This property is read-only and not available at design time.

## Data Type

Integer

# WACredentialId Property ([WebAuthn](#webauthn-component) Component)

Specifies the credential Id of the credential.

## Syntax

*C++ Builder Syntax*

```text
__property String WACredentialId[int WACredentialIndex] = { read=FWACredentialId };
__property DynamicArray<Byte> WACredentialIdB[int WACredentialIndex] = { read=FWACredentialIdB };
```

## Default Value

""

## Remarks

Specifies the credential Id of the credential.

The *WACredentialIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WACredentialCount](#wacredentialcount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

Byte Array

# WACredentialPublicKey Property ([WebAuthn](#webauthn-component) Component)

Specifies the public key of the credential.

## Syntax

*C++ Builder Syntax*

```text
__property String WACredentialPublicKey[int WACredentialIndex] = { read=FWACredentialPublicKey };
```

## Default Value

""

## Remarks

Specifies the public key of the credential.

The *WACredentialIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WACredentialCount](#wacredentialcount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

String

# WACredentialSignAlgorithm Property ([WebAuthn](#webauthn-component) Component)

Specifies the signing algorithm of the credential.

## Syntax

*C++ Builder Syntax*

```text
__property String WACredentialSignAlgorithm[int WACredentialIndex] = { read=FWACredentialSignAlgorithm };
```

## Default Value

"0"

## Remarks

Specifies the signing algorithm of the credential.

The *WACredentialIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WACredentialCount](#wacredentialcount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

String

# WACredentialSignCount Property ([WebAuthn](#webauthn-component) Component)

Specifies the signature count of the credential.

## Syntax

*C++ Builder Syntax*

```text
__property int WACredentialSignCount[int WACredentialIndex] = { read=FWACredentialSignCount };
```

## Default Value

0

## Remarks

Specifies the signature count of the credential.

The *WACredentialIndex* parameter specifies the index of the item in the array. The size of the array is controlled by the [WACredentialCount](#wacredentialcount-property-webauthn-component) property.

This property is read-only and not available at design time.

## Data Type

Integer

# UserDisplayName Property ([WebAuthn](#webauthn-component) Component)

Specifies a user-friendly name for the associated user account intended only for display.

## Syntax

*C++ Builder Syntax*

```text
__property String UserDisplayName = { read=FUserDisplayName, write=FSetUserDisplayName };
```

## Default Value

""

## Remarks

This property specifies a user-friendly name for the associated user account intended only for display.

## Data Type

String

# UserId Property ([WebAuthn](#webauthn-component) Component)

Specifies the user Id, or user handle, for the associated user account.

## Syntax

*C++ Builder Syntax*

```text
__property String UserId = { read=FUserId, write=FSetUserId };
__property DynamicArray<Byte> UserIdB = { read=FUserIdB, write=FSetUserIdB };
```

## Default Value

""

## Remarks

This property specifies the user Id, or user handle, for the associated user account. By default, this value will be empty. If left unspecified, the Id will be calculated as the SHA256 hash of the [UserName](#username-property-webauthn-component) property for use during registration and authentication.

If manually specified, this property will be used instead. In this case, it should be ensured that the specified Id is an opaque byte sequence with a maximum size of 64 bytes.

Note that this property is not meant to be displayed to the user.

## Data Type

Byte Array

# UserName Property ([WebAuthn](#webauthn-component) Component)

Specifies a user-friendly name for the associated user account.

## Syntax

*C++ Builder Syntax*

```text
__property String UserName = { read=FUserName, write=FSetUserName };
```

## Default Value

""

## Remarks

This property specifies a user-friendly name or identifier for the associated user account. This property must be set prior to calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component).

For example, possible values include: "alexm", "+14255551234", "alex.mueller@example.com", "alex.mueller@example.com (prod-env)".

By default, the [UserId](#userid-property-webauthn-component) will be calculated as the SHA256 hash of this property for use during registration and authentication.

## Data Type

String

# UserVerification Property ([WebAuthn](#webauthn-component) Component)

Specifies the Relying Party's requirements regarding user verification during registration.

## Syntax

*C++ Builder Syntax*

```text
__property TipaWebAuthnUserVerifications UserVerification = { read=FUserVerification, write=FSetUserVerification };
enum TipaWebAuthnUserVerifications {
  uvRequired=0,
  uvPreferred=1,
  uvDiscouraged=2
};
```

## Default Value

uvPreferred

## Remarks

This property specifies whether the Relying Party's requirements regarding user verification during registration. Possible values include:

|  |  |
| --- | --- |
| 0 (uvRequired) | The Relying Party requires user verification during registration or authentication, in that an error should be returned if user verification cannot be performed, or fails. |
| 1 (uvPreferred - default) | The Relying Party prefers user verification during registration or authentication if possible, but will not fail the operation if user verification is not performed. |
| 2 (uvDiscouraged) | The Relying Party discourages user verification during registration or authentication, but will not fail the operation if user verification is performed. |

As some background, an authenticator must support at least one authentication factor. An authenticator that supports one or more additional authentication factors (i.e., 2 or 3 total authentication factors) can support user verification, and is known as a multi-factor capable authenticator. In that regard, an authenticator that is not multi-factor capable is defined as single-factor capable, and do not support user verification. If this property is set to *0* (uvRequired) and the client attempts to utilize a single-factor capable authenticator, registration will fail.

Whether user verification was successful, or even performed, is indicated by the [UvInitialized](#UvInitialized) config, which may be queried during [RegistrationComplete](#registrationcomplete-event-webauthn-component) or [AuthenticationComplete](#authenticationcomplete-event-webauthn-component). This config may be stored or updated during these events for future use.

## Data Type

Integer

# AddExtension Method ([WebAuthn](#webauthn-component) Component)

Used to add an extension to include when building the options for registration or authentication.

## Syntax

*C++ Builder Syntax*

```text
void __fastcall AddExtension(String Name, String Value, int ValueType);
```

## Remarks

This method is used to add an extension to include when building the options for registration or authentication (i.e., when calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) and [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), respectively).

The *Name* parameter specifies the name of the extension.

The *Value* parameter specifies the value of the extension.

The *ValueType* parameter specifies the type of the value. Possible values are as follows:

- 0 (Object)
- 1 (Array)
- 2 (String)
- 3 (Number)
- 4 (Bool)
- 5 (Null)
- 6 (Raw)

For example, to include the registered FIDO AppId Extension (appid) when calling [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), you can do the following:

```text
webauthn.AddExtension("appid", "some_legacy_rp_id", 2);
```

Assuming the extensions are supported by the authenticator and client, the extension outputs are reported when verifying the response after calling either [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) or [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component). For each extension, the [Extension](#extension-event-webauthn-component) event will fire with the relevant response parameters and types.

In the above case, the extension output will report either true or false, depending on whether the provided appid was utilized. If true, the [RelyingPartyId](#relyingpartyid-property-webauthn-component) should be updated accordingly to ensure that verification succeeds. For example:

```text
webauthn.OnExtension += (o, e) => {
  // Ensure returned value is a boolean, and true, before updating
  if (e.Name.Equals("appid") && e.ValueType == 4 && bool.Parse(e.Value)) {
    webauthn.RelyingPartyId = "some_legacy_rp_id";
  }
};
```

# AddUserCredential Method ([WebAuthn](#webauthn-component) Component)

Used to add a user credential to the UserCredentials collection.

## Syntax

*C++ Builder Syntax*

```text
void __fastcall AddUserCredential(DynamicArray<Byte> credentialId, String publicKey, int signCount, String algorithm);
```

## Remarks

This method is used to add a user credential to the UserCredentials collection, which can be used to hold existing credentials for a specified [UserName](#username-property-webauthn-component) prior to calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) and [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component).

Before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component), this method should be called for each credential that exists for the given [UserName](#username-property-webauthn-component). Included credentials will be specified in the resulting options. This will ensure that the new credential is not created on an authenticator that already contains a credential mapped to the specific [UserName](#username-property-webauthn-component). If a mapped credential for the selected authenticator already exists, this may result in an error.

Before calling [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), if a username is provided by the front-end, AddUserCredential should be called for each existing credential for the identified user account. The [UserName](#username-property-webauthn-component) property should not be specified in this case, as it is not included in the options.

If a username is not provided by the front-end, AddUserCredential should not called, and only discoverable credentials will be utilized for authentication. In this case, the user will select the relevant credential during authentication, unknown to the component initially. After receiving a response from the authenticator and calling [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component), the utilized credential will be present in [AuthenticationInfo](#authenticationinfo-event-webauthn-component).

# Config Method ([WebAuthn](#webauthn-component) Component)

Sets or retrieves a configuration setting.

## Syntax

*C++ Builder Syntax*

```text
String __fastcall Config(String ConfigurationString);
```

## Remarks

Config is a generic method available in every component. It is used to set and retrieve [configuration settings](#config-settings-webauthn-component) for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these *internal properties* is provided through the Config method.

To set a configuration setting named *PROPERTY*, you must call *Config("PROPERTY=VALUE")*, where *VALUE* is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a [configuration setting](#config-settings-webauthn-component), you must call *Config("PROPERTY")*. The value will be returned as a string.

# CreateAuthenticationRequest Method ([WebAuthn](#webauthn-component) Component)

Used to build the request options for a user attempting to login, or authenticate, using an existing credential.

## Syntax

*C++ Builder Syntax*

```text
String __fastcall CreateAuthenticationRequest();
```

## Remarks

This method is used to build the request options for a user attempting to login, or authenticate, an existing credential, and will return a JSON-formatted string of these options. These options should be returned to the front-end and then passed to *navigator.credentials.get()* after some additional modification.

Before calling this method, [Origin](#origin-property-webauthn-component), [RelyingPartyId](#relyingpartyid-property-webauthn-component), and/or [RelyingPartyName](#relyingpartyname-property-webauthn-component) must be set accordingly.

Additionally, if the user account has been identified (i.e., the user has specified their username), [AddUserCredential](#addusercredential-method-webauthn-component) should be called to populate UserCredentials with existing credentials for the identified user. If the user account has not been specified, UserCredentials may remain empty, implying that only discoverable credentials will be utilized for login.

The following properties may also be set or modified for additional configuration of the produced login options:

- Extensions
- [Timeout](#timeout-property-webauthn-component)

Please see below for a simple example of this process:

```csharp
string userName = "test"; // If provided, optional
List<existingCredentials> = QueryCredentialsByUser(userName);

for (int i = 0; i < existingCredentials.Count; i++) {
  server.AddUserCredential(existingCredentials[i].IdB, existingCredentials[i].PublicKey, existingCredentials[i].SignCount, existingCredentials[i].SignAlgorithm)
}

// JSON options string that should be returned to the client and passed to navigator.credentials.create()
string ret = server.CreateAuthenticationRequest();

// Store the options in the same context for later use during login.
context.Session.SetString("loginOptions", ret);
```

# CreateRegistrationRequest Method ([WebAuthn](#webauthn-component) Component)

Used to build the request options for a user attempting to register a new credential.

## Syntax

*C++ Builder Syntax*

```text
String __fastcall CreateRegistrationRequest();
```

## Remarks

This method is used to build the request options for a user attempting to register, and will return a JSON-formatted string of these options. These options should be returned to the front-end and then passed to *navigator.credentials.create()* after some additional modification.

Before calling this method, [Origin](#origin-property-webauthn-component), [RelyingPartyId](#relyingpartyid-property-webauthn-component), and/or [RelyingPartyName](#relyingpartyname-property-webauthn-component) must be set accordingly.

To identify the user performing registration, the [UserName](#username-property-webauthn-component), [UserDisplayName](#userdisplayname-property-webauthn-component), and [UserId](#userid-property-webauthn-component) should be specified. Additionally, [AddUserCredential](#addusercredential-method-webauthn-component) should be called to populate UserCredentials with existing credentials for the relevant user.

The following properties may also be set or modified for additional configuration of the produced registration options:

- [AttestationType](#attestationtype-property-webauthn-component)
- [AuthenticatorAttachment](#authenticatorattachment-property-webauthn-component)
- [DiscoverableCredentials](#discoverablecredentials-property-webauthn-component)
- Extensions
- [PublicKeyAlgorithms](#publickeyalgorithms-property-webauthn-component)
- [Timeout](#timeout-property-webauthn-component)
- [UserVerification](#userverification-property-webauthn-component)

Please see below for a simple example of this process:

```csharp
server.UserName = "test";
server.UserDisplayName = "Test User";

// Some List of WACredential type, search by UserName
List<WACredential> existingCredentials = QueryCredentialsByUser(server.UserName);

for (int i = 0; i < existingCredentials.Count; i++) {
  server.AddUserCredential(existingCredentials[i].IdB, existingCredentials[i].PublicKey, existingCredentials[i].SignCount, existingCredentials[i].SignAlgorithm)
}

// JSON options string that should be returned to the client and passed to navigator.credentials.create()
string ret = server.CreateRegistrationRequest();

// Store the options in the same context for later use during registration.
context.Session.SetString("registrationOptions", ret);
```

# Reset Method ([WebAuthn](#webauthn-component) Component)

Resets the component properties.

## Syntax

*C++ Builder Syntax*

```text
void __fastcall Reset();
```

## Remarks

This method resets all message and key properties to their default values.

# VerifyAuthenticationResponse Method ([WebAuthn](#webauthn-component) Component)

Used to log in, or authenticate, using an existing credential.

## Syntax

*C++ Builder Syntax*

```text
void __fastcall VerifyAuthenticationResponse(String response, String options);
```

## Remarks

This method is used to log in, or authenticate, using an existing credential.

Before calling this method, [Origin](#origin-property-webauthn-component), [RelyingPartyId](#relyingpartyid-property-webauthn-component), and/or [RelyingPartyName](#relyingpartyname-property-webauthn-component) must be set accordingly.

The *Response* parameter is used to provide the JSON-formatted authenticator response returned from the front-end call to *navigator.credentials.get()*.

The *Options* parameter is used to provide the options obtained from [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component) during the first step of authentication.

After parsing the *Response* and *Options* parameters, the component will first attempt to verify the *Response*. During verification, [AuthenticationInfo](#authenticationinfo-event-webauthn-component) will fire, requesting additional information regarding the current credential. Within this event, it should be confirmed that the relevant credential used to log in exists. Relevant information about this credential should also be provided to the component. Please see [AuthenticationInfo](#authenticationinfo-event-webauthn-component) for additional information.

Assuming the response is successfully verified, [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) will fire containing updated information about the existing credential, which must be stored for future use. Afterwards, this method will return successfully, indicating the authentication process is complete.

Please see below for a simple example of this process:

```csharp
server.OnAuthenticationInfo += (o, e) => {
  // Search for single Credential Id
  existingCredential = QueryCredentialById(e.CredentialId);
  string user = QueryUserById(e.CredentialId);

  if (existingCredential == null) {
    // Authentication should fail since CredentialId does not exist
    e.Cancel = true;
  }

  server.UserName = user;
  e.PublicKey = existingCredential.PublicKey;
  e.SignCount = existingCredential.SignCount;
  e.Algorithm = existingCredential.SignAlgorithm;
};

server.OnAuthenticationComplete += (o, e) => {
  // Update credential info
  SaveCredential(e.CredentialIdB, e.SignCount);
};

string response = new StreamReader(context.Request.Body).ReadToEnd();
string cachedOptions = context.Session.GetString("loginOptions") ?? String.Empty;

server.VerifyAuthenticationResponse(response, options);

Console.WriteLine("Authentication Successful.");
```

# VerifyRegistrationResponse Method ([WebAuthn](#webauthn-component) Component)

Used to register a new credential.

## Syntax

*C++ Builder Syntax*

```text
void __fastcall VerifyRegistrationResponse(String response, String options);
```

## Remarks

This method is used to register a new credential.

Before calling this method, [Origin](#origin-property-webauthn-component), [RelyingPartyId](#relyingpartyid-property-webauthn-component), and/or [RelyingPartyName](#relyingpartyname-property-webauthn-component) must be set accordingly.

The *Response* parameter is used to provide the JSON-formatted authenticator response returned from the front-end call to *navigator.credentials.create()*.

The *Options* parameter is used to provide the options obtained from [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) during the first step of registration.

After parsing the *Response* and *Options* parameters, the component will first attempt to verify the *Response*. During verification, [RegistrationInfo](#registrationinfo-event-webauthn-component) will fire, requesting confirmation regarding the new credential. Within this event, it should be confirmed that the new credential does not already exist for any user. Please see [RegistrationInfo](#registrationinfo-event-webauthn-component) for additional information.

Assuming the response is successfully verified, [RegistrationComplete](#registrationcomplete-event-webauthn-component) will fire containing information about the new credential, which must be stored for future use. Afterwards, this method will return successfully, indicating the registration process is complete.

Please see below for a simple example of this process:

```csharp
server.OnRegistrationInfo += (o, e) => {
  // Some List of WACredential type, search by Credential Id
  existingCredentials = QueryCredentialsById(e.CredentialId);

  if (existingCredentials.Count != 0) {
    // Registration should fail since CredentialId exists
    e.Cancel = true;
  }
};

server.OnRegistrationComplete += (o, e) => {
  // Save credential info for authentication
  SaveCredential(server.UserName, e.CredentialIdB, e.PublicKey, e.SignCount, e.Algorithm);
};

string response = StreamReader(context.Request.Body).ReadToEnd();
string cachedOptions = context.Session.GetString("registrationOptions") ?? String.Empty;

server.VerifyRegistrationResponse(response, options);

Console.WriteLine("Registration Successful.");
```

# AuthenticationComplete Event ([WebAuthn](#webauthn-component) Component)

Fired when a user successfully logs in.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  String CredentialId;
  DynamicArray<Byte> CredentialIdB;
  int SignCount;
} TipaWebAuthnAuthenticationCompleteEventParams;
typedef void __fastcall (__closure *TipaWebAuthnAuthenticationCompleteEvent)(System::TObject* Sender, TipaWebAuthnAuthenticationCompleteEventParams *e);
__property TipaWebAuthnAuthenticationCompleteEvent OnAuthenticationComplete = { read=FOnAuthenticationComplete, write=FOnAuthenticationComplete };
```

## Remarks

This event is fired when a user successfully logs in, i.e., after [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component) returns without error.

The *CredentialId* parameter should be used to identify the locally stored credential that has been used to successfully log in.

Once the stored credential is identified, the signature counter of this credential record should be updated to the value in the *SignCount* parameter.

If stored previously, implementations may also query the [BackupState](#BackupState) and [UvInitialized](#UvInitialized) configs to update the credential record accordingly.

# AuthenticationInfo Event ([WebAuthn](#webauthn-component) Component)

Fired when the component requests additional information regarding the existing credential.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  String CredentialId;
  DynamicArray<Byte> CredentialIdB;
  bool Cancel;
  String PublicKey;
  String Algorithm;
  int SignCount;
} TipaWebAuthnAuthenticationInfoEventParams;
typedef void __fastcall (__closure *TipaWebAuthnAuthenticationInfoEvent)(System::TObject* Sender, TipaWebAuthnAuthenticationInfoEventParams *e);
__property TipaWebAuthnAuthenticationInfoEvent OnAuthenticationInfo = { read=FOnAuthenticationInfo, write=FOnAuthenticationInfo };
```

## Remarks

This event is fired when the component requests additional information regarding the existing credential after calling [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component).

The *CredentialId* parameter specifies the credential Id of the existing credential.

The *Cancel* parameter may be utilized to cancel the authentication of the current user or credential.

To handle this event appropriately, the *CredentialId* parameter should be utilized to check the existing credential database. If the credential does not exist in the database, authentication should fail, and the *Cancel* parameter should be set to true.

Otherwise, if the credential exists, *PublicKey*, *Algorithm*, and *SignCount* should be set to their relevant values associated with the credential. Additionally, the [UserName](#username-property-webauthn-component) (and possibly [UserId](#userid-property-webauthn-component)) should be set to their relevant values. The component will utilize these to complete the verification and authentication process.

If stored previously, implementations may optionally set the [BackupEligible](#BackupEligible) config for use during verification.

# Error Event ([WebAuthn](#webauthn-component) Component)

Fired when information is available about errors during data delivery.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  int ErrorCode;
  String Description;
} TipaWebAuthnErrorEventParams;
typedef void __fastcall (__closure *TipaWebAuthnErrorEvent)(System::TObject* Sender, TipaWebAuthnErrorEventParams *e);
__property TipaWebAuthnErrorEvent OnError = { read=FOnError, write=FOnError };
```

## Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.

The *ErrorCode* parameter contains an error code, and the *Description* parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the [Error Codes](#trappable-errors-webauthn-component) section.

# Extension Event ([WebAuthn](#webauthn-component) Component)

Fired when an extension is found while verifying an authenticator response.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  String Name;
  String Value;
  int ValueType;
} TipaWebAuthnExtensionEventParams;
typedef void __fastcall (__closure *TipaWebAuthnExtensionEvent)(System::TObject* Sender, TipaWebAuthnExtensionEventParams *e);
__property TipaWebAuthnExtensionEvent OnExtension = { read=FOnExtension, write=FOnExtension };
```

## Remarks

This event is fired when an extension is found while verifying an authenticator response using either [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) or [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component). Any extensions from the parsed response will be added to the Extensions collection and may be manually verified in [RegistrationInfo](#registrationinfo-event-webauthn-component) or [AuthenticationInfo](#authenticationinfo-event-webauthn-component).

The *Name* parameter specifies the name of the extension.

The *Value* parameter specifies the value of the extension.

The *ValueType* parameter specifies the type of the value. Possible values are as follows:

- 0 (Object)
- 1 (Array)
- 2 (String)
- 3 (Number)
- 4 (Bool)
- 5 (Null)
- 6 (Raw)

The component will not interpret the extensions found, and it will be up to the developer to interpret the extensions accordingly. For more information and an example, please see [AddExtension](#addextension-method-webauthn-component).

# Log Event ([WebAuthn](#webauthn-component) Component)

Fired once for each log message.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  int LogLevel;
  String Message;
  String LogType;
} TipaWebAuthnLogEventParams;
typedef void __fastcall (__closure *TipaWebAuthnLogEvent)(System::TObject* Sender, TipaWebAuthnLogEventParams *e);
__property TipaWebAuthnLogEvent OnLog = { read=FOnLog, write=FOnLog };
```

## Remarks

This event is fired once for each log message generated by the component. The verbosity is controlled by the [LogLevel](#LogLevel) setting.

*LogLevel* indicates the level of message. Possible values are as follows:

|  |  |
| --- | --- |
| 0 (None) | No events are logged. |
| 1 (Info - default) | Informational events are logged. |
| 2 (Verbose) | Detailed data are logged. |
| 3 (Debug) | Debug data are logged. |

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

*Message* is the log entry.

*LogType* identifies the type of log entry. Possible values are as follows:

- "Info"
- "RequestHeaders"
- "ResponseHeaders"
- "RequestBody"
- "ResponseBody"
- "ProxyRequest"
- "ProxyResponse"
- "FirewallRequest"
- "FirewallResponse"

# RegistrationComplete Event ([WebAuthn](#webauthn-component) Component)

Fired when a user is successfully registered.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  String CredentialId;
  DynamicArray<Byte> CredentialIdB;
  String UserName;
  String PublicKey;
  int SignCount;
  String Algorithm;
} TipaWebAuthnRegistrationCompleteEventParams;
typedef void __fastcall (__closure *TipaWebAuthnRegistrationCompleteEvent)(System::TObject* Sender, TipaWebAuthnRegistrationCompleteEventParams *e);
__property TipaWebAuthnRegistrationCompleteEvent OnRegistrationComplete = { read=FOnRegistrationComplete, write=FOnRegistrationComplete };
```

## Remarks

This event is fired when a user is successfully registered, i.e., after [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) returns without error.

The *CredentialId* parameter indicates the credential Id of the new credential associated with the current *UserName*.

Along with the credential Id, the *PublicKey*, *SignCount*, and *Algorithm* parameters must be stored for future use. Specifically, these parameters will be utilized during authentication, when [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component) is called. These parameters should be directly associated with the specific user this credential was created for.

Implementations may optionally store the [BackupState](#BackupState), [BackupEligible](#BackupEligible), [UvInitialized](#UvInitialized) configs for future use. Please refer to the config descriptions for additional details.

# RegistrationInfo Event ([WebAuthn](#webauthn-component) Component)

Fired when the component requests additional information regarding the new credential.

## Syntax

*C++ Builder Syntax*

```text
typedef struct {
  String CredentialId;
  DynamicArray<Byte> CredentialIdB;
  bool Cancel;
} TipaWebAuthnRegistrationInfoEventParams;
typedef void __fastcall (__closure *TipaWebAuthnRegistrationInfoEvent)(System::TObject* Sender, TipaWebAuthnRegistrationInfoEventParams *e);
__property TipaWebAuthnRegistrationInfoEvent OnRegistrationInfo = { read=FOnRegistrationInfo, write=FOnRegistrationInfo };
```

## Remarks

This event is fired when the component requests additional information regarding the new credential after calling [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component).

The *Cancel* parameter may be utilized to cancel the authentication of the current user or credential.

To handle this event appropriately, the *CredentialId* parameter should be utilized to check the existing credential database. If the credential Id already exists in the database for **any** user, this implies that registration should fail. In this case, the *Cancel* parameter should be set to true.

Otherwise, if the credential Id does not exist in the existing credential database, the *Cancel* parameter should not be modified, and verification will succeed.

# Config Settings ([WebAuthn](#webauthn-component) Component)

 The component accepts one or more of the following *configuration settings*. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these *internal properties* is provided through the [Config](#config-method-webauthn-component) method.

### WebAuthn Config Settings

**BackupEligible**: Indicates or specifies the backup eligibility of a credential.This config indicates or specifies the backup eligibility of a credential, and may be set and/or queried during both registration and authentication. Possible values are:

- *0*: The credential is a single-device credential and may never be backed up.
- *1*: The credential is a multi-device credential and may be backed up.

During registration, this config may be queried within [RegistrationComplete](#registrationcomplete-event-webauthn-component) (or after [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) returns) in order to store the backup eligibility of the new credential for future use.

During authentication, this config may first be set during [AuthenticationInfo](#authenticationinfo-event-webauthn-component) for use during verification of the existing credential. By default, this config will be set to *-1*, implying that backup eligibility will not be utilized during verification.

After verification, this config may be queried within [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) in order to update the stored backup eligibility of the existing credential.

It is recommended to store the value of this flag along with the relevant credential for future evaluation, though not required.

**BackupState**: Indicates the backup state of a credential.This config indicates the backup state of a credential, and may be queried during both registration and authentication. Possible values are:

- *0*: The credential is not currently backed up.
- *1*: The credential is currently backed up.

During registration, this config may be queried within [RegistrationComplete](#registrationcomplete-event-webauthn-component) (or after [VerifyRegistrationResponse](#verifyregistrationresponse-method-webauthn-component) returns) in order to store the backup state of the new credential for future use.

During authentication, this config may be queried within [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) (or after [VerifyAuthenticationResponse](#verifyauthenticationresponse-method-webauthn-component) returns) in order to update the stored backup state of the existing credential.

It is recommended to store the value of this flag along with the relevant credential for future evaluation, though not required.

**Hints**: Specifies any hints to communicate to the user-agent about how a request may be completed.This config may be used to specify any hints to communicate to the user-agent about how a request may be completed. Note that hints do not indicate any requirements from the Relying Party, but may guide the user-agent in providing the best experience by using contextual information the Relying Party has about the request.

This config may be specified as a comma-separated list of one or more of the following values in order of decreasing preference:

- *security-key*: Indicates that the Relying Party believes that users will satisfy this request with a physical security key.
- *client-device*: Indicates that the Relying Party believes that users will satisfy this request with a platform authenticator attached to the client device.
- *hybrid*: Indicates that the Relying Party believes that users will satisfy this request with general-purpose authenticators such as smartphones.

For example, this config may be set to the following string: *security-key,client-device,hybrid*

**ServerChallenge**: Specifies the cryptographic challenge associated with the current options, as specified by the component.This config specifies the cryptographic challenge associated with the current options, as specified by the component.

The cryptographic challenge is some randomly generated data that is sent to the authenticator.

After calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component) or [CreateAuthenticationRequest](#createauthenticationrequest-method-webauthn-component), this may be queried to get the challenge specified in the recently created options.

**UvInitialized**: Indicates whether user verification has been performed for a new or existing credential.This config indicates whether user verification has been successfully performed for a credential. When *true*, user verification has been successfully performed. Otherwise, a value of *false* indicates that either user verification was unsuccessful, or user verification has not been performed at all.

The component can indicate whether it would like user verification to occur by setting the [UserVerification](#userverification-property-webauthn-component) property before calling [CreateRegistrationRequest](#createregistrationrequest-method-webauthn-component). This config may be queried during [RegistrationComplete](#registrationcomplete-event-webauthn-component) or [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) to determine the current user verification status of the relevant credential.

This config may be stored or updated during [RegistrationComplete](#registrationcomplete-event-webauthn-component) or [AuthenticationComplete](#authenticationcomplete-event-webauthn-component) for future use.

### Base Config Settings

**BuildInfo**: Information about the product's build.When queried, this setting will return a string containing information about the product's build.

**CodePage**: The system code page used for Unicode to Multibyte translations.The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:

|  |  |
| --- | --- |
| Identifier | Name |
| 037 | IBM EBCDIC - U.S./Canada |
| 437 | OEM - United States |
| 500 | IBM EBCDIC - International |
| 708 | Arabic - ASMO 708 |
| 709 | Arabic - ASMO 449+, BCON V4 |
| 710 | Arabic - Transparent Arabic |
| 720 | Arabic - Transparent ASMO |
| 737 | OEM - Greek (formerly 437G) |
| 775 | OEM - Baltic |
| 850 | OEM - Multilingual Latin I |
| 852 | OEM - Latin II |
| 855 | OEM - Cyrillic (primarily Russian) |
| 857 | OEM - Turkish |
| 858 | OEM - Multilingual Latin I + Euro symbol |
| 860 | OEM - Portuguese |
| 861 | OEM - Icelandic |
| 862 | OEM - Hebrew |
| 863 | OEM - Canadian-French |
| 864 | OEM - Arabic |
| 865 | OEM - Nordic |
| 866 | OEM - Russian |
| 869 | OEM - Modern Greek |
| 870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) |
| 874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) |
| 875 | IBM EBCDIC - Modern Greek |
| 932 | ANSI/OEM - Japanese, Shift-JIS |
| 936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) |
| 949 | ANSI/OEM - Korean (Unified Hangul Code) |
| 950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) |
| 1026 | IBM EBCDIC - Turkish (Latin-5) |
| 1047 | IBM EBCDIC - Latin 1/Open System |
| 1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) |
| 1141 | IBM EBCDIC - Germany (20273 + Euro symbol) |
| 1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) |
| 1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) |
| 1144 | IBM EBCDIC - Italy (20280 + Euro symbol) |
| 1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) |
| 1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) |
| 1147 | IBM EBCDIC - France (20297 + Euro symbol) |
| 1148 | IBM EBCDIC - International (500 + Euro symbol) |
| 1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) |
| 1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) |
| 1201 | Unicode UCS-2 Big-Endian |
| 1250 | ANSI - Central European |
| 1251 | ANSI - Cyrillic |
| 1252 | ANSI - Latin I |
| 1253 | ANSI - Greek |
| 1254 | ANSI - Turkish |
| 1255 | ANSI - Hebrew |
| 1256 | ANSI - Arabic |
| 1257 | ANSI - Baltic |
| 1258 | ANSI/OEM - Vietnamese |
| 1361 | Korean (Johab) |
| 10000 | MAC - Roman |
| 10001 | MAC - Japanese |
| 10002 | MAC - Traditional Chinese (Big5) |
| 10003 | MAC - Korean |
| 10004 | MAC - Arabic |
| 10005 | MAC - Hebrew |
| 10006 | MAC - Greek I |
| 10007 | MAC - Cyrillic |
| 10008 | MAC - Simplified Chinese (GB 2312) |
| 10010 | MAC - Romania |
| 10017 | MAC - Ukraine |
| 10021 | MAC - Thai |
| 10029 | MAC - Latin II |
| 10079 | MAC - Icelandic |
| 10081 | MAC - Turkish |
| 10082 | MAC - Croatia |
| 12000 | Unicode UCS-4 Little-Endian |
| 12001 | Unicode UCS-4 Big-Endian |
| 20000 | CNS - Taiwan |
| 20001 | TCA - Taiwan |
| 20002 | Eten - Taiwan |
| 20003 | IBM5550 - Taiwan |
| 20004 | TeleText - Taiwan |
| 20005 | Wang - Taiwan |
| 20105 | IA5 IRV International Alphabet No. 5 (7-bit) |
| 20106 | IA5 German (7-bit) |
| 20107 | IA5 Swedish (7-bit) |
| 20108 | IA5 Norwegian (7-bit) |
| 20127 | US-ASCII (7-bit) |
| 20261 | T.61 |
| 20269 | ISO 6937 Non-Spacing Accent |
| 20273 | IBM EBCDIC - Germany |
| 20277 | IBM EBCDIC - Denmark/Norway |
| 20278 | IBM EBCDIC - Finland/Sweden |
| 20280 | IBM EBCDIC - Italy |
| 20284 | IBM EBCDIC - Latin America/Spain |
| 20285 | IBM EBCDIC - United Kingdom |
| 20290 | IBM EBCDIC - Japanese Katakana Extended |
| 20297 | IBM EBCDIC - France |
| 20420 | IBM EBCDIC - Arabic |
| 20423 | IBM EBCDIC - Greek |
| 20424 | IBM EBCDIC - Hebrew |
| 20833 | IBM EBCDIC - Korean Extended |
| 20838 | IBM EBCDIC - Thai |
| 20866 | Russian - KOI8-R |
| 20871 | IBM EBCDIC - Icelandic |
| 20880 | IBM EBCDIC - Cyrillic (Russian) |
| 20905 | IBM EBCDIC - Turkish |
| 20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) |
| 20932 | JIS X 0208-1990 & 0121-1990 |
| 20936 | Simplified Chinese (GB2312) |
| 21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) |
| 21027 | Extended Alpha Lowercase |
| 21866 | Ukrainian (KOI8-U) |
| 28591 | ISO 8859-1 Latin I |
| 28592 | ISO 8859-2 Central Europe |
| 28593 | ISO 8859-3 Latin 3 |
| 28594 | ISO 8859-4 Baltic |
| 28595 | ISO 8859-5 Cyrillic |
| 28596 | ISO 8859-6 Arabic |
| 28597 | ISO 8859-7 Greek |
| 28598 | ISO 8859-8 Hebrew |
| 28599 | ISO 8859-9 Latin 5 |
| 28605 | ISO 8859-15 Latin 9 |
| 29001 | Europa 3 |
| 38598 | ISO 8859-8 Hebrew |
| 50220 | ISO 2022 Japanese with no halfwidth Katakana |
| 50221 | ISO 2022 Japanese with halfwidth Katakana |
| 50222 | ISO 2022 Japanese JIS X 0201-1989 |
| 50225 | ISO 2022 Korean |
| 50227 | ISO 2022 Simplified Chinese |
| 50229 | ISO 2022 Traditional Chinese |
| 50930 | Japanese (Katakana) Extended |
| 50931 | US/Canada and Japanese |
| 50933 | Korean Extended and Korean |
| 50935 | Simplified Chinese Extended and Simplified Chinese |
| 50936 | Simplified Chinese |
| 50937 | US/Canada and Traditional Chinese |
| 50939 | Japanese (Latin) Extended and Japanese |
| 51932 | EUC - Japanese |
| 51936 | EUC - Simplified Chinese |
| 51949 | EUC - Korean |
| 51950 | EUC - Traditional Chinese |
| 52936 | HZ-GB2312 Simplified Chinese |
| 54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) |
| 57002 | ISCII Devanagari |
| 57003 | ISCII Bengali |
| 57004 | ISCII Tamil |
| 57005 | ISCII Telugu |
| 57006 | ISCII Assamese |
| 57007 | ISCII Oriya |
| 57008 | ISCII Kannada |
| 57009 | ISCII Malayalam |
| 57010 | ISCII Gujarati |
| 57011 | ISCII Punjabi |
| 65000 | Unicode UTF-7 |
| 65001 | Unicode UTF-8 |

 The following is a list of valid code page identifiers for Mac OS only:

|  |  |
| --- | --- |
| Identifier | Name |
| 1 | ASCII |
| 2 | NEXTSTEP |
| 3 | JapaneseEUC |
| 4 | UTF8 |
| 5 | ISOLatin1 |
| 6 | Symbol |
| 7 | NonLossyASCII |
| 8 | ShiftJIS |
| 9 | ISOLatin2 |
| 10 | Unicode |
| 11 | WindowsCP1251 |
| 12 | WindowsCP1252 |
| 13 | WindowsCP1253 |
| 14 | WindowsCP1254 |
| 15 | WindowsCP1250 |
| 21 | ISO2022JP |
| 30 | MacOSRoman |
| 10 | UTF16String |
| 0x90000100 | UTF16BigEndian |
| 0x94000100 | UTF16LittleEndian |
| 0x8c000100 | UTF32String |
| 0x98000100 | UTF32BigEndian |
| 0x9c000100 | UTF32LittleEndian |
| 65536 | Proprietary |

**LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.

**MaskSensitiveData**: Whether sensitive data is masked in log messages.In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to *true* to mask sensitive data. The default is *true*.

**UseFIPSCompliantAPI**: Tells the component whether or not to use FIPS certified APIs.When set to *true*, the component will utilize the underlying operating system's certified APIs. Java editions, regardless of OS, utilize Bouncy Castle Federal Information Processing Standards (FIPS), while all other Windows editions make use of Microsoft security libraries.

FIPS mode can be enabled by setting the *UseFIPSCompliantAPI* configuration setting to *true*. This is a static setting that applies to all instances of all components of the toolkit within the process. It is recommended to enable or disable this setting once before the component has been used to establish a connection. Enabling FIPS while an instance of the component is active and connected may result in unexpected behavior.

For more details, please see the [FIPS 140-2 Compliance](https://www.nsoftware.com/kb/articles/fips.rst) article.

NOTE: This setting is applicable only on Windows.

NOTE: Enabling FIPS compliance requires a special license; please contact [sales@nsoftware.com](mailto:sales@nsoftware.com) for details.

**UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the component will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to *true* tells the component to use the internal implementation instead of using the system security libraries.

 This setting is set to *false* by default on all platforms.

# Trappable Errors ([WebAuthn](#webauthn-component) Component)