Skip to main content

🆔 Creation of an mDoc

After initializing your DocumentStore and related components, you can proceed to create an mDoc (mobile Document) credential. This section guides you through creating a Document and generating a standards-compliant mDoc credential. The following code should go into the suspend fun init() in App.kt.

Creating a Document​

A Document represents an individual item created and managed by the DocumentStore.

  • Method: Use DocumentStore#createDocument to create a new document.
val document = documentStore.createDocument(
   displayName = "Erika's Driving License",
   typeDisplayName = "Utopia Driving License"
)

Creating an MdocCredential​

An MdocCredential represents a mobile credential, such as a Mobile Driving License (mDL), following the ISO/IEC 18013-5:2021 standard.

1. Prepare Timestamps​

Set up the credential's validity period and signing time:

val now = Clock.System.now()
val signedAt = now
val validFrom = now
val validUntil = now + 365.days

2. Generate IACA Certificate​

The IACA (Issuing Authority Certificate Authority) certificate is required for signing the Document Signing (DS) certificate.

val iacaKey = Crypto.createEcPrivateKey(EcCurve.P256)
val iacaCert = MdocUtil.generateIacaCertificate(
   iacaKey = iacaKey,
   subject = X500Name.fromName(name = "CN=Test IACA Key"),
   serial = ASN1Integer.fromRandom(numBits = 128),
   validFrom = validFrom,
   validUntil = validUntil,
   issuerAltNameUrl = "https://issuer.example.com",
   crlUrl = "https://issuer.example.com/crl"
)

We are currently generating a random IACA certificate. You can use multipazctl to generate your own certificates & keys. Refer here for the steps.

3. Generate Document Signing (DS) Certificate​

The DS certificate signs the mDoc credential.

val dsKey = Crypto.createEcPrivateKey(EcCurve.P256)
val dsCert = MdocUtil.generateDsCertificate(
   iacaCert = iacaCert,
   iacaKey = iacaKey,
   dsKey = dsKey.publicKey,
   subject = X500Name.fromName(name = "CN=Test DS Key"),
   serial = ASN1Integer.fromRandom(numBits = 128),
   validFrom = validFrom,
   validUntil = validUntil
)

4. Create the mDoc Credential​

Finally, use the document and generate certificates to create the mDoc credential.

val mdocCredential =
   DrivingLicense.getDocumentType().createMdocCredentialWithSampleData(
       document = document,
       secureArea = secureArea,
       createKeySettings = CreateKeySettings(
           algorithm = Algorithm.ESP256,
           nonce = "Challenge".encodeToByteString(),
           userAuthenticationRequired = true
       ),
       dsKey = dsKey,
       dsCertChain = X509CertChain(listOf(dsCert)),
       signedAt = signedAt,
       validFrom = validFrom,
       validUntil = validUntil,
   )

By following these steps, you can securely create and provision an mDoc credential, ready to be managed and used within your application.

Refer to this part for the implementation of the Creating an MdocCredential section of this guide.

Looking for a more realistic flow?

The example above uses helpful defaults for quick onboarding. If you're exploring how to construct credentials manually — including MSO creation, issuer namespaces, and authentication — check out this advanced sample created by a core contributor.