WebAuthn Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

WebAuthn

Remarks

The WebAuthn class 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 class 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 class 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 class by using the following properties:

• Origin
• RelyingPartyId
• RelyingPartyName

The Origin 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, ensures the application's security by restricting requests to valid origins and domains, preventing unauthorized entities from attempting to use credentials.

The RelyingPartyId 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. Using the previous example, this would mean login.example.com would be used as the RelyingPartyId.

The RelyingPartyId can be manually specified, though it should be ensured that a valid effective domain is defined for the given Origin. Using the previous example, example.com would suffice, however, m.login.example.com would be an invalid identifier.

The RelyingPartyName is a user-friendly identifier for the class, 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 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 to use across all operations from related origins. Additionally, a JSON document must be hosted at the webauthn well-known URL for the RelyingPartyId (e.g., hosted at https://RelyingPartyId/.well-known/webauthn) as described here. This document should contain all origins specified in Origin.

Please see below for a simple example of configuring the mentioned properties. Note that at the very least, Origin must be set for each step of the registration and authentication processes below.

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 initates a request to the front-end script, which should then communicate with the class to start this process.

During registration, the class is first required to build options for creating, or registering, a new user credential by calling CreateRegistrationRequest. 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. The UserName property should be set to the user-friendly identifier for the user account attempting registration. Typically, the UserName is provided by the client in the front-end request. The client may also provide the UserDisplayName, specifying a name associated with the user account intended only for display.

The UserId property may be set to some unique identifier for the relevant UserName. By default, the UserId is empty, and will be calculated by the class as the SHA256 hash of the provided UserName. 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 has existing credentials previously obtained from various authenticators. Before calling CreateRegistrationRequest, implementations should query their existing credential database for credentials associated with the specified UserName. Once identified, the UserCredentials collection should be populated by calling AddUserCredential for each credential. Doing so will ensure that a new credential is not created on an authenticator containing a credential mapped to this UserName. 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
• AuthenticatorAttachment
• DiscoverableCredentials
• Extensions
• PublicKeyAlgorithms
• Timeout
• UserVerification

Once the class is configured, CreateRegistrationRequest 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 class.

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

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 class. To verify the authenticator response, VerifyRegistrationResponse should be called, taking the options previously generated with CreateRegistrationRequest and the recently received response as parameters.

After calling VerifyRegistrationResponse, the RegistrationInfo 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 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 class succeeds, RegistrationComplete 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 associated with the credential.
2. If manually specified, the associated UserId.
3. The CredentialId parameter of RegistrationComplete.
4. The PublicKey parameter of RegistrationComplete.
5. The SignCount parameter of RegistrationComplete.
6. The Algorithm parameter of RegistrationComplete.

Additionally, implementations may wish to store the BackupEligible, BackupState, and 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:

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 class to start this process.

During authentication, the class is first required to build options for logging in using an existing user credential by calling CreateAuthenticationRequest. 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.

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 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 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 class can indicate its preference regarding whether a discoverable credential is created using the DiscoverableCredentials 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

Once the class is configured, CreateAuthenticationRequest 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 class.

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

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 class. To verify the authenticator response, VerifyAuthenticationResponse should be called, taking the recently received response, and the options previously generated with CreateAuthenticationRequest (stored in the HTTP context).

After calling VerifyAuthenticationResponse, the AuthenticationInfo 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 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:

• The current UserName associated with the credential.
• If manually specified, the associated UserId.
• The PublicKey parameter of AuthenticationInfo.
• The SignCount parameter of AuthenticationInfo.
• The Algorithm parameter of AuthenticationInfo.

Assuming this information is correct, the class will continue the verification process accordingly, and AuthenticationComplete 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.

Implementations may wish to query the values of the BackupState and 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:

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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

AttestationType Property (WebAuthn Class)

Specifies the preference regarding attestation conveyance during registration.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAttestationType();
int SetAttestationType(int iAttestationType);

Unicode (Windows)
INT GetAttestationType();
INT SetAttestationType(INT iAttestationType);

AT_NONE(0), 
AT_INDIRECT(1), 
AT_DIRECT(2), 
AT_ENTERPRISE(3)

int ipworkswebauthn_webauthn_getattestationtype(void* lpObj);
int ipworkswebauthn_webauthn_setattestationtype(void* lpObj, int iAttestationType);

int getAttestationType();
int setAttestationType(int iAttestationType);

Default Value

0

Remarks

This property specifies the preference regarding attestation conveyance during registration. This value may be set prior to calling CreateRegistrationRequest. Possible values include:

Data Type

Integer

AuthenticatorAttachment Property (WebAuthn Class)

Specifies the preference regarding authenticator attachment modality during registration.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAuthenticatorAttachment();
int SetAuthenticatorAttachment(int iAuthenticatorAttachment);

Unicode (Windows)
INT GetAuthenticatorAttachment();
INT SetAuthenticatorAttachment(INT iAuthenticatorAttachment);

AT_ANY(0), 
AT_PLATFORM(1), 
AT_CROSS_PLATFORM(2)

int ipworkswebauthn_webauthn_getauthenticatorattachment(void* lpObj);
int ipworkswebauthn_webauthn_setauthenticatorattachment(void* lpObj, int iAuthenticatorAttachment);

int getAuthenticatorAttachment();
int setAuthenticatorAttachment(int iAuthenticatorAttachment);

Default Value

0

Remarks

This property specifies the preference regarding authenticator attachment modality. This value may be set prior to calling CreateRegistrationRequest. Possible values include:

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDiscoverableCredentials();
int SetDiscoverableCredentials(int iDiscoverableCredentials);

Unicode (Windows)
INT GetDiscoverableCredentials();
INT SetDiscoverableCredentials(INT iDiscoverableCredentials);

DC_UNSPECIFIED(0), 
DC_DISCOURAGED(1), 
DC_PREFERRED(2), 
DC_REQUIRED(3)

int ipworkswebauthn_webauthn_getdiscoverablecredentials(void* lpObj);
int ipworkswebauthn_webauthn_setdiscoverablecredentials(void* lpObj, int iDiscoverableCredentials);

int getDiscoverableCredentials();
int setDiscoverableCredentials(int iDiscoverableCredentials);

Default Value

0

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. Possible values include:

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, and assuming the credential exists, relevant credential information should be provided.

This property is not available at design time.

Data Type

Integer

Extensions Property (WebAuthn Class)

Specifies extensions that will either be sent to the client, or have been sent to the class.

Syntax

• C++
• C
• Qt

IPWorksWebAuthnList<IPWorksWebAuthnWAExtension>* GetExtensions();

int ipworkswebauthn_webauthn_getwaextensioncount(void* lpObj);

char* ipworkswebauthn_webauthn_getwaextensionname(void* lpObj, int waextensionindex);

char* ipworkswebauthn_webauthn_getwaextensionvalue(void* lpObj, int waextensionindex);

int ipworkswebauthn_webauthn_getwaextensionvaluetype(void* lpObj, int waextensionindex);

int getWAExtensionCount();

QString getWAExtensionName(int iWAExtensionIndex);

QString getWAExtensionValue(int iWAExtensionIndex);

int getWAExtensionValueType(int iWAExtensionIndex);

Remarks

This property specifies extensions utilized by the class in two different cases.

In the first case, this property will be populated using AddExtension, which should be called to send extensions to the client prior to CreateRegistrationRequest and CreateAuthenticationRequest.

In the second case, this property may be populated after parsing an authenticator response with VerifyRegistrationResponse or VerifyAuthenticationResponse. Typically, the parsed extensions will be responses to any extensions sent during the first case, and implementations can view the result either in Extension, or RegistrationInfo and AuthenticationInfo.

In RegistrationInfo and AuthenticationInfo implementations may perform validation of the extensions present (or missing) from this collection. While implementations may verify responses to all previously sent extensions were received in the response, implementations must be able to handle such situations where unsolicited extensions were received, or certain extensions were ignored. Please see RegistrationInfo and AuthenticationInfo for additional details.

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

Data Type

IPWorksWebAuthnWAExtension

Origin Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOrigin();
int SetOrigin(const char* lpszOrigin);

Unicode (Windows)
LPWSTR GetOrigin();
INT SetOrigin(LPCWSTR lpszOrigin);

char* ipworkswebauthn_webauthn_getorigin(void* lpObj);
int ipworkswebauthn_webauthn_setorigin(void* lpObj, const char* lpszOrigin);

QString getOrigin();
int setOrigin(QString qsOrigin);

Default Value

""

Remarks

This property specifies the full web origin, including the protocol (http or https) and domain, of the class (WebAuthn Relying Party). The origin must be specified before calling CreateRegistrationRequest, VerifyRegistrationResponse, CreateAuthenticationRequest, and VerifyAuthenticationResponse.

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 will be set to the default effective domain of the origin. In the above example, RelyingPartyId would be set to login.example.com.

The RelyingPartyId 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 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 to use across all operations from related origins. Additionally, a JSON document must be hosted at the webauthn well-known URL for the RelyingPartyId (e.g., hosted at https://RelyingPartyId/.well-known/webauthn) as described here. This document should contain all origins specified in Origin.

Data Type

String

PublicKeyAlgorithms Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPublicKeyAlgorithms();
int SetPublicKeyAlgorithms(const char* lpszPublicKeyAlgorithms);

Unicode (Windows)
LPWSTR GetPublicKeyAlgorithms();
INT SetPublicKeyAlgorithms(LPCWSTR lpszPublicKeyAlgorithms);

char* ipworkswebauthn_webauthn_getpublickeyalgorithms(void* lpObj);
int ipworkswebauthn_webauthn_setpublickeyalgorithms(void* lpObj, const char* lpszPublicKeyAlgorithms);

QString getPublicKeyAlgorithms();
int setPublicKeyAlgorithms(QString qsPublicKeyAlgorithms);

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.

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, after verifying the authenticator response using VerifyRegistrationResponse.

Data Type

String

RelyingPartyId Property (WebAuthn Class)

Specifies the unique identifier of the Relying Party.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRelyingPartyId();
int SetRelyingPartyId(const char* lpszRelyingPartyId);

Unicode (Windows)
LPWSTR GetRelyingPartyId();
INT SetRelyingPartyId(LPCWSTR lpszRelyingPartyId);

char* ipworkswebauthn_webauthn_getrelyingpartyid(void* lpObj);
int ipworkswebauthn_webauthn_setrelyingpartyid(void* lpObj, const char* lpszRelyingPartyId);

QString getRelyingPartyId();
int setRelyingPartyId(QString qsRelyingPartyId);

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. For example, if the Origin is specified as https://example.com, this property will be set to example.com.

The RelyingPartyId can be manually specified after setting Origin, 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 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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRelyingPartyName();
int SetRelyingPartyName(const char* lpszRelyingPartyName);

Unicode (Windows)
LPWSTR GetRelyingPartyName();
INT SetRelyingPartyName(LPCWSTR lpszRelyingPartyName);

char* ipworkswebauthn_webauthn_getrelyingpartyname(void* lpObj);
int ipworkswebauthn_webauthn_setrelyingpartyname(void* lpObj, const char* lpszRelyingPartyName);

QString getRelyingPartyName();
int setRelyingPartyName(QString qsRelyingPartyName);

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, VerifyRegistrationResponse, CreateAuthenticationRequest, and VerifyAuthenticationResponse.

Data Type

String

Timeout Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int ipworkswebauthn_webauthn_gettimeout(void* lpObj);
int ipworkswebauthn_webauthn_settimeout(void* lpObj, int iTimeout);

int getTimeout();
int setTimeout(int iTimeout);

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 or CreateAuthenticationRequest, this value simply represents a hint for the time the class 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

UserCredentials Property (WebAuthn Class)

Specifies existing credentials for a user account.

Syntax

• C++
• C
• Qt

IPWorksWebAuthnList<IPWorksWebAuthnWACredential>* GetUserCredentials();

int ipworkswebauthn_webauthn_getwacredentialcount(void* lpObj);

int ipworkswebauthn_webauthn_getwacredentialid(void* lpObj, int wacredentialindex, char** lpWACredentialId, int* lenWACredentialId);

char* ipworkswebauthn_webauthn_getwacredentialpublickey(void* lpObj, int wacredentialindex);

char* ipworkswebauthn_webauthn_getwacredentialsignalgorithm(void* lpObj, int wacredentialindex);

int ipworkswebauthn_webauthn_getwacredentialsigncount(void* lpObj, int wacredentialindex);

int getWACredentialCount();

QByteArray getWACredentialId(int iWACredentialIndex);

QString getWACredentialPublicKey(int iWACredentialIndex);

QString getWACredentialSignAlgorithm(int iWACredentialIndex);

int getWACredentialSignCount(int iWACredentialIndex);

Remarks

This property specifies existing credentials for a user account. This collection may be populated using AddUserCredential before calling CreateRegistrationRequest or CreateAuthenticationRequest.

Before calling CreateRegistrationRequest, AddUserCredential may be called for each credential that exists for the specified UserName. This will ensure that the new credential is not created on an authenticator that already contains a credential mapped to the specific UserName. If a mapped credential for the selected authenticator already exists, this may result in an error.

Before calling CreateAuthenticationRequest, if a username is provided by the front-end, AddUserCredential may be called for each existing credential for the identified user account. The UserName 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 class initially. After receiving a response from the authenticator and calling VerifyAuthenticationResponse, the utilized credential will be present in AuthenticationInfo.

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

Data Type

IPWorksWebAuthnWACredential

UserDisplayName Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetUserDisplayName();
int SetUserDisplayName(const char* lpszUserDisplayName);

Unicode (Windows)
LPWSTR GetUserDisplayName();
INT SetUserDisplayName(LPCWSTR lpszUserDisplayName);

char* ipworkswebauthn_webauthn_getuserdisplayname(void* lpObj);
int ipworkswebauthn_webauthn_setuserdisplayname(void* lpObj, const char* lpszUserDisplayName);

QString getUserDisplayName();
int setUserDisplayName(QString qsUserDisplayName);

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUserId(char* &lpUserId, int &lenUserId);
int SetUserId(const char* lpUserId, int lenUserId);

Unicode (Windows)
INT GetUserId(LPSTR &lpUserId, INT &lenUserId);
INT SetUserId(LPCSTR lpUserId, INT lenUserId);

int ipworkswebauthn_webauthn_getuserid(void* lpObj, char** lpUserId, int* lenUserId);
int ipworkswebauthn_webauthn_setuserid(void* lpObj, const char* lpUserId, int lenUserId);

QByteArray getUserId();
int setUserId(QByteArray qbaUserId);

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 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

Binary String

UserName Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetUserName();
int SetUserName(const char* lpszUserName);

Unicode (Windows)
LPWSTR GetUserName();
INT SetUserName(LPCWSTR lpszUserName);

char* ipworkswebauthn_webauthn_getusername(void* lpObj);
int ipworkswebauthn_webauthn_setusername(void* lpObj, const char* lpszUserName);

QString getUserName();
int setUserName(QString qsUserName);

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.

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

By default, the UserId will be calculated as the SHA256 hash of this property for use during registration and authentication.

Data Type

String

UserVerification Property (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUserVerification();
int SetUserVerification(int iUserVerification);

Unicode (Windows)
INT GetUserVerification();
INT SetUserVerification(INT iUserVerification);

UV_REQUIRED(0), 
UV_PREFERRED(1), 
UV_DISCOURAGED(2)

int ipworkswebauthn_webauthn_getuserverification(void* lpObj);
int ipworkswebauthn_webauthn_setuserverification(void* lpObj, int iUserVerification);

int getUserVerification();
int setUserVerification(int iUserVerification);

Default Value

1

Remarks

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

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 config, which may be queried during RegistrationComplete or AuthenticationComplete. This config may be stored or updated during these events for future use.

Data Type

Integer

AddExtension Method (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddExtension(const char* lpszName, const char* lpszValue, int iValueType);

Unicode (Windows)
INT AddExtension(LPCWSTR lpszName, LPCWSTR lpszValue, INT iValueType);

int ipworkswebauthn_webauthn_addextension(void* lpObj, const char* lpszName, const char* lpszValue, int iValueType);

int addExtension(const QString& qsName, const QString& qsValue, int iValueType);

Remarks

This method is used to add an extension to include when building the options for registration or authentication (i.e., when calling CreateRegistrationRequest and CreateAuthenticationRequest, 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, you can do the following:

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 or VerifyAuthenticationResponse. For each extension, the Extension 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 should be updated accordingly to ensure that verification succeeds. For example:

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"; } };

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddUserCredential Method (WebAuthn Class)

Used to add a user credential to the UserCredentials collection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddUserCredential(const char* lpcredentialId, int lencredentialId, const char* lpszpublicKey, int isignCount, const char* lpszalgorithm);

Unicode (Windows)
INT AddUserCredential(LPCSTR lpcredentialId, INT lencredentialId, LPCWSTR lpszpublicKey, INT isignCount, LPCWSTR lpszalgorithm);

int ipworkswebauthn_webauthn_addusercredential(void* lpObj, const char* lpcredentialId, int lencredentialId, const char* lpszpublicKey, int isignCount, const char* lpszalgorithm);

int addUserCredential(QByteArray& qbacredentialId, const QString& qspublicKey, int isignCount, const QString& qsalgorithm);

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 prior to calling CreateRegistrationRequest and CreateAuthenticationRequest.

Before calling CreateRegistrationRequest, this method should be called for each credential that exists for the given UserName. 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. If a mapped credential for the selected authenticator already exists, this may result in an error.

Before calling CreateAuthenticationRequest, if a username is provided by the front-end, AddUserCredential should be called for each existing credential for the identified user account. The UserName 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 class initially. After receiving a response from the authenticator and calling VerifyAuthenticationResponse, the utilized credential will be present in AuthenticationInfo.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (WebAuthn Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworkswebauthn_webauthn_config(void* lpObj, const char* lpszConfigurationString);

QString config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateAuthenticationRequest Method (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CreateAuthenticationRequest();

Unicode (Windows)
LPWSTR CreateAuthenticationRequest();

char* ipworkswebauthn_webauthn_createauthenticationrequest(void* lpObj);

QString 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, RelyingPartyId, and/or RelyingPartyName must be set accordingly.

Additionally, if the user account has been identified (i.e., the user has specified their username), AddUserCredential 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

Please see below for a simple example of this process:

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);

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateRegistrationRequest Method (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CreateRegistrationRequest();

Unicode (Windows)
LPWSTR CreateRegistrationRequest();

char* ipworkswebauthn_webauthn_createregistrationrequest(void* lpObj);

QString 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, RelyingPartyId, and/or RelyingPartyName must be set accordingly.

To identify the user performing registration, the UserName, UserDisplayName, and UserId should be specified. Additionally, AddUserCredential 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
• AuthenticatorAttachment
• DiscoverableCredentials
• Extensions
• PublicKeyAlgorithms
• Timeout
• UserVerification

Please see below for a simple example of this process:

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);

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Reset Method (WebAuthn Class)

Resets the class properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworkswebauthn_webauthn_reset(void* lpObj);

int reset();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

VerifyAuthenticationResponse Method (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int VerifyAuthenticationResponse(const char* lpszresponse, const char* lpszoptions);

Unicode (Windows)
INT VerifyAuthenticationResponse(LPCWSTR lpszresponse, LPCWSTR lpszoptions);

int ipworkswebauthn_webauthn_verifyauthenticationresponse(void* lpObj, const char* lpszresponse, const char* lpszoptions);

int verifyAuthenticationResponse(const QString& qsresponse, const QString& qsoptions);

Remarks

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

Before calling this method, Origin, RelyingPartyId, and/or RelyingPartyName 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 during the first step of authentication.

After parsing the Response and Options parameters, the class will first attempt to verify the Response. During verification, AuthenticationInfo 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 class. Please see AuthenticationInfo for additional information.

Assuming the response is successfully verified, AuthenticationComplete 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:

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.");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

VerifyRegistrationResponse Method (WebAuthn Class)

Used to register a new credential.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int VerifyRegistrationResponse(const char* lpszresponse, const char* lpszoptions);

Unicode (Windows)
INT VerifyRegistrationResponse(LPCWSTR lpszresponse, LPCWSTR lpszoptions);

int ipworkswebauthn_webauthn_verifyregistrationresponse(void* lpObj, const char* lpszresponse, const char* lpszoptions);

int verifyRegistrationResponse(const QString& qsresponse, const QString& qsoptions);

Remarks

This method is used to register a new credential.

Before calling this method, Origin, RelyingPartyId, and/or RelyingPartyName 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 during the first step of registration.

After parsing the Response and Options parameters, the class will first attempt to verify the Response. During verification, RegistrationInfo 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 for additional information.

Assuming the response is successfully verified, RegistrationComplete 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:

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.");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AuthenticationComplete Event (WebAuthn Class)

Fired when a user successfully logs in.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAuthenticationComplete(WebAuthnAuthenticationCompleteEventParams *e);

typedef struct {
  const char *CredentialId;
  int lenCredentialId;
  int SignCount;
  int reserved;
} WebAuthnAuthenticationCompleteEventParams;


Unicode (Windows)
virtual INT FireAuthenticationComplete(WebAuthnAuthenticationCompleteEventParams *e);

typedef struct {
  LPCSTR CredentialId;
  INT lenCredentialId;
  INT SignCount;
  INT reserved;
} WebAuthnAuthenticationCompleteEventParams;

#define EID_WEBAUTHN_AUTHENTICATIONCOMPLETE 1

virtual INT IPWORKSWEBAUTHN_CALL FireAuthenticationComplete(LPSTR &lpCredentialId, INT &lenCredentialId, INT &iSignCount);

class WebAuthnAuthenticationCompleteEventParams {
public:
  const QByteArray &credentialId();

  int signCount();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireAuthenticationComplete(WebAuthnAuthenticationCompleteEventParams *e) {...}
// Or, connect one or more slots to this signal.
void authenticationComplete(WebAuthnAuthenticationCompleteEventParams *e);

Remarks

This event is fired when a user successfully logs in, i.e., after VerifyAuthenticationResponse 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 and UvInitialized configs to update the credential record accordingly.

AuthenticationInfo Event (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAuthenticationInfo(WebAuthnAuthenticationInfoEventParams *e);

typedef struct {
  const char *CredentialId;
  int lenCredentialId;
  int Cancel;
  char *PublicKey;
  char *Algorithm;
  int SignCount;
  int reserved;
} WebAuthnAuthenticationInfoEventParams;


Unicode (Windows)
virtual INT FireAuthenticationInfo(WebAuthnAuthenticationInfoEventParams *e);

typedef struct {
  LPCSTR CredentialId;
  INT lenCredentialId;
  BOOL Cancel;
  LPWSTR PublicKey;
  LPWSTR Algorithm;
  INT SignCount;
  INT reserved;
} WebAuthnAuthenticationInfoEventParams;

#define EID_WEBAUTHN_AUTHENTICATIONINFO 2

virtual INT IPWORKSWEBAUTHN_CALL FireAuthenticationInfo(LPSTR &lpCredentialId, INT &lenCredentialId, BOOL &bCancel, LPSTR &lpszPublicKey, LPSTR &lpszAlgorithm, INT &iSignCount);

class WebAuthnAuthenticationInfoEventParams {
public:
  const QByteArray &credentialId();

  bool cancel();
  void setCancel(bool bCancel);

  const QString &publicKey();
  void setPublicKey(const QString &qsPublicKey);

  const QString &algorithm();
  void setAlgorithm(const QString &qsAlgorithm);

  int signCount();
  void setSignCount(int iSignCount);

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireAuthenticationInfo(WebAuthnAuthenticationInfoEventParams *e) {...}
// Or, connect one or more slots to this signal.
void authenticationInfo(WebAuthnAuthenticationInfoEventParams *e);

Remarks

This event is fired when the class requests additional information regarding the existing credential after calling VerifyAuthenticationResponse.

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 (and possibly UserId) should be set to their relevant values. The class will utilize these to complete the verification and authentication process.

If stored previously, implementations may optionally set the BackupEligible config for use during verification.

Error Event (WebAuthn Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(WebAuthnErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} WebAuthnErrorEventParams;


Unicode (Windows)
virtual INT FireError(WebAuthnErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} WebAuthnErrorEventParams;

#define EID_WEBAUTHN_ERROR 3

virtual INT IPWORKSWEBAUTHN_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class WebAuthnErrorEventParams {
public:
  int errorCode();

  const QString &description();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireError(WebAuthnErrorEventParams *e) {...}
// Or, connect one or more slots to this signal.
void error(WebAuthnErrorEventParams *e);

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

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 section.

Extension Event (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireExtension(WebAuthnExtensionEventParams *e);

typedef struct {
  const char *Name;
  const char *Value;
  int ValueType;
  int reserved;
} WebAuthnExtensionEventParams;


Unicode (Windows)
virtual INT FireExtension(WebAuthnExtensionEventParams *e);

typedef struct {
  LPCWSTR Name;
  LPCWSTR Value;
  INT ValueType;
  INT reserved;
} WebAuthnExtensionEventParams;

#define EID_WEBAUTHN_EXTENSION 4

virtual INT IPWORKSWEBAUTHN_CALL FireExtension(LPSTR &lpszName, LPSTR &lpszValue, INT &iValueType);

class WebAuthnExtensionEventParams {
public:
  const QString &name();

  const QString &value();

  int valueType();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireExtension(WebAuthnExtensionEventParams *e) {...}
// Or, connect one or more slots to this signal.
void extension(WebAuthnExtensionEventParams *e);

Remarks

This event is fired when an extension is found while verifying an authenticator response using either VerifyRegistrationResponse or VerifyAuthenticationResponse. Any extensions from the parsed response will be added to the Extensions collection and may be manually verified in RegistrationInfo or AuthenticationInfo.

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 class 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.

Log Event (WebAuthn Class)

Fired once for each log message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireLog(WebAuthnLogEventParams *e);

typedef struct {
  int LogLevel;
  const char *Message;
  const char *LogType;
  int reserved;
} WebAuthnLogEventParams;


Unicode (Windows)
virtual INT FireLog(WebAuthnLogEventParams *e);

typedef struct {
  INT LogLevel;
  LPCWSTR Message;
  LPCWSTR LogType;
  INT reserved;
} WebAuthnLogEventParams;

#define EID_WEBAUTHN_LOG 5

virtual INT IPWORKSWEBAUTHN_CALL FireLog(INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);

class WebAuthnLogEventParams {
public:
  int logLevel();

  const QString &message();

  const QString &logType();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireLog(WebAuthnLogEventParams *e) {...}
// Or, connect one or more slots to this signal.
void log(WebAuthnLogEventParams *e);

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

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

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 Class)

Fired when a user is successfully registered.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireRegistrationComplete(WebAuthnRegistrationCompleteEventParams *e);

typedef struct {
  const char *CredentialId;
  int lenCredentialId;
  const char *UserName;
  const char *PublicKey;
  int SignCount;
  const char *Algorithm;
  int reserved;
} WebAuthnRegistrationCompleteEventParams;


Unicode (Windows)
virtual INT FireRegistrationComplete(WebAuthnRegistrationCompleteEventParams *e);

typedef struct {
  LPCSTR CredentialId;
  INT lenCredentialId;
  LPCWSTR UserName;
  LPCWSTR PublicKey;
  INT SignCount;
  LPCWSTR Algorithm;
  INT reserved;
} WebAuthnRegistrationCompleteEventParams;

#define EID_WEBAUTHN_REGISTRATIONCOMPLETE 6

virtual INT IPWORKSWEBAUTHN_CALL FireRegistrationComplete(LPSTR &lpCredentialId, INT &lenCredentialId, LPSTR &lpszUserName, LPSTR &lpszPublicKey, INT &iSignCount, LPSTR &lpszAlgorithm);

class WebAuthnRegistrationCompleteEventParams {
public:
  const QByteArray &credentialId();

  const QString &userName();

  const QString &publicKey();

  int signCount();

  const QString &algorithm();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireRegistrationComplete(WebAuthnRegistrationCompleteEventParams *e) {...}
// Or, connect one or more slots to this signal.
void registrationComplete(WebAuthnRegistrationCompleteEventParams *e);

Remarks

This event is fired when a user is successfully registered, i.e., after VerifyRegistrationResponse 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 is called. These parameters should be directly associated with the specific user this credential was created for.

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

RegistrationInfo Event (WebAuthn Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireRegistrationInfo(WebAuthnRegistrationInfoEventParams *e);

typedef struct {
  const char *CredentialId;
  int lenCredentialId;
  int Cancel;
  int reserved;
} WebAuthnRegistrationInfoEventParams;


Unicode (Windows)
virtual INT FireRegistrationInfo(WebAuthnRegistrationInfoEventParams *e);

typedef struct {
  LPCSTR CredentialId;
  INT lenCredentialId;
  BOOL Cancel;
  INT reserved;
} WebAuthnRegistrationInfoEventParams;

#define EID_WEBAUTHN_REGISTRATIONINFO 7

virtual INT IPWORKSWEBAUTHN_CALL FireRegistrationInfo(LPSTR &lpCredentialId, INT &lenCredentialId, BOOL &bCancel);

class WebAuthnRegistrationInfoEventParams {
public:
  const QByteArray &credentialId();

  bool cancel();
  void setCancel(bool bCancel);

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass WebAuthn and override this emitter function.
virtual int fireRegistrationInfo(WebAuthnRegistrationInfoEventParams *e) {...}
// Or, connect one or more slots to this signal.
void registrationInfo(WebAuthnRegistrationInfoEventParams *e);

Remarks

This event is fired when the class requests additional information regarding the new credential after calling VerifyRegistrationResponse.

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.

WACredential Type

Represents a WebAuthn credential record.

Syntax

IPWorksWebAuthnWACredential (declared in ipworkswebauthn.h)

Remarks

This type represents a WebAuthn credential record.

• Id
• PublicKey
• SignAlgorithm
• SignCount

Fields

Constructors

WACredential()

WAExtension Type

Represents an extension that will either be sent to the client and authenticator, or has been received from the client and authenticator.

Syntax

IPWorksWebAuthnWAExtension (declared in ipworkswebauthn.h)

Remarks

This type represents an extension that will either be sent to the client and authenticator, or has been received from the client and authenticator.

• Name
• Value
• ValueType

Fields

Constructors

WAExtension()

IPWorksWebAuthnList Type

Syntax

IPWorksWebAuthnList<T> (declared in ipworkswebauthn.h)

Remarks

IPWorksWebAuthnList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the WebAuthn class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (WebAuthn Class)

WebAuthn Config Settings

Base Config Settings

Trappable Errors (WebAuthn Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.