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 iacaCert = X509Cert.fromPem(
    """
        -----BEGIN CERTIFICATE-----
        MIICYzCCAemgAwIBAgIQ36kOae8cfvOqQ+mO4YhnpDAKBggqhkjOPQQDAzAuMQswCQYDVQQGDAJV
        UzEfMB0GA1UEAwwWT1dGIE11bHRpcGF6IFRFU1QgSUFDQTAeFw0yNTA3MjQxMTE3MTlaFw0zMDA3
        MjQxMTE3MTlaMC4xCzAJBgNVBAYMAlVTMR8wHQYDVQQDDBZPV0YgTXVsdGlwYXogVEVTVCBJQUNB
        MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEQQJf9BH+fJytVI4K4nQvHJAfzapvuT6jo+19fo+o9+zV
        PFnOYtsbPXB5sPeuMMv5ZkQGmn9yWCgpbZHAS2pJ/eJXAcLp9uH8BGo6pYhkPomx9cwgMX0YUXoB
        4wiO6w9eo4HLMIHIMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEAMC0GA1UdEgQm
        MCSGImh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuY29tL3dlYnNpdGUwMwYDVR0fBCwwKjAooCagJIYi
        aHR0cHM6Ly9pc3N1ZXIuZXhhbXBsZS5jb20vY3JsLmNybDAdBgNVHQ4EFgQUPbetw5QkxGKjazN0
        qI9YfaexD+0wHwYDVR0jBBgwFoAUPbetw5QkxGKjazN0qI9YfaexD+0wCgYIKoZIzj0EAwMDaAAw
        ZQIxAKizj2YexKf1+CTBCOV4ehyiUU5MSi9iPScW32+halSCVUtbmW63fpG+37obLGivegIwb38g
        xhIRxDdIk1CBVsqANCFUvdBuSoORRV5928xo/B9he5ZFyb8b6UauJS70AMD8
        -----END CERTIFICATE-----
    """.trimIndent()

val iacaKey = EcPrivateKey.fromPem(
    """
        -----BEGIN PRIVATE KEY-----
        MFcCAQAwEAYHKoZIzj0CAQYFK4EEACIEQDA+AgEBBDBEPQnb6xr3p0XKGucrf3iVI/sDF2fc55vs
        T31kxam8x8ocKu4ETouTZM+DZKu0cD+gBwYFK4EEACI=
        -----END PRIVATE KEY-----
    """.trimIndent(),
    iacaCert.ecPublicKey
)

We are embedding IACA certificate & key into the code right now. In a production environment you'll them load from a sever.

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 MdocCredential creation code for the complete example.

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.