Skip to main content

Configure the system for ISO

Learn how to set up the system for the ISO mdoc format.

Implementation​

All mdocs have a DocType specifying the type of credential and one or more NameSpaces defining its data elements with unique identifiers (essentially the root-level claims objects). Though mdoc was developed for mDL (DocType: org.iso.18013.5.1.mDL), the format can be used for other kinds of mobile identification documents since other DocTypes can be specified, along with the format of the data elements and values therein. Documents can contain data elements from multiple namespaces.

For mdocs issued with Procivis One, the DocType is specified in the schemaId field during credential schema creation. The schemaType is mdoc.

Each data element in an mdoc (that is, each field of the credential) is individually encoded and included as a digest in the mobile security object (MSO), a separate structure which is signed by the issuer during issuance and included in the mdoc when sharing a proof with a verifier. Because the data elements are individually encoded, mdoc supports selective disclosure. The public key of the key pair used to sign the MSO is contained in the MSO.

If issuing mDLs (DocType: org.iso.18013.5.1.mDL), the data element portrait must be configured. See mDL portrait.

Configuring mdocs issuance and verification​

Certificate​

All mdocs require a signed Document Signer Certificate (DSC) certificate. The Certificate Authority (CA) certificate that signed the DSC is added to the configuration for both issuers and verifiers.

Even though mdocs do not use DIDs, Procivis One incorporates DID usage into mdocs issuance for internal workflow interoperability. External interoperability is not impacted.

The following is a high-level workflow of mdoc configuration with Procivis One.

  1. Generate a key pair using either ES256 or EDDSA.

  2. Get a DSC.

    • Use the Generate a Certificate Signing Request endpoint, referencing the key from (1) and passing issuer information such as common name, to create a CSR.

    • Submit the CSR to a CA that supports the mdl profle. If the CSR is validated, the CA returns a DSC.

    warning

    If the CA is signing with ECDSA, SHA256 must be used. The system does not support SHA384 or SHA512.

  3. Add the CA's certificate to the configuration of the MDL DID method.

    • params:
        private:
          iacaCertificate: <CA certificate here>

  4. Create a DID with the signed certificate from (2).

    • Use the Create a DID endpoint
    • Pass the key from (1)
    • Pass MDL as the method
    • For params, pass "certificate": "SIGNED_CERTIFICATE_HERE" with the certificate in PEM format

    → During did:mdl creation the system verifies that the certificate has been signed by the CA from (2) and contains the key from (1).

  5. Issue and verify mdocs using the DID from (4).

mDL portrait​

For the portrait data element of mDL credentials, as specified in ISO/IEC 18013-2:2020, Annex D, a separate datatype must be configured. Limit accepted files to JPEG and pass true for the public param encodeAsMdlPortrait.

Here's an example configuration:

MDL_PICTURE:
  display: 'datatype.mdlPicture'
  type: 'FILE'
  order: 402
  params:
    public:
      accept:
        - image/jpeg               // ** only JPEG is accepted **
      fileSize: 4194304
      showAs: IMAGE
      encodeAsMdlPortrait: true    // ** required **

Exchange protocol​

For configuring the exchange protocol for issuance, see Configure OID4VC for mdoc

mdoc validity​

While mdoc does not support revocation methods it does support expiration. The mdoc issuer sets when the validity period starts and when it stops. Since long validity periods with no possibility of revocation undermine trust, the mdoc specification expects short validity periods combined with an automatic update mechanism.

Here's an example: your state issues you a mobile driver's license. The MSO of this mDL says that it is valid for three days. As the third day approaches, your wallet sends a request to the issuing authority for a new MSO. The issuing authority's system automatically sends you a new MSO. Your mDL is still valid and the three day timer starts again.

So how does suspension work?

If the issuing authority decides to suspend your credential, their system stops sending you any new MSOs. After the three days of the latest received MSO has elapsed, your credential has expired and cannot be validated.

Setting validity periods​

Validity periods for issued mdocs are set in the configuration of the MDOC credential format. There are two relevant parameters:

  • msoExpiresIn: The length of validity from the time of issuance, in seconds. Each new credential and each new MSO will have be valid for this length of time.
  • msoExpectedUpdateIn: This sets when the system will respond to a wallet with a new MSO. This value should be shorter than the total length of validity.

Here's an example configuration:

MDOC:
  type: 'MDOC'
  display: 'format.mdoc'
  order: 4
  params:
    public:
      msoExpiresIn: 604800 # 7d in seconds
      msoExpectedUpdateIn: 86400 # 1d in seconds
      leeway: 60
      embedLayoutProperties: true

With this configuration, a newly issued mdoc would be valid for seven days. If the wallet requests a new MSO after one day, the system sends a new MSO and the timer starts over again. If the wallet sends a request only 23 hours after issuance, no new MSO would be sent. mdocs issued with Procivis One contain the optional expectedUpdate value, letting wallets know when they can request a new MSO.

If two different validity lengths are required for mdoc issuance, configure another instance of the MDOC format.

Suspending an mdoc​

During credential schema creation of mdocs, use the revocation method MDOC_MSO_UPDATE_SUSPENSION to enable suspension. When an mdoc credential is suspended via the suspension endpoint (Core and Desk), the system stops sending new MSOs.

Suspended mdocs can be reactived using the reactivate endpoint (Core and Desk). Upon reactivation, wallets can receive a new MSO.

info

When suspending an mdoc credential, the suspension will not take effect until the current Mobile Security Object (MSO) expires. The credential will be valid in wallets until the next MSO refresh cycle.

Holding an mdoc​

When holding an mdoc with Procivis One the system uses the expectedUpdate field of the credential to know when to request a new MSO.

If the MSO expires and no new MSO is available, the credential state changes to SUSPENDED until a new MSO is received.

expiry_date​

In addition to the validity contained in the MSO, mdocs can also have an expiry date as a data element. This is used for business logic and may or may not be requested by a verifier. By contrast, the MSO is always shared.