目录

Passkey

This module provides the following capabilities:

Since: 6.0.0(20)

Modules to Import

import { fido2 } from '@kit.OnlineAuthenticationKit';
import { BusinessError } from '@kit.BasicServicesKit';

AuthenticatorAttestationResponse

Describes the authenticator attestation response in Uint8Array format.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
attestationObject Uint8Array Yes No Data structure used to prove the validity of the newly generated key pair to the server in the response packet of the registration credential.
clientDataJson Uint8Array Yes No Client data, which represents the contextual bindings of the WebAuthn relying party and the client. The data includes the type, challenge, and origin.
publicKeyAlgorithm Algorithm No No Cryptographic algorithm.
publicKey Uint8Array No Yes Public key data generated during registration, including the public key algorithm type and key parameters. This data is used by the server to store and subsequently verify the authentication signature. The default value is empty.
authenticatorData Uint8Array No No Authenticator data, including the relying party ID hash, user presence/verification flag, signature counter, and credential data. This data is used to verify the validity of the authentication response.
transports string[] No No Authenticator transports. The values are enumerated values of AuthenticatorTransport.

AuthenticatorAttestationResponseJson

Describes the authenticator attestation response, which is a JSON string.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
clientDataJson string No No Client data, which represents the contextual bindings of the WebAuthn relying party and the client. The data includes the type, challenge, and origin. The length ranges from 0 to 4096 characters.
authenticatorData string No No Authenticator data, including the relying party ID hash, user presence/verification flag, signature counter, and credential data. This data is used to verify the validity of the authentication response. The length ranges from 0 to 4096 characters.
transports Array<string> No No Authenticator transports. The values are enumerated values of AuthenticatorTransport.
publicKey string No Yes Public key data generated during registration, including the public key algorithm type and key parameters. This data is used by the server to store and subsequently verify the authentication signature. The default value is empty. The length ranges from 0 to 4096 characters.
publicKeyAlgorithm Algorithm No No Cryptographic algorithm.
attestationObject string No No Data structure used to prove the validity of the newly generated key pair to the server in the response packet of the registration credential. The length ranges from 0 to 10,000 characters.

AuthenticationExtensionsClientOutputsJson

Describes the results of processing client extensions requested by a relying party when the relying party calls create() or get().

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

AuthenticatorAssertionResponseJson

Authenticator assertion response, which is a JSON string.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
clientDataJson string No No Client data. The length ranges from 0 to 4096 characters.
authenticatorData string No No Authenticator data, including the relying party ID hash, user presence/verification flag, signature counter, and credential data. This data is used to verify the validity of the authentication response. The length ranges from 0 to 4096 characters.
signature string No No Signature information for FIDO2 authentication. The length ranges from 0 to 4096 characters.
userHandle string No Yes User handle. The default value is empty. The length ranges from 0 to 4096 characters.

AuthenticatorAssertionResponse

Defines a struct of the authenticator assertion response.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
authenticatorData Uint8Array Yes No Authenticator data, including the relying party ID hash, user presence/verification flag, signature counter, and credential data. This data is used to verify the validity of the authentication response.
signature Uint8Array Yes No Signature information for FIDO2 authentication.
userHandle Uint8Array Yes Yes User handle. The default value is empty.
clientDataJson Uint8Array Yes No Client data.

AuthenticationExtensionsClientOutputs

Defines authentication extensions.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

PublicKeyAttestationCredential

Describes the registration response parameters.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
rawId Uint8Array Yes No Unique index of a credential.
response AuthenticatorAttestationResponse Yes No Response.
authenticatorAttachment AuthenticatorAttachment Yes Yes Authenticator information (platform or roaming). The default value is platform.
id string Yes No Credential ID (in Base64 format). The length ranges from 0 to 512 characters.
type string Yes No Credential type. The length ranges from 0 to 512 characters.
clientExtensionResults AuthenticationExtensionsClientOutputs Yes No Client extension result.
registrationResponseJson RegistrationResponseJson No No Authentication result in JSON format.

RegistrationResponseJson

Registration response parameters in JSON format.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
id string No No Credential identifier. The requirements for the identifier are distinct for each type of credential. The length ranges from 0 to 512 characters.
rawId string No No Raw credential identifier. The length ranges from 0 to 512 characters.
response AuthenticatorAttestationResponseJson No No Authenticator attestation response.
authenticatorAttachment string No Yes Authenticator information (platform or roaming). The default value is platform. The length ranges from 0 to 512 characters.
clientExtensionResults AuthenticationExtensionsClientOutputsJson No No Client extension result. The current version does not support extensions, so the placeholder is always NULL and the value corresponding to the clientExtensionResults key must be parsed into {}.
type string No No Credential type represented by this object. The length ranges from 0 to 512 characters.

PublicKeyCredentialRequestOptions

Defines the passkey authentication request parameters.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
challenge Uint8Array No No Challenge value.
timeout number No Yes Timeout. The unit is ms. The default value is 300000 (5 minutes), and the value ranges from 0 to 600000 (10 minutes).
rpId string No Yes Relying party identifier. The default value is empty. The length ranges from 0 to 512 characters.
allowCredentials Array<PublicKeyCredentialDescriptor> No Yes Additional parameter list of an authentication credential. The default value is empty.
userVerification UserVerificationRequirement No Yes User verification requirement. The default value is FIDO2_PREFERRED.
hints Array<PublicKeyCredentialHint> No Yes Authentication mode hints. The default value is [].
extensions Map<string, Object> No Yes The extensions must be a JSON string representing a Map<string, Object> object. The default value is empty.

PublicKeyAssertionCredential

Authentication response parameters.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
rawId Uint8Array Yes No Unique index of a credential.
response AuthenticatorAssertionResponse Yes No Response.
authenticatorAttachment AuthenticatorAttachment Yes Yes Authenticator information (platform or roaming). The default value is platform.
id string Yes No Credential ID (in Base64 format). The length ranges from 0 to 512 characters.
type string Yes No Credential type. The length ranges from 0 to 512 characters.
clientExtensionResults AuthenticationExtensionsClientOutputs No No Client extension result.
authenticationResponseJson AuthenticationResponseJson No No Authentication response data, which is a JSON string.

AuthenticationResponseJson

Describes authentication response parameters in JSON format.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
id string No No Credential identifier, which is a JSON string. The requirements for the identifier are distinct for each type of credential. The length ranges from 0 to 512 characters.
rawId string No No Raw credential identifier, which is a JSON string. The length ranges from 0 to 512 characters.
response AuthenticatorAssertionResponseJson No No Authenticator assertion response, which is a JSON string.
authenticatorAttachment string No Yes Authenticator information (platform or roaming). The default value is platform. The length ranges from 0 to 512 characters.
clientExtensionResults AuthenticationExtensionsClientOutputsJson No No Client extension result. The current version does not support extensions, so the placeholder is always NULL and the value corresponding to the clientExtensionResults key must be parsed into {}.
type string No No Credential type represented by this object. The length ranges from 0 to 512 characters.

CredentialMediationRequirement

Enumerates the user mediation requirements.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
SILENT 'silent' User mediation is suppressed for a given operation. If the operation can be performed without user involvement, wonderful. If user involvement is necessary, then the operation will return null rather than involving the user.
OPTIONAL 'optional' User mediation is optional. If credentials can be handed over for a given operation without user mediation, they will be. If user mediation is required, then the user agent will involve the user in the decision.
CONDITIONAL 'conditional' User mediation is required conditionally. In the authentication scenario, if the device has credentials, user mediation is required for selecting credentials. In the registration scenario, if the user has already agreed to create credentials, the credentials can be created without user mediation.
REQUIRED 'required' The user agent will not hand over credentials without user mediation.

CredentialCreationOptions

Describes the dictionary object of registration information, which contains the raw registration message.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
mediation CredentialMediationRequirement No Yes Indicates whether a given operation requires user mediation. The default value is optional.
publicKey PublicKeyCredentialCreationOptions No No FIDO2 registration message, which contains the challenge, relying party, user information, and authenticator selection result.

CredentialRequestOptions

Dictionary object of authentication information, which contains the raw authentication message and the option of whether user mediation is required.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
mediation CredentialMediationRequirement No Yes Indicates whether a given operation requires user mediation. The default value is optional.
publicKey PublicKeyCredentialRequestOptions No No FIDO2 authentication message, which contains the challenge, relying party information, user information, and authenticator selection result.

TokenBindingStatus

Enumerates the states of the TokenBinding protocol.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
PRESENT 'present' Normal communication.
SUPPORTED 'supported' Token binding is supported, but communication is not yet available.

TokenBinding

Defines the token binding protocol, which is used by the client to communicate with the relying party.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
status TokenBindingStatus No No Token binding status of the client.
id string No No Identifier. The length ranges from 0 to 512 characters.

AttestationConveyancePreference

Enumerates attestation conveyance preferences, which are referenced by a WebAuthn relying party during credential generation.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
NONE 'none' The relying party is not interested in authenticator attestation. This is the default value.
INDIRECT 'indirect' The indirect relying party wants to receive a verifiable attestation statement, but allows the client to decide how to obtain such an attestation statement.
DIRECT 'direct' The direct relying party wants to receive the attestation statement as generated by the authenticator.
ENTERPRISE 'enterprise' The relying party wants to receive an enterprise attestation statement which may include information that uniquely identifies the authenticator.

UserVerificationRequirement

The relying party may need to perform user verification (to check whether the current user is the intended user) for some operations but not for others. The enumeration class is defined to distinguish different requirement levels.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
REQUIRED 'required' User verification is required.
PREFERRED 'preferred' The relying party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the user verification flag set.
DISCOURAGED 'discouraged' The relying party does not want user verification employed during the operation.

ResidentKeyRequirement

Enumerates whether discoverable credentials are required.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
DISCOURAGED 'discouraged' The relying party prefers creating a server-side credential, but will accept a client-side discoverable credential. The client and authenticator must create server-side credentials whenever possible.
PREFERRED 'preferred' The relying party strongly prefers creating a client-side discoverable credential, but will accept a server-side credential.
REQUIRED 'required' The relying party requires a client-side discoverable credential. If a client-side discoverable credential cannot be created, the client must return an error.

AuthenticatorAttachment

Authenticator information (platform or roaming). The default value is platform.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
PLATFORM 'platform' Platform authenticator, such as a PIN, fingerprint, or face.
CROSS_PLATFORM 'cross-platform' Cross-platform authenticator, also called roaming authenticator, which includes Bluetooth, NFC, and USB.

AuthenticatorSelectionCriteria

Describes the authenticator selection criteria, which are specified by a WebAuthn relying party.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
authenticatorAttachment AuthenticatorAttachment No Yes Authenticator information. The default value is platform.
residentKey string No Yes Resident key. The default value is empty. The length ranges from 0 to 4096 characters.
requireResidentKey boolean No Yes Indicates whether a resident key is required. The value true indicates yes, and the value false indicates no. The default value is false.
userVerification UserVerificationRequirement No Yes User verification requirement. The default value is preferred.

AuthenticatorTransport

Enumerates authenticator transports.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
USB 'usb' USB.
NFC 'nfc' Near Field Communication (NFC).
BLE 'ble' Bluetooth.
SMART_CARD 'smart-card' Smart card.
HYBRID 'hybrid' Hybrid.
INTERNAL 'internal' Internal (built-in device transport).

PublicKeyCredentialDescriptor

Describes the credential parameters during registration or authentication.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
type PublicKeyCredentialType No No Credential type.
id Uint8Array No No Credential identifier.
transports Array<AuthenticatorTransport> No Yes Authenticator transports. The values are enumerated values of AuthenticatorTransport. By default, the value is an empty list.

Algorithm

Enumerates the algorithms.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
ES256 -7 ES256 algorithm.
ES384 -35 ES384 algorithm.
ES512 -36 ES512 algorithm.
RS256 -257 RS256 algorithm.
RS384 -258 RS384 algorithm.
RS512 -259 RS512 algorithm
PS256 -37 PS256 algorithm.
PS384 -38 PS384 algorithm.
PS512 -39 PS512 algorithm.

PublicKeyCredentialHint

Enumerates public key credential hints.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
SECURITY_KEY 'security-key' Security key.
CLIENT_DEVICE 'client-device' Client device.
HYBRID 'hybrid' Hybrid.

PublicKeyCredentialType

Enumerates public key credential types.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
PUBLIC_KEY 'public-key' Public key.

PublicKeyCredentialParameters

Defines the additional parameters of an authentication credential.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
type PublicKeyCredentialType No No Credential type.
alg Algorithm No No Cryptographic algorithm used by the credential.

PublicKeyCredentialUserEntity

Describes additional user properties provided during credential creation.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
id Uint8Array No No Credential identifier. The length ranges from 0 to 512 characters.
displayName string No No User name displayed on the foreground. The length ranges from 0 to 512 characters.
name string No No Username. The length ranges from 0 to 512 characters.

PublicKeyCredentialRpEntity

Defines the relying party properties provided during credential creation.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
id string No Yes Credential identifier. The default value is empty. The length ranges from 0 to 512 characters.
name string No No Username. The length ranges from 0 to 512 characters.

PublicKeyCredentialCreationOptions

Describes credential creation options.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
rp PublicKeyCredentialRpEntity No No Relying party properties provided during credential creation.
user PublicKeyCredentialUserEntity No No User information.
challenge Uint8Array No No Challenge value. The length ranges from 16 to 512 characters.
pubKeyCredParams Array<PublicKeyCredentialParameters> No No Additional parameter list of an authentication credential.
timeout number No Yes Timeout. The unit is ms. The default value is 300000 (5 minutes), and the value ranges from 0 to 600000 (10 minutes).
excludeCredentials Array<PublicKeyCredentialDescriptor> No Yes List of credentials already registered with the FIDO server. By default, the value is an empty array.
authenticatorSelection AuthenticatorSelectionCriteria No Yes Authenticator selection criteria. The default value is empty.
hints Array<PublicKeyCredentialHint> No Yes Hints. The default value is an empty array.
attestation AttestationConveyancePreference No Yes Credential conveyance preference. The default value is NONE.
attestationFormats Array<string> No Yes Preference regarding the attestation statement format used by the authenticator. It is specified by the relying party. By default, the value is an empty array.
extensions Map<string, Object> No Yes Extensions. The default value is empty.

Uvm

Enumerates platform authenticators.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
UVM_FINGERPRINT 2 Fingerprint.
UVM_PIN 4 PIN code.
UVM_FACE 16 Face.

ClientCapability

Enumerates client capabilities supported by the current device.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Value Description
CONDITIONAL_CREATE 'conditionalCreate'

Passkey registration.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
CONDITIONAL_GET 'conditionalGet'

Authentication using a passkey.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
HYBRID_TRANSPORT 'hybridTransport'

Hybrid transport, indicating multiple data transport modes.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
PASSKEY_PLATFORM_AUTHENTICATOR 'passkeyPlatformAuthenticator'

Passkey platform authenticator.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
USER_VERIFYING_PLATFORM_AUTHENTICATOR 'userVerifyingPlatformAuthenticator'

User-verifying platform authenticator.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
RELATED_ORIGINS 'relatedOrigins'

Supporting related origin requests.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
SIGNAL_ALL_ACCEPTED_CREDENTIALS 'signalAllAcceptedCredentials'

Sending all accepted credentials.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
SIGNAL_CURRENT_USER_DETAILS 'signalCurrentUserDetails'

Sending detailed information about the current user.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
SIGNAL_UNKNOWN_CREDENTIAL 'signalUnknownCredential'

Sending unknown credentials.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).
EXTENSION_LARGEBLOB 'extension:largeblob'

largeBlob extension parameter.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.
EXTENSION_AUTH_TYPE_LIST 'extension:authTypeList'

authTypeList extension parameter.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

AuthenticatorMetadata

Describes authenticator metadata.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Name Type Read-Only Optional Description
aaguid string Yes No Unique identifier of an authenticator. The length ranges from 0 to 512 characters.
uvm Uvm Yes No Supported platform authenticator type, such as face, fingerprint, and PIN.
isAvailable boolean Yes No Indicates whether an authenticator is available. The value true indicates yes, and the value false indicates no.

fido2.getClientCapabilities

getClientCapabilities(context: common.Context): Promise<Map<ClientCapability, boolean>>

Queries the client capabilities supported by the current device. This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Parameters:

Parameter Type Mandatory Description
context common.Context Yes Context of the current ability.

Returns:

Type Description
Promise<Map<ClientCapability, boolean>> Promise object, which returns the capability enumeration. The value true indicates that a capability is supported and the value false indicates not.

Error codes:

For details about the error codes, please refer to Universal Error Codes and Passkey Service Error Codes.

ID Error Message
801

Device type error.

Applicable versions: 21+6.0.1(21)+
1021300007 Unknown error.
1021300009

Data error.

Applicable versions: 26.0.0+
1021300011 Failed to connect to the service.

Example:

import { UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  uiContext = new UIContext();
  context: Context = this.uiContext.getHostContext() as common.UIAbilityContext;
  build() {
    RelativeContainer() {
      Text()
        .id('HelloWorld')
        .onClick(async () => {
          try {
            let clientCapabilities: Map<fido2.ClientCapability, boolean> =
              await fido2.getClientCapabilities(this.context);
            console.info('Succeeded in doing getClientCapabilities. clientCapabilities:', JSON.stringify(clientCapabilities));
          } catch (error) {
            const err: BusinessError = error as BusinessError;
            console.error(`Failed to call getClientCapabilities. Code is ${err.code}, message is ${err.message}`);
          }
        })
    }
  }
}

fido2.getPlatformAuthenticators

getPlatformAuthenticators(context: common.Context): Promise<Array<AuthenticatorMetadata>>

Queries the platform authenticator capabilities (face, fingerprint, and PIN) currently supported. This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Parameters:

Parameter Type Mandatory Description
context common.Context Yes Context of the current ability.

Returns:

Type Description
Promise<Array<AuthenticatorMetadata>> Authenticator metadata list returned through a promise.

Error codes:

For details about the error codes, please refer to Universal Error Codes and Passkey Service Error Codes.

ID Error Message
801

Device type error.

Applicable versions: 21+6.0.1(21)+
1021300007 Unknown error.
1021300009

Data error.

Applicable versions: 26.0.0+
1021300011 Failed to connect to the service.

Example:

import { UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  uiContext = new UIContext();
  context: Context = this.uiContext.getHostContext() as common.UIAbilityContext;
  build() {
    RelativeContainer() {
      Text()
        .id('HelloWorld')
        .onClick(async () => {
          try {
            let platformAuthenticators: Array<fido2.AuthenticatorMetadata> =
              await fido2.getPlatformAuthenticators(this.context);
            console.info('Succeeded in doing getPlatformAuthenticators. platformAuthenticators:',
              JSON.stringify(platformAuthenticators));
          } catch (error) {
            const err: BusinessError = error as BusinessError;
            console.error(`Failed to call getPlatformAuthenticators. Code is ${err.code}, message is ${err.message}`);
          }
        })
    }
  }
}

fido2.register

register(context: common.Context, options: CredentialCreationOptions, tokenBinding?: TokenBinding): Promise<PublicKeyAttestationCredential>

Registers a passkey. This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Parameters:

Parameter Type Mandatory Description
context common.Context Yes Context of the current ability.
options CredentialCreationOptions Yes Registration message options.
tokenBinding TokenBinding No Channel parameter. By default, this parameter is left empty.

Returns:

Type Description
Promise<PublicKeyAttestationCredential> Promise used to return the result.

Error codes:

For details about the error codes, please refer to Universal Error Codes and Passkey Service Error Codes.

ID Error Message
801

Device type error.

Applicable versions: 21+6.0.1(21)+
1021300001 The system does not support.
1021300002 Invalid state.
1021300003 System integrity check failed.
1021300004 User abort.
1021300005 Time out.
1021300006 Encoding error.
1021300007 Unknown error.
1021300008 The constraint condition is incorrect.
1021300009 Data error.
1021300010 User Rejects.
1021300011 Failed to connect to the service.
1021300012 The number of credentials has reached the maximum limit.

Example:

import { UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  uiContext = new UIContext();
  context: Context = this.uiContext.getHostContext() as common.UIAbilityContext;
  build() {
    RelativeContainer() {
      Text()
        .id('HelloWorld')
        .onClick(async () => {
          let pkOptions: fido2.PublicKeyCredentialCreationOptions = {
            rp: { id: 'example.com', name: 'Example Corp' },
            user: { id: new Uint8Array([1, 2, 3, 4]), name: 'user', displayName: 'User Name' },
            pubKeyCredParams: [
            ],
            challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8])
          };
          let credentialCreationOp: fido2.CredentialCreationOptions = {
            publicKey: pkOptions
          };
          try {
            let publicKeyAttestationCredential: fido2.PublicKeyAttestationCredential =
              await fido2.register(this.context, credentialCreationOp);
            console.info('Succeeded in doing register. publicKeyAttestationCredential:',
              JSON.stringify(publicKeyAttestationCredential));
          } catch (error) {
            const err: BusinessError = error as BusinessError;
            console.error(`Failed to call register. Code is ${err.code}, message is ${err.message}`);
          }
        })
    }
  }
}

fido2.authenticate

authenticate(context: common.Context, options: CredentialRequestOptions, tokenBinding?: TokenBinding): Promise<PublicKeyAssertionCredential>

Performs authentication using a passkey. This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.FIDO2

Since: 6.0.0(20)

Parameters:

Parameter Type Mandatory Description
context common.Context Yes Context of the current ability.
options CredentialRequestOptions Yes Authentication message options.
tokenBinding TokenBinding No Channel parameter. By default, this parameter is left empty.

Returns:

Type Description
Promise<PublicKeyAssertionCredential> Promise used to return the authentication result.

Error codes:

For details about the error codes, please refer to Universal Error Codes and Passkey Service Error Codes.

ID Error Message
801

Device type error.

Applicable versions: 21+6.0.1(21)+
1021300002 Invalid state.
1021300003 System integrity check failed.
1021300004 User abort.
1021300005 Time out.
1021300006 Encoding error.
1021300007 Unknown error.
1021300009 Data error.
1021300010 User Rejects.
1021300011 Failed to connect to the service.
1021300013

Switched to the custom authentication process.

Applicable versions: 26.0.0+
1021310001 Invalid CTAP command.
1021310002 The command contains invalid parameters.
1021310003 Invalid message or attribute length.
1021310004 Invalid CBOR or unpredictable error.
1021310005 Failed to parse the CBOR.
1021310006 Not found valid credentials.
1021310007 Not allowed.
1021310008 User verification failed.
1021310009 Other error.

Example:

import { UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  uiContext = new UIContext();
  context: Context = this.uiContext.getHostContext() as common.UIAbilityContext;
  build() {
    RelativeContainer() {
      Text()
        .id('HelloWorld')
        .onClick(async () => {
          let authPub: fido2.PublicKeyCredentialRequestOptions = {
            challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]),
            rpId: 'example.com'
          };
          let authCredentialRequestOptions: fido2.CredentialRequestOptions = {
            publicKey: authPub,
            mediation: 'optional' as fido2.CredentialMediationRequirement
          };
          try {
            let pkAssertionCredential: fido2.PublicKeyAssertionCredential =
              await fido2.authenticate(this.context, authCredentialRequestOptions);
            console.info('Succeeded in doing authenticate. pkAssertionCredential:', JSON.stringify(pkAssertionCredential));
          } catch (error) {
            const err: BusinessError = error as BusinessError;
            console.error(`Failed to call authenticate. Code is ${err.code}, message is ${err.message}`);
          }
        })
    }
  }
}