DCAPI: Integrate ISO 18013-7 Annex C

Author: nodh

CHANGELOG.md

@@ -18,7 +18,7 @@ Release 7.0.0 (unreleased):
     - Fix disclosure of SD-JWT claims from foreign issuers: match disclosure digests against the originally serialized disclosures instead of re-serializing them, since digests are computed over the exact bytes (RFC 9901, section 4.2.3), e.g. failing for disclosures serialized with whitespace.
     - Extend `DCQLCredentialQueryMatchingResult` by case `AllMandatoryClaimsMatchingResult`
     - Consolidate interface of `OpenId4VpVerifier`: All clients should use `createAuthnRequest()`, so we deprecate methods `submitAuthnRequest()` or `createAuthnRequestAsSignedRequestObject()`
-    - Extract `DcApiVerifier` as a pendant to `OpenId4VpVerifier` which handles DCAPI requests only
+    - Extract `DcApiVerifier` as a pendant to `OpenId4VpVerifier` which handles DCAPI requests only, deprecating `Iso180137AnnexCVerifier`
     - Move `CreationOptions` and `CreatedRequest` to upper level (`at.asitplus.wallet.lib.openid`) instead of nesting in `OpenId4VpVerifier`
 - Verifier:
     - Add `NonceChallengeVerifier`, a thin `Verifier` wrapper that creates presentation challenges from a `NonceService` and verifies SD-JWT/VC-JWT presentations against the embedded challenge.

openid-data-classes/src/commonMain/kotlin/at/asitplus/openid/dcql/DCQLQueryToIsoDeviceRequest.kt

@@ -0,0 +1,34 @@
+package at.asitplus.openid.dcql
+
+import at.asitplus.iso.DeviceRequest
+import at.asitplus.iso.DocRequest
+import at.asitplus.iso.ItemsRequest
+import at.asitplus.iso.ItemsRequestList
+import at.asitplus.iso.SingleItemsRequest
+import at.asitplus.signum.indispensable.cosef.io.ByteStringWrapper
+
+/**
+ * Renders this DCQL query as an ISO 18013-5 [DeviceRequest],
+ * to be used for ISO/IEC 18013-7 Annex C flows over the W3C Digital Credentials API.
+ *
+ * All credential queries must be [DCQLIsoMdocCredentialQuery] with explicitly enumerated
+ * [DCQLIsoMdocCredentialQuery.claims]: DCQL's `claims == null` (requesting all claims)
+ * cannot be expressed in an ISO device request.
+ */
+fun DCQLQuery.toIso180137AnnexCDeviceRequest(): DeviceRequest = DeviceRequest(
+    version = "1.0",
+    docRequests = credentials.map { it.toDocRequest() }.toTypedArray(),
+)
+
+private fun DCQLCredentialQuery.toDocRequest(): DocRequest {
+    require(this is DCQLIsoMdocCredentialQuery) {
+        "Only mso_mdoc credential queries are supported for ISO 18013-7 Annex C, got $format"
+    }
+    val namespaces = requireNotNull(claims) {
+        "ISO device requests require explicitly enumerated claims"
+    }.groupBy(
+        keySelector = { it.namespace },
+        valueTransform = { SingleItemsRequest(it.claimName, it.intentToRetain ?: false) },
+    ).mapValues { (_, items) -> ItemsRequestList(items) }
+    return DocRequest(ByteStringWrapper(ItemsRequest(meta.doctypeValue, namespaces)))
+}

vck-openid/src/commonMain/kotlin/at/asitplus/wallet/lib/openid/AuthnResponseResult.kt

@@ -12,7 +12,7 @@ data class AuthnResponseResult(
     val idTokenValidationResult: KmmResult<IdToken>?,
     val vpTokenValidationResult: KmmResult<VpTokenValidationResult>?,
     val request: AuthenticationRequestParameters?,
-) {
+) : DcApiResponseResult() {
     val state
         get() = request?.state
 }

vck-openid/src/commonMain/kotlin/at/asitplus/wallet/lib/openid/CredentialPresentationRequestBuilder.kt

@@ -8,11 +8,6 @@ import at.asitplus.dif.FormatContainerSdJwt
 import at.asitplus.dif.FormatHolder
 import at.asitplus.dif.InputDescriptor
 import at.asitplus.dif.PresentationDefinition
-import at.asitplus.iso.DeviceRequest
-import at.asitplus.iso.DocRequest
-import at.asitplus.iso.ItemsRequest
-import at.asitplus.iso.ItemsRequestList
-import at.asitplus.iso.SingleItemsRequest
 import at.asitplus.openid.dcql.DCQLClaimsPathPointer
 import at.asitplus.openid.dcql.DCQLClaimsPathPointerSegment.NameSegment
 import at.asitplus.openid.dcql.DCQLClaimsQueryList
@@ -28,10 +23,10 @@ import at.asitplus.openid.dcql.DCQLJwtVcCredentialQuery
 import at.asitplus.openid.dcql.DCQLQuery
 import at.asitplus.openid.dcql.DCQLSdJwtCredentialMetadataAndValidityConstraints
 import at.asitplus.openid.dcql.DCQLSdJwtCredentialQuery
-import at.asitplus.signum.indispensable.cosef.io.ByteStringWrapper
 import at.asitplus.wallet.lib.RequestOptionsCredential
 import at.asitplus.wallet.lib.data.ConstantIndex.CredentialRepresentation.*
 import at.asitplus.wallet.lib.data.CredentialPresentationRequest
+import at.asitplus.wallet.lib.data.CredentialPresentationRequest.DCQLRequest
 import at.asitplus.wallet.lib.toIsoMdocClaimPath
 import com.benasher44.uuid.uuid4
 
@@ -66,8 +61,8 @@ data class CredentialPresentationRequestBuilder(
         ISO_MDOC -> FormatHolder(msoMdoc = FormatContainerJwt())
     }
 
-    fun toDCQLRequest(): CredentialPresentationRequest.DCQLRequest? {
-        return CredentialPresentationRequest.DCQLRequest(
+    fun toDCQLRequest(): DCQLRequest? {
+        return DCQLRequest(
             DCQLQuery(
                 credentials = DCQLCredentialQueryList(
                     credentials.mapNotNull {
@@ -80,26 +75,6 @@ data class CredentialPresentationRequestBuilder(
         )
     }
 
-    fun toIso180137AnnexCDeviceRequest() = credentials.map {
-        if (it.representation != ISO_MDOC) {
-            throw UnsupportedOperationException("Wrong representation: Only ISO MDoc is supported")
-        }
-        val docType = it.credentialScheme.isoDocType ?: throw IllegalStateException("Missing doc type")
-        val itemsRequestList = it.effectiveRequestedAttributePaths().map { reqAttr ->
-            val (namespace, claimName) = reqAttr.toIsoMdocClaimPath(it.credentialScheme)
-                .toIsoMdocNamespaceAndClaimName()
-            namespace to SingleItemsRequest(claimName, false)
-        }.groupBy(
-            keySelector = { (namespace, _) -> namespace },
-            valueTransform = { (_, itemRequest) -> itemRequest }
-        ).mapValues { (_, itemRequests) ->
-            ItemsRequestList(itemRequests)
-        }
-        DocRequest(ByteStringWrapper(ItemsRequest(docType, itemsRequestList)))
-    }.toTypedArray().let {
-        DeviceRequest("1.0", it)
-    }
-
     private fun RequestOptionsCredential.toQuery(): DCQLCredentialQuery? = when (representation) {
         PLAIN_JWT -> toJwtVcQuery()
         SD_JWT -> toSdJwtQuery()

vck-openid/src/commonMain/kotlin/at/asitplus/wallet/lib/openid/DcApiCreationOptions.kt

@@ -19,5 +19,11 @@ sealed class DcApiCreationOptions {
      */
     data object OpenId4VpSigned : DcApiCreationOptions()
 
-    // TODO: OpenId4VpMultiSigned (`openid4vp-v1-multisigned`) and Iso18013AnnexC (`org-iso-mdoc`)
+    /**
+     * ISO 18013-7 Annex C request, i.e. protocol `org-iso-mdoc`,
+     * see [at.asitplus.dcapi.request.verifier.DigitalCredentialGetRequest.IsoMdoc].
+     */
+    data object Iso180137AnnexC : DcApiCreationOptions()
+
+    // TODO: OpenId4VpMultiSigned (`openid4vp-v1-multisigned`)
 }

vck-openid/src/commonMain/kotlin/at/asitplus/wallet/lib/openid/DcApiVerifier.kt

@@ -5,23 +5,27 @@ import at.asitplus.catching
 import at.asitplus.dcapi.DCAPIHandover
 import at.asitplus.dcapi.DCAPIHandover.Companion.TYPE_DCAPI
 import at.asitplus.dcapi.DCAPIInfo
+import at.asitplus.dcapi.DCAPIResponse
 import at.asitplus.dcapi.DigitalCredentialInterface
 import at.asitplus.dcapi.IsoMdocResponse
 import at.asitplus.dcapi.OpenID4VPDCAPIHandoverInfo
 import at.asitplus.dcapi.OpenId4VpResponse
 import at.asitplus.dcapi.SessionTranscriptContentHashable
+import at.asitplus.dcapi.request.IsoMdocRequest
 import at.asitplus.dcapi.request.verifier.CredentialRequestOptions
-import at.asitplus.dcapi.request.verifier.DigitalCredentialGetRequest
+import at.asitplus.dcapi.request.verifier.DigitalCredentialGetRequest.*
+import at.asitplus.dcapi.request.verifier.DigitalCredentialGetRequest.OpenId4Vp.SignedDataElement
 import at.asitplus.dif.ClaimFormat
 import at.asitplus.dif.DifInputDescriptor
 import at.asitplus.dif.FormatContainerJwt
 import at.asitplus.dif.FormatContainerSdJwt
 import at.asitplus.dif.PresentationSubmissionDescriptor
 import at.asitplus.iso.DeviceResponse
+import at.asitplus.iso.EncryptionInfo
+import at.asitplus.iso.EncryptionParameters
 import at.asitplus.iso.SessionTranscript
 import at.asitplus.iso.serializeOrigin
 import at.asitplus.iso.sha256
-import at.asitplus.jsonpath.JsonPath
 import at.asitplus.openid.AuthenticationRequestParameters
 import at.asitplus.openid.CredentialFormatEnum
 import at.asitplus.openid.IdTokenType
@@ -36,10 +40,14 @@ import at.asitplus.openid.VpFormatsSupported
 import at.asitplus.openid.dcql.DCQLCredentialQueryIdentifier
 import at.asitplus.openid.dcql.DCQLQuery
 import at.asitplus.openid.dcql.DCQLQueryResponse
+import at.asitplus.openid.dcql.toIso180137AnnexCDeviceRequest
 import at.asitplus.rfc6749OAuth2AuthorizationFramework.ResponseType
+import at.asitplus.signum.indispensable.CryptoPrivateKey
+import at.asitplus.signum.indispensable.SecretExposure
 import at.asitplus.signum.indispensable.SignatureAlgorithm
 import at.asitplus.signum.indispensable.cosef.io.coseCompliantSerializer
 import at.asitplus.signum.indispensable.cosef.toCoseAlgorithm
+import at.asitplus.signum.indispensable.cosef.toCoseKey
 import at.asitplus.signum.indispensable.io.Base64UrlStrict
 import at.asitplus.signum.indispensable.josef.JsonWebKey
 import at.asitplus.signum.indispensable.josef.JsonWebKeySet
@@ -61,6 +69,7 @@ import at.asitplus.wallet.lib.cbor.VerifyCoseSignatureWithKey
 import at.asitplus.wallet.lib.cbor.VerifyCoseSignatureWithKeyFun
 import at.asitplus.wallet.lib.data.CredentialPresentationRequest.DCQLRequest
 import at.asitplus.wallet.lib.data.CredentialPresentationRequest.PresentationExchangeRequest
+import at.asitplus.wallet.lib.data.IsoDocumentParsed
 import at.asitplus.wallet.lib.data.VerifiablePresentationJws
 import at.asitplus.wallet.lib.data.toBase64UrlJsonString
 import at.asitplus.wallet.lib.extensions.sessionTranscriptThumbprint
@@ -76,6 +85,7 @@ import at.asitplus.wallet.lib.procedures.dcql.DCQLQueryAdapter
 import at.asitplus.wallet.lib.utils.DefaultMapStore
 import at.asitplus.wallet.lib.utils.MapStore
 import io.github.aakira.napier.Napier
+import io.ktor.utils.io.core.*
 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray
 import kotlinx.serialization.decodeFromByteArray
 import kotlinx.serialization.encodeToByteArray
@@ -124,8 +134,15 @@ class DcApiVerifier @JvmOverloads constructor(
     override val nonceService: NonceService = DefaultNonceService(),
     /** Used to store issued authn requests to verify the authn response to it */
     private val stateToAuthnRequestStore: MapStore<String, AuthenticationRequestParameters> = DefaultMapStore(),
+    /** Used to store issued requests to verify the response to it */
+    private val stateToIsoMdocRequestStore: MapStore<String, IsoMdocRequest> = DefaultMapStore(),
     /** Algorithms supported to decrypt responses from wallets, for [metadataWithEncryption]. */
     private val supportedJweEncryptionAlgorithms: Set<JweEncryption> = JweEncryption.entries.toSet(),
+    /**
+     * Workaround until signum is ready. Required for ISO 18013-7 Annex decryption.
+     * Parameters: Serialized ephemeral key, cipher text, decryption key, encoded session transcript
+     */
+    private val decryptHpke: (suspend (ByteArray, ByteArray, CryptoPrivateKey.EC.WithPublicKey, ByteArray) -> ByteArray)? = null,
 ) : AbstractMdocVerifier() {
 
     private val nonceAwareVerifier = NonceChallengeVerifier(
@@ -200,16 +217,20 @@ class DcApiVerifier @JvmOverloads constructor(
         CredentialRequestOptions.create(
             listOf(
                 when (creationOptions) {
-                    is DcApiCreationOptions.OpenId4VpUnsigned -> DigitalCredentialGetRequest.OpenId4VpUnsigned(
+                    is DcApiCreationOptions.OpenId4VpUnsigned -> OpenId4VpUnsigned(
                         // client_id MUST be omitted in unsigned requests, per OpenID4VP 1.0 Appendix A.3.1
                         createPlainAuthnRequest(requestOptions.copy(populateClientId = false))
                     )
 
-                    is DcApiCreationOptions.OpenId4VpSigned -> DigitalCredentialGetRequest.OpenId4VpSigned(
-                        DigitalCredentialGetRequest.OpenId4Vp.SignedDataElement(
+                    is DcApiCreationOptions.OpenId4VpSigned -> OpenId4VpSigned(
+                        SignedDataElement(
                             createSignedRequestObject(requestOptions).getOrThrow().jws
                         )
                     )
+
+                    DcApiCreationOptions.Iso180137AnnexC -> IsoMdoc(
+                        createIsoMdocRequest(requestOptions)
+                    )
                 }
             )
         )
@@ -241,6 +262,21 @@ class DcApiVerifier @JvmOverloads constructor(
             storeAuthnRequest(it, requestOptions.state)
         }
 
+    private suspend fun createIsoMdocRequest(
+        requestOptions: OpenId4VpRequestOptions,
+    ): IsoMdocRequest {
+        val deviceRequest = ((requestOptions.presentationRequest as? DCQLRequest)?.dcqlQuery
+            ?: throw IllegalArgumentException("ISO 18013-7 Annex C requires a DCQL presentation request"))
+            .toIso180137AnnexCDeviceRequest()
+
+        val encryptionParameters = EncryptionParameters(
+            nonceService.provideNonce().toByteArray(),
+            decryptionKeyMaterial.publicKey.toCoseKey().getOrThrow()
+        )
+        return IsoMdocRequest(deviceRequest, EncryptionInfo(TYPE_DCAPI, encryptionParameters))
+            .also { stateToIsoMdocRequestStore.put(requestOptions.state, it) }
+    }
+
     private suspend fun OpenId4VpRequestOptions.toAuthnRequest(): AuthenticationRequestParameters =
         AuthenticationRequestParameters(
             responseType = responseType,
@@ -311,7 +347,7 @@ class DcApiVerifier @JvmOverloads constructor(
     suspend fun validateAuthnResponse(
         input: String,
         externalId: String,
-    ): KmmResult<AuthnResponseResult> = catching {
+    ): KmmResult<DcApiResponseResult> = catching {
         validateAuthnResponse(
             input = joseCompliantSerializer.decodeFromString<DigitalCredentialInterface>(input),
             externalId = externalId
@@ -326,9 +362,14 @@ class DcApiVerifier @JvmOverloads constructor(
     suspend fun validateAuthnResponse(
         input: DigitalCredentialInterface,
         externalId: String,
-    ): KmmResult<AuthnResponseResult> = catching {
+    ): KmmResult<DcApiResponseResult> = catching {
         when (input) {
-            is IsoMdocResponse -> TODO()
+            is IsoMdocResponse -> validateResponse(
+                receivedData = input.data,
+                externalId = externalId,
+                expectedOrigin = "TODO"
+            ).getOrThrow()
+
             else -> validateAuthnResponse(
                 input = responseParser.parseAuthnResponse(input as OpenId4VpResponse),
                 externalId = externalId
@@ -375,6 +416,46 @@ class DcApiVerifier @JvmOverloads constructor(
         }
     }
 
+    @OptIn(SecretExposure::class)
+    suspend fun validateResponse(
+        receivedData: DCAPIResponse,
+        externalId: String,
+        expectedOrigin: String
+    ): KmmResult<Iso180137AnnexCWrapper> = catching {
+        val isoMdocRequest = stateToIsoMdocRequestStore.get(externalId)!!
+        val privateKey = decryptionKeyMaterial.exportPrivateKey().getOrThrow()
+                as? CryptoPrivateKey.EC.WithPublicKey
+            ?: throw IllegalStateException("Expected EC private key")
+
+        val encryptedResponseData = receivedData.response.encryptedResponseData
+        val serializedOrigin = expectedOrigin.serializeOrigin()
+            ?: throw IllegalStateException("Expected origin invalid")
+
+        val sessionTranscript = createDcApiSessionTranscriptAnnexC(
+            DCAPIInfo(
+                encryptionInfo = isoMdocRequest.encryptionInfo,
+                serializedOrigin = serializedOrigin,
+            )
+        )
+        val encodedSessionTranscript = coseCompliantSerializer.encodeToByteArray(sessionTranscript)
+        val encodedDeviceResponse = decryptHpke!!(
+            encryptedResponseData.enc,
+            encryptedResponseData.cipherText,
+            privateKey,
+            encodedSessionTranscript
+        )
+        val deviceResponse = coseCompliantSerializer.decodeFromByteArray<DeviceResponse>(encodedDeviceResponse)
+
+        Iso180137AnnexCWrapper(
+            verifier.verifyPresentationIsoMdoc(
+                input = deviceResponse,
+                verifyDocument = verifyDocument(
+                    sessionTranscript = sessionTranscript
+                )
+            ).getOrThrow().documents
+        )
+    }
+
     private fun AuthnResponseResult.isFullyValid(): Boolean =
         idTokenValidationResult?.isFailure != true &&
                 vpTokenValidationResult?.isFailure != true &&
@@ -416,35 +497,13 @@ class DcApiVerifier @JvmOverloads constructor(
         val vpToken = responseParameters.parameters.vpToken
             ?: throw IllegalArgumentException("vp_token not present in ${responseParameters.parameters}")
         val clientIdRequired = responseParameters.clientIdRequired
-
         val originalResponseParameters = responseParameters.originalResponseParameters
-
-        (originalResponseParameters as? ResponseParametersFrom.DcApi)?.let {
-            authnRequest.verifyExpectedOrigin(it.origin)
+        require(originalResponseParameters is ResponseParametersFrom.DcApi) {
+            "Unsupported response parameters: $originalResponseParameters"
         }
+        authnRequest.verifyExpectedOrigin(originalResponseParameters.origin)
 
-        authnRequest.presentationDefinition?.let {
-            val presentationSubmission = responseParameters.parameters.presentationSubmission?.descriptorMap
-                ?: throw IllegalArgumentException("Presentation Exchange need to present a presentation submission.")
-
-            val presentation = presentationSubmission.associate { descriptor ->
-                descriptor.id to verifyPresentationResult(
-                    claimFormat = descriptor.format,
-                    relatedPresentation = descriptor.relatedPresentation(vpToken),
-                    expectedNonce = expectedNonce,
-                    input = responseParameters,
-                    clientId = authnRequest.clientId,
-                    responseUrl = authnRequest.responseUrl ?: authnRequest.redirectUrlExtracted,
-                    transactionData = authnRequest.transactionData,
-                    clientIdRequired = clientIdRequired,
-                    origin = (originalResponseParameters as? ResponseParametersFrom.DcApi)?.origin,
-                )
-            }
-
-            VpTokenValidationResultPresentationExchange(
-                inputDescriptorResponseValidations = presentation,
-            )
-        } ?: authnRequest.dcqlQuery?.let { query ->
+        authnRequest.dcqlQuery?.let { query ->
             val presentation = vpToken.jsonObject.mapKeys {
                 DCQLCredentialQueryIdentifier(it.key)
             }.mapValues { (credentialQueryId, relatedPresentation) ->
@@ -462,7 +521,7 @@ class DcApiVerifier @JvmOverloads constructor(
                             ?: authnRequest.redirectUrlExtracted,
                         transactionData = authnRequest.transactionData,
                         clientIdRequired = clientIdRequired,
-                        origin = (originalResponseParameters as? ResponseParametersFrom.DcApi)?.origin,
+                        origin = originalResponseParameters.origin,
                         requireCryptographicHolderBinding = query.credentialQuery(credentialQueryId)?.requireCryptographicHolderBinding,
                     )
                 }
@@ -490,9 +549,6 @@ class DcApiVerifier @JvmOverloads constructor(
     private fun DCQLQuery.credentialQuery(id: DCQLCredentialQueryIdentifier) =
         credentials.associateBy { it.id }[id]
 
-    private fun PresentationSubmissionDescriptor.relatedPresentation(vpToken: JsonElement) =
-        JsonPath(cumulativeJsonPath).query(vpToken).first().value
-
     private fun CredentialFormatEnum.toClaimFormat(): ClaimFormat = when (this) {
         CredentialFormatEnum.JWT_VC -> ClaimFormat.JWT_VP
         CredentialFormatEnum.DC_SD_JWT -> ClaimFormat.SD_JWT
@@ -648,3 +704,9 @@ private val PresentationSubmissionDescriptor.cumulativeJsonPath: String
         }
         return cummulativeJsonPath
     }
+
+sealed class DcApiResponseResult {
+
+}
+
+data class Iso180137AnnexCWrapper(val documents: Collection<IsoDocumentParsed>) : DcApiResponseResult()