getCredential

@Blocking
fun getCredential(id: String, skipStatusCheck: Boolean = false): MobileCredential

Retrieve a specific mobile credential from the storage.

The verification result is returned based on the following sequence of verification steps, as per ISO/IEC 18013-5:2021:

  1. Device Key Validation:

    Ensures the device key cryptographic curve is supported by the SDK.

  2. Issuer Data Authentication:

    Executes the issuer's data authentication procedure defined in section 9.3.1 of ISO/IEC 18013-5:2021:

    • MSO Header Validation: Validates the certificate found in the MSO (Mobile Security Object) header.

    • Signer Certificate Verification: Verifies the Signer Certificate (as specified in Section 9.3.3 and Table B.3 of ISO/IEC 18013-5:2021) against the set of the trusted issuer certificates, currently stored by the SDK.

    • IssuerAuth Digital Signature Verification: Verifies the digital signature of the IssuerAuth structure.

    • Verify Value Digest: Ensures the integrity and correctness of the value digest.

    • ValidityInfo Structure Validation: Ensures all elements in the ValidityInfo structure meet the defined standards.

  3. DocType-Specific Validation:

    Performs additional validation steps specific to the credential's docType.

    For mDLs this includes :

    • Confirms the mDL signer's certificate maximum validity period is within limits (up to 457 days).

    • Ensures the mDL signer certificate has the correct ExtKeyUsage (ISO/IEC 18013-5:2021 B.1.4).

    • Confirms the mDL signer certificate set its key usage for digital signatures exclusively.

    • Verifies the mDL signer certificate was issued from the correct location.

Confirms the credential has not been revoked or suspended when the skipStatusCheck parameter is set to false.

The SDK retrieves and caches status list tokens as part of the credential status check. Each status list token contains the following parameters:

  • ttl (Time to Live): Recommended duration the relying party should use a token before retrieving a new one.

  • exp (Expiry): Absolute expiration time after which the token can no longer be used.

The SDK calculates a nextUpdateDate as the earlier of:

  • retrieval time + ttl

  • exp

Then based on the result:

  • If the current time is before nextUpdateDate, the SDK continues to use the cached token.

  • If the current time is after nextUpdateDate, it attempts to retrieve a new status list token.

Offline behavior:

  • If the device is offline and ttl has passed but exp has not, the cached token will still be used.

  • If exp has passed, the status will be returned as Unknown.

Currently the Holder SDK does not support forcing a status list token refresh.

Return

Stored mobile credential corresponding to the provided ID as an instance of MobileCredential, which includes both Personally Identifiable Information (PII) and the verification result.

Parameters

id

Unique ID of a mobile credential to be retrieved.

skipStatusCheck

Defines whether a revocation status check should be skipped. Defaults to false, indicating a status check will be performed. Network requests may be performed if set to false.

Throws

If the SDK API is called before the SDK is initialized.

If the MobileCredential is not found in the local storage.

If the credential is invalid.