From 8ed0bcde4d1bb8df1c6388a4fb4b6bc570479b3a Mon Sep 17 00:00:00 2001 From: Janno Kusman Date: Wed, 27 Nov 2024 10:28:49 +0200 Subject: [PATCH] RM-4211: add x-cdoc2-auth-x5c header parameter and update nonce format --- README.md | 29 ++++++ cdoc2-key-capsules-openapi.yaml | 5 +- cdoc2-key-shares-openapi.yaml | 169 ++++++++++++++++++++++++++++++++ get-openapi-version.groovy | 10 +- pom.xml | 41 ++++++-- 5 files changed, 244 insertions(+), 10 deletions(-) create mode 100644 cdoc2-key-shares-openapi.yaml diff --git a/README.md b/README.md index 2f80bf3..a11de78 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Contains OpenAPI specifications for [CDOC2 project](https://open-eid.github.io/C Used for code generation by: * https://github.com/open-eid/cdoc2-java-ref-impl * https://github.com/open-eid/cdoc2-capsule-server +* https://github.com/open-eid/cdoc2-shares-server (WIP) ## Java @@ -58,11 +59,18 @@ Or from Maven pom.xml: 2.1.0 yaml + + ee.cyber.cdoc2.openapi + cdoc2-key-shares-openapi + 1.0.0 + yaml + ``` Copy into project directory: ```bash mvn dependency::copy -Dartifact=ee.cyber.cdoc2.openapi:cdoc2-key-capsules-openapi:2.1.0:yaml -DoutputDirectory=./target/openapi +mvn dependency::copy -Dartifact=ee.cyber.cdoc2.openapi:cdoc2-key-shares-openapi:1.0.0:yaml -DoutputDirectory=./target/openapi ``` ### Usage from Java Maven projects for code generation @@ -101,6 +109,8 @@ where `project.distributionManagement.repository.id` is `` under `` In most cases, this parameter will be required for authentication. Or use maven deploy:deploy-file directly to deploy single file: + +cdoc2-key-capsules: ``` mvn deploy:deploy-file \ -DrepositoryId=github \ @@ -112,13 +122,32 @@ mvn deploy:deploy-file \ -DartifactId=cdoc2-key-capsules-openapi \ -Dmaven.deploy.file.skip=false ``` + +cdoc2-key-shares: +``` +mvn deploy:deploy-file \ +-DrepositoryId=github \ +-Durl=https://maven.pkg.github.com/open-eid/cdoc2-openapi \ +-Dfile=cdoc2-openapi/cdoc2-key-shares-openapi.yaml \ +-Dversion=1.0.0 \ +-Dpackaging=yaml \ +-DgroupId=ee.cyber.cdoc2.openapi \ +-DartifactId=cdoc2-key-shares-openapi \ +-Dmaven.deploy.file.skip=false +``` Refer: https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html ## Delete OpenApi package from local Maven repository +cdoc2-key-capsules: ``` mvn dependency:purge-local-repository -DmanualInclude=ee.cyber.cdoc2.openapi:cdoc2-key-capsules-openapi ``` +cdoc2-key-shares: +``` +mvn dependency:purge-local-repository -DmanualInclude=ee.cyber.cdoc2.openapi:cdoc2-key-shares-openapi +``` + diff --git a/cdoc2-key-capsules-openapi.yaml b/cdoc2-key-capsules-openapi.yaml index 4ffd2ea..2a4f873 100644 --- a/cdoc2-key-capsules-openapi.yaml +++ b/cdoc2-key-capsules-openapi.yaml @@ -7,9 +7,10 @@ info: description: API for exchanging CDOC2 ephemeral key material in key capsules servers: - url: 'https://localhost:8443' - description: no auth (for creating key capsules) + description: no auth (for creating key capsules). Regular TLS (no mutual TLS required). - url: 'https://localhost:8444' description: mutual TLS authentication (for retrieving key capsules) + paths: '/key-capsules/{transactionId}': get: @@ -48,6 +49,7 @@ paths: operationId: getCapsuleByTransactionId security: - mutualTLS: [] + /key-capsules: post: summary: Add Key Capsule @@ -81,6 +83,7 @@ paths: security: [] tags: - cdoc2-key-capsules + components: schemas: Capsule: diff --git a/cdoc2-key-shares-openapi.yaml b/cdoc2-key-shares-openapi.yaml new file mode 100644 index 0000000..f8368b2 --- /dev/null +++ b/cdoc2-key-shares-openapi.yaml @@ -0,0 +1,169 @@ +openapi: 3.0.3 +info: + contact: + url: http://ria.ee + title: cdoc2-key-shares + version: 1.0.1-draft + description: API for exchanging CDOC2 key material shares +servers: + - url: 'https://localhost:8443' + description: Regular TLS (no mutual TLS required). + +paths: + '/key-shares/{shareId}': + get: + summary: Get key share for shareId + description: Get key share for shareId + tags: + - cdoc2-key-shares + operationId: getKeyShareByShareId + parameters: + - name: shareId + in: path + schema: + type: string + minLength: 18 + maxLength: 34 + required: true + - name: x-cdoc2-auth-ticket + in: header + schema: + type: string + required: true + description: | + SDJWT [Auth ticket WIP](https://gitlab.ext.cyber.ee/cdoc2/cdoc2-documentation/-/blob/RM-2776-authentication-protocol/cdoc2-system-docs/docs/03_system_architecture/ch05_ID_authentication_protocol.md?ref_type=heads#verifying-sd-jwt-verifying-authentication-ticket) + - name: x-cdoc2-auth-x5c + in: header + schema: + type: string + required: true + description: | + PEM encoded X509 certificate (without newlines) that was used to sign X-Cdoc2-Auth-Ticket. + Certificate holders identify is specified in Subject "serialnumber" field. This must match to + "kid" in "x-cdoc2-auth-ticket" header. Example certificate subject: + 'serialNumber = PNOEE-30303039914, GN = OK, SN = TESTNUMBER, CN = "TESTNUMBER,OK", C = EE' + Certificate full structure is defined in + [Certificate and OCSP Profile for Smart-ID](https://www.skidsolutions.eu/wp-content/uploads/2024/10/SK-CPR-SMART-ID-EN-v4_7-20241127.pdf) + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/KeyShare' + '400': + description: 'Bad request. Client error.' + '401': + description: 'Unauthorized. No correct auth headers' + '404': + description: 'Not Found. 404 is also returned, when recipient id in record does not match user id in auth-ticket' + + + '/key-shares': + post: + summary: Add Key Share + description: Save a key share and generate share id using secure random. Generated share is returned in Location header + operationId: createKeyShare + responses: + '201': + description: Created + headers: + Location: + schema: + type: string + example: /key-shares/9a7c3717d21f5cf19d18fa4fa5adee21 + description: 'URI of created resource. ShareId can be extracted from URI as it follows pattern /key-shares/{shareId}' + '400': + description: 'Bad request. Client error.' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/KeyShare' + tags: + - cdoc2-key-shares + + '/key-shares/{shareId}/nonce': + post: + description: | + Create server nonce for authentication signature. + operationId: createNonce + parameters: + - name: shareId + in: path + schema: + type: string + minLength: 18 + maxLength: 34 + required: true + responses: + '200': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/NonceResponse' + '400': + description: 'Bad request. Client error.' + '403': + description: 'Authentication failed' + '404': + description: 'Not Found. (shareId)' + requestBody: + required: false + description: Always empty (OAS doesn't allow post without body, so optional body is defined here) + content: + application/json: + schema: #empty request body + type: object + nullable: true + tags: + - cdoc2-key-shares + +components: + schemas: + KeyShare: + title: Key Share + type: object + properties: + share: + type: string + format: byte + minLength: 32 + maxLength: 128 + description: Key Share. Binary format is yet to be defined [#RM-55912](https://rm-int.cyber.ee/ito/issues/55912) + recipient: + type: string + minLength: 12 + maxLength: 32 + description: | + Recipient who can download this share. ETSI319412-1. Example "etsi/PNOEE-48010010101". + In future might support other formats + [etsi/:semantics-identifier](https://github.com/SK-EID/smart-id-documentation/blob/v2/README.md#2322-etsisemantics-identifier) + required: + - share + - recipient + + NonceResponse: + title: Nonce response + type: object + properties: + nonce: + type: string + minLength: 12 + maxLength: 16 + description: 'server nonce for subsequent authentication' + required: + - nonce + + securitySchemes: + bearerAuth: # for /key-shares endpoints, long-term token + type: http + scheme: bearer + basicAuth: # temporary solution for initial functionality of /key-shares endpoints + type: http + scheme: basic + +tags: + - name: cdoc2-key-shares diff --git a/get-openapi-version.groovy b/get-openapi-version.groovy index 173c3fb..e6bc148 100644 --- a/get-openapi-version.groovy +++ b/get-openapi-version.groovy @@ -1,6 +1,10 @@ import org.yaml.snakeyaml.Yaml println 'buildbasedir: ' + properties['buildbasedir'] def yaml = new Yaml() -def openapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-capsules-openapi.yaml').text) -println "cdoc2-key-capsules-openapi.version: ${openapi.info.version}" -project.getProperties().setProperty('cdoc2-key-capsules-openapi.version', openapi.info.version) \ No newline at end of file +def keyCapsuleOpenapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-capsules-openapi.yaml').text) +println "cdoc2-key-capsules-openapi.version: ${keyCapsuleOpenapi.info.version}" +project.getProperties().setProperty('cdoc2-key-capsules-openapi.version', keyCapsuleOpenapi.info.version) + +def keySharesOpenapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-shares-openapi.yaml').text) +println "cdoc2-key-shares-openapi.version: ${keySharesOpenapi.info.version}" +project.getProperties().setProperty('cdoc2-key-shares-openapi.version', keySharesOpenapi.info.version) \ No newline at end of file diff --git a/pom.xml b/pom.xml index d25e3b0..12059f0 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 ee.cyber.cdoc2 - 2.1.0 + 3.0.0 cdoc2-openapi CDOC2 OpenApi specifications pom @@ -68,8 +68,6 @@ - - @@ -85,14 +83,13 @@ - parse-info.version-from-cdoc2-key-capsules-openapi.yaml + parse-info.version-from-yaml-files initialize execute - ${project.basedir} @@ -133,7 +130,6 @@ install-file - ${project.basedir}/cdoc2-key-capsules-openapi.yaml ee.cyber.cdoc2.openapi cdoc2-key-capsules-openapi @@ -142,6 +138,21 @@ yaml + + deploy-openapi-cdoc2-key-shares + install + + install-file + + + ${project.basedir}/cdoc2-key-shares-openapi.yaml + ee.cyber.cdoc2.openapi + cdoc2-key-shares-openapi + + ${cdoc2-key-shares-openapi.version} + yaml + + @@ -168,6 +179,24 @@ ${project.distributionManagement.repository.url} + + deploy-openapi-cdoc2-key-shares + deploy + + deploy-file + + + false + ${project.basedir}/cdoc2-key-shares-openapi.yaml + ee.cyber.cdoc2.openapi + cdoc2-key-shares-openapi + + ${cdoc2-key-shares-openapi.version} + yaml + ${project.distributionManagement.repository.id} + ${project.distributionManagement.repository.url} + +