Skip to content

Commit

Permalink
Merge branch 'RM-4211_key-shares-updates' into 'master'
Browse files Browse the repository at this point in the history
* add `x-cdoc2-auth-x5c` header parameter.
* Remove 'format: byte' for `nonce` and `x-auth-ticket`
* rename X-Auth-Ticket -\> x-cdoc2-auth-ticket to follow conventions in OAS spec

See merge request cdoc2/cdoc2-openapi!5
  • Loading branch information
jann0k committed Nov 27, 2024
2 parents a3e8331 + 8ed0bcd commit 853f373
Showing 5 changed files with 244 additions and 10 deletions.
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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:
<version>2.1.0</version>
<type>yaml</type>
</dependency>
<dependency>
<groupId>ee.cyber.cdoc2.openapi</groupId>
<artifactId>cdoc2-key-shares-openapi</artifactId>
<version>1.0.0</version>
<type>yaml</type>
</dependency>
```

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 `<id>` under `<server>`
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
```




5 changes: 4 additions & 1 deletion cdoc2-key-capsules-openapi.yaml
Original file line number Diff line number Diff line change
@@ -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:
169 changes: 169 additions & 0 deletions cdoc2-key-shares-openapi.yaml
Original file line number Diff line number Diff line change
@@ -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
10 changes: 7 additions & 3 deletions get-openapi-version.groovy
Original file line number Diff line number Diff line change
@@ -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)
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)
41 changes: 35 additions & 6 deletions pom.xml
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@
<modelVersion>4.0.0</modelVersion>

<groupId>ee.cyber.cdoc2</groupId>
<version>2.1.0</version>
<version>3.0.0</version>
<artifactId>cdoc2-openapi</artifactId>
<description>CDOC2 OpenApi specifications</description>
<packaging>pom</packaging>
@@ -68,8 +68,6 @@
</profile>
</profiles>

<dependencies></dependencies>

<build>
<plugins>
<plugin>
@@ -85,14 +83,13 @@
</dependencies>
<executions>
<execution>
<id>parse-info.version-from-cdoc2-key-capsules-openapi.yaml</id>
<id>parse-info.version-from-yaml-files</id>
<phase>initialize</phase>
<goals>
<goal>execute</goal>
</goals>
<configuration>
<properties>

<buildbasedir>${project.basedir}</buildbasedir>
</properties>
<!-- Path variables on Win are not encoded properly if included directly into pom.xml -->
@@ -133,7 +130,6 @@
<goal>install-file</goal>
</goals>
<configuration>

<file>${project.basedir}/cdoc2-key-capsules-openapi.yaml</file>
<groupId>ee.cyber.cdoc2.openapi</groupId>
<artifactId>cdoc2-key-capsules-openapi</artifactId>
@@ -142,6 +138,21 @@
<packaging>yaml</packaging>
</configuration>
</execution>
<execution>
<id>deploy-openapi-cdoc2-key-shares</id>
<phase>install</phase>
<goals>
<goal>install-file</goal>
</goals>
<configuration>
<file>${project.basedir}/cdoc2-key-shares-openapi.yaml</file>
<groupId>ee.cyber.cdoc2.openapi</groupId>
<artifactId>cdoc2-key-shares-openapi</artifactId>
<!-- cdoc2-key-shares-openapi.version value is set by groovy-maven-plugin, parsed from openapi file -->
<version>${cdoc2-key-shares-openapi.version}</version>
<packaging>yaml</packaging>
</configuration>
</execution>
</executions>
</plugin>

@@ -168,6 +179,24 @@
<url>${project.distributionManagement.repository.url}</url>
</configuration>
</execution>
<execution>
<id>deploy-openapi-cdoc2-key-shares</id>
<phase>deploy</phase>
<goals>
<goal>deploy-file</goal>
</goals>
<configuration>
<skip>false</skip>
<file>${project.basedir}/cdoc2-key-shares-openapi.yaml</file>
<groupId>ee.cyber.cdoc2.openapi</groupId>
<artifactId>cdoc2-key-shares-openapi</artifactId>
<!-- cdoc2-key-shares-openapi.version value is set by groovy-maven-plugin, parsed from openapi file -->
<version>${cdoc2-key-shares-openapi.version}</version>
<packaging>yaml</packaging>
<repositoryId>${project.distributionManagement.repository.id}</repositoryId>
<url>${project.distributionManagement.repository.url}</url>
</configuration>
</execution>
</executions>

<configuration>

0 comments on commit 853f373

Please sign in to comment.