Issuing mdoc and mDL

This guide walks you through issuing an ISO mdoc credential with Procivis One.

1. Create a certificate identifier

You need a Document Signing Certificate (DSC) certificate to issue mdocs. The process varies slightly whether you are developing and testing or are ready to go in production.

1a. Development and testing

You can create the full chain of certificates needed to start issuing mdocs entirely in Procivis One.

1. Complete Create a self-signed root CA, making sure to do the following:

• Include an issuerAlternativeName in the call to create the CA identifier (required for mdoc CAs)

2. Complete Create a certificate using an internal CA, making sure to do the following:

• Pass MDL for the profile parameter
• Use the CA from (1) for certificateAuthority.identifierId

1b. Production

If you are not an acting root Certificate Authority and you want to issue mdocs in production, you must get your DCS signed by a qualified external party.

1. Complete Import a Certificate, making sure to do the following:

• When creating the CSR, pass MDL for the profile parameter
• Submit the CSR to a CA that supports SHA256 signatures and the MDL profile

2. Create a credential schema

To issue mdocs, create a credential schema that uses the mdoc credential format. Complete 2.1 Create a credential schema, making sure to set the following parameters:

1. Use formats to set mdoc and the DocType:

• Use MDOC for format, or your preferred instance of mdoc if you have customized your configuration
• Use schemaId to set the Doctype

POST /api/credential-schema/v2

{
  "formats": [
    {
      "format": "MDOC",
      "schemaId": "org.iso.18013.5.1.mDL"
    }
  ],
  ...
}

If you do not set a schemaId, the system will auto-generate the DocType. Here are some examples of externally-defined DocTypes you may want to issue:

Credential type	mdoc DocType
Standard mDL	org.iso.18013.5.1.mDL
eIDAS PIDs	eu.europa.ec.eudi.pid.1

The DocType you issue may be determined by the ecosystem in which you intend to operate, and correct entry is important for interoperability. You can also define your own DocType if there is no existing standard schema definition with which you need to interoperate.

2. Define your namespace(s)

In addition to the DocType, the mdoc standard uses a "namespace" to define the sets of claims you are issuing. Here are some namespace examples:

Credential type	mdoc DocType
Standard mDL	org.iso.18013.5.1
eIDAS PID	eu.europa.ec.eudi.pid.1
US mDL - AAMVA	org.iso.18013.5.1.aamva

How namespaces work

The standard mDL namespace includes claims like:

• family_name
• given_name
• height

Some implementations then add their own namespaces to define new data elements. The AAMVA implementation of mDL, for example, adds claims like:

• domestic_driving_privileges
• organ_donor
• veteran

You can include more than one namespace in an mdoc credential. If you issue an mDL with both the standard mDL namespace and the AAMVA namespace, an international verifier might want to only request data from the standard mDL namespace while a U.S.-based verifier may want to also request data from the AAMVA namespace.

Use mappings to map each claim to a namespace. Here's a technically complete call:

POST /api/credential-schema/v2

{
  "name": "example ISO schema",
  "allowRevocation": true, // Revocation is supported with Token Status List
  "formats": [
    {
      "format": "MDOC",
      "schemaId": "org.namespace.1" // Define the DocType
    }
  ],
  "claims": [
    {
      "key": "first_name",
      "datatype": "STRING",
      "required": true,
      "mappings": [
        {
          "format": "MDOC",
          "namespace": "org.namespace.1", // Map the claim to a namespace
          "technicalKey": "first_name"
        }
      ],
    },
    {
      "key": "last_name",
      "datatype": "STRING",
      "required": true,
      "mappings": [
        {
          "format": "MDOC",
          "namespace": "org.namespace.2", // You can map to multiple namespaces
          "technicalKey": "last_name"
        }
      ],
    },
    {
      "key": "portrait",
      "datatype": "MDL_PICTURE",
      "required": true,
      "mappings": [
        {
          "format": "MDOC",
          "namespace": "org.namespace.2", 
          "technicalKey": "portrait"
        }
      ]
    }
  ]
}

info

• If you are making an ISO mDL and including the mDL portrait claim, pass MDL_PICTURE for that claim's datatype. This ensures proper encoding according to ISO specifications.
• Suspension is not supported, in accordance with the ISO specification.

On creation, store the returned schema ID for later use during issuance.

3. Create and issue a credential

Using the schema created above, complete:

1. Creating a Credential

2. Sharing a Credential