Skip to content

Commit 853f373

Browse files
jann0kjann0k
committed
Merge branch 'RM-4211_key-shares-updates' into 'master'
* 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
2 parents a3e8331 + 8ed0bcd commit 853f373

File tree

5 files changed

+244
-10
lines changed

5 files changed

+244
-10
lines changed

‎README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Contains OpenAPI specifications for [CDOC2 project](https://open-eid.github.io/C
55
Used for code generation by:
66
* https://github.com/open-eid/cdoc2-java-ref-impl
77
* https://github.com/open-eid/cdoc2-capsule-server
8+
* https://github.com/open-eid/cdoc2-shares-server (WIP)
89

910
## Java
1011

@@ -58,11 +59,18 @@ Or from Maven pom.xml:
5859
<version>2.1.0</version>
5960
<type>yaml</type>
6061
</dependency>
62+
<dependency>
63+
<groupId>ee.cyber.cdoc2.openapi</groupId>
64+
<artifactId>cdoc2-key-shares-openapi</artifactId>
65+
<version>1.0.0</version>
66+
<type>yaml</type>
67+
</dependency>
6168
```
6269

6370
Copy into project directory:
6471
```bash
6572
mvn dependency::copy -Dartifact=ee.cyber.cdoc2.openapi:cdoc2-key-capsules-openapi:2.1.0:yaml -DoutputDirectory=./target/openapi
73+
mvn dependency::copy -Dartifact=ee.cyber.cdoc2.openapi:cdoc2-key-shares-openapi:1.0.0:yaml -DoutputDirectory=./target/openapi
6674
```
6775

6876
### Usage from Java Maven projects for code generation
@@ -101,6 +109,8 @@ where `project.distributionManagement.repository.id` is `<id>` under `<server>`
101109
In most cases, this parameter will be required for authentication.
102110

103111
Or use maven deploy:deploy-file directly to deploy single file:
112+
113+
cdoc2-key-capsules:
104114
```
105115
mvn deploy:deploy-file \
106116
-DrepositoryId=github \
@@ -112,13 +122,32 @@ mvn deploy:deploy-file \
112122
-DartifactId=cdoc2-key-capsules-openapi \
113123
-Dmaven.deploy.file.skip=false
114124
```
125+
126+
cdoc2-key-shares:
127+
```
128+
mvn deploy:deploy-file \
129+
-DrepositoryId=github \
130+
-Durl=https://maven.pkg.github.com/open-eid/cdoc2-openapi \
131+
-Dfile=cdoc2-openapi/cdoc2-key-shares-openapi.yaml \
132+
-Dversion=1.0.0 \
133+
-Dpackaging=yaml \
134+
-DgroupId=ee.cyber.cdoc2.openapi \
135+
-DartifactId=cdoc2-key-shares-openapi \
136+
-Dmaven.deploy.file.skip=false
137+
```
115138
Refer: https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html
116139

117140
## Delete OpenApi package from local Maven repository
141+
cdoc2-key-capsules:
118142
```
119143
mvn dependency:purge-local-repository -DmanualInclude=ee.cyber.cdoc2.openapi:cdoc2-key-capsules-openapi
120144
```
121145

146+
cdoc2-key-shares:
147+
```
148+
mvn dependency:purge-local-repository -DmanualInclude=ee.cyber.cdoc2.openapi:cdoc2-key-shares-openapi
149+
```
150+
122151

123152

124153

‎cdoc2-key-capsules-openapi.yaml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ info:
77
description: API for exchanging CDOC2 ephemeral key material in key capsules
88
servers:
99
- url: 'https://localhost:8443'
10-
description: no auth (for creating key capsules)
10+
description: no auth (for creating key capsules). Regular TLS (no mutual TLS required).
1111
- url: 'https://localhost:8444'
1212
description: mutual TLS authentication (for retrieving key capsules)
13+
1314
paths:
1415
'/key-capsules/{transactionId}':
1516
get:
@@ -48,6 +49,7 @@ paths:
4849
operationId: getCapsuleByTransactionId
4950
security:
5051
- mutualTLS: []
52+
5153
/key-capsules:
5254
post:
5355
summary: Add Key Capsule
@@ -81,6 +83,7 @@ paths:
8183
security: []
8284
tags:
8385
- cdoc2-key-capsules
86+
8487
components:
8588
schemas:
8689
Capsule:

‎cdoc2-key-shares-openapi.yaml‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
openapi: 3.0.3
2+
info:
3+
contact:
4+
url: http://ria.ee
5+
title: cdoc2-key-shares
6+
version: 1.0.1-draft
7+
description: API for exchanging CDOC2 key material shares
8+
servers:
9+
- url: 'https://localhost:8443'
10+
description: Regular TLS (no mutual TLS required).
11+
12+
paths:
13+
'/key-shares/{shareId}':
14+
get:
15+
summary: Get key share for shareId
16+
description: Get key share for shareId
17+
tags:
18+
- cdoc2-key-shares
19+
operationId: getKeyShareByShareId
20+
parameters:
21+
- name: shareId
22+
in: path
23+
schema:
24+
type: string
25+
minLength: 18
26+
maxLength: 34
27+
required: true
28+
- name: x-cdoc2-auth-ticket
29+
in: header
30+
schema:
31+
type: string
32+
required: true
33+
description: |
34+
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)
35+
- name: x-cdoc2-auth-x5c
36+
in: header
37+
schema:
38+
type: string
39+
required: true
40+
description: |
41+
PEM encoded X509 certificate (without newlines) that was used to sign X-Cdoc2-Auth-Ticket.
42+
Certificate holders identify is specified in Subject "serialnumber" field. This must match to
43+
"kid" in "x-cdoc2-auth-ticket" header. Example certificate subject:
44+
'serialNumber = PNOEE-30303039914, GN = OK, SN = TESTNUMBER, CN = "TESTNUMBER,OK", C = EE'
45+
Certificate full structure is defined in
46+
[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)
47+
responses:
48+
'200':
49+
description: OK
50+
content:
51+
application/json:
52+
schema:
53+
$ref: '#/components/schemas/KeyShare'
54+
'400':
55+
description: 'Bad request. Client error.'
56+
'401':
57+
description: 'Unauthorized. No correct auth headers'
58+
'404':
59+
description: 'Not Found. 404 is also returned, when recipient id in record does not match user id in auth-ticket'
60+
61+
62+
'/key-shares':
63+
post:
64+
summary: Add Key Share
65+
description: Save a key share and generate share id using secure random. Generated share is returned in Location header
66+
operationId: createKeyShare
67+
responses:
68+
'201':
69+
description: Created
70+
headers:
71+
Location:
72+
schema:
73+
type: string
74+
example: /key-shares/9a7c3717d21f5cf19d18fa4fa5adee21
75+
description: 'URI of created resource. ShareId can be extracted from URI as it follows pattern /key-shares/{shareId}'
76+
'400':
77+
description: 'Bad request. Client error.'
78+
requestBody:
79+
required: true
80+
content:
81+
application/json:
82+
schema:
83+
$ref: '#/components/schemas/KeyShare'
84+
tags:
85+
- cdoc2-key-shares
86+
87+
'/key-shares/{shareId}/nonce':
88+
post:
89+
description: |
90+
Create server nonce for authentication signature.
91+
operationId: createNonce
92+
parameters:
93+
- name: shareId
94+
in: path
95+
schema:
96+
type: string
97+
minLength: 18
98+
maxLength: 34
99+
required: true
100+
responses:
101+
'200':
102+
description: Created
103+
content:
104+
application/json:
105+
schema:
106+
$ref: '#/components/schemas/NonceResponse'
107+
'400':
108+
description: 'Bad request. Client error.'
109+
'403':
110+
description: 'Authentication failed'
111+
'404':
112+
description: 'Not Found. (shareId)'
113+
requestBody:
114+
required: false
115+
description: Always empty (OAS doesn't allow post without body, so optional body is defined here)
116+
content:
117+
application/json:
118+
schema: #empty request body
119+
type: object
120+
nullable: true
121+
tags:
122+
- cdoc2-key-shares
123+
124+
components:
125+
schemas:
126+
KeyShare:
127+
title: Key Share
128+
type: object
129+
properties:
130+
share:
131+
type: string
132+
format: byte
133+
minLength: 32
134+
maxLength: 128
135+
description: Key Share. Binary format is yet to be defined [#RM-55912](https://rm-int.cyber.ee/ito/issues/55912)
136+
recipient:
137+
type: string
138+
minLength: 12
139+
maxLength: 32
140+
description: |
141+
Recipient who can download this share. ETSI319412-1. Example "etsi/PNOEE-48010010101".
142+
In future might support other formats
143+
[etsi/:semantics-identifier](https://github.com/SK-EID/smart-id-documentation/blob/v2/README.md#2322-etsisemantics-identifier)
144+
required:
145+
- share
146+
- recipient
147+
148+
NonceResponse:
149+
title: Nonce response
150+
type: object
151+
properties:
152+
nonce:
153+
type: string
154+
minLength: 12
155+
maxLength: 16
156+
description: 'server nonce for subsequent authentication'
157+
required:
158+
- nonce
159+
160+
securitySchemes:
161+
bearerAuth: # for /key-shares endpoints, long-term token
162+
type: http
163+
scheme: bearer
164+
basicAuth: # temporary solution for initial functionality of /key-shares endpoints
165+
type: http
166+
scheme: basic
167+
168+
tags:
169+
- name: cdoc2-key-shares

‎get-openapi-version.groovy‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
import org.yaml.snakeyaml.Yaml
22
println 'buildbasedir: ' + properties['buildbasedir']
33
def yaml = new Yaml()
4-
def openapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-capsules-openapi.yaml').text)
5-
println "cdoc2-key-capsules-openapi.version: ${openapi.info.version}"
6-
project.getProperties().setProperty('cdoc2-key-capsules-openapi.version', openapi.info.version)
4+
def keyCapsuleOpenapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-capsules-openapi.yaml').text)
5+
println "cdoc2-key-capsules-openapi.version: ${keyCapsuleOpenapi.info.version}"
6+
project.getProperties().setProperty('cdoc2-key-capsules-openapi.version', keyCapsuleOpenapi.info.version)
7+
8+
def keySharesOpenapi = yaml.load(new File(properties['buildbasedir'] + File.separator + 'cdoc2-key-shares-openapi.yaml').text)
9+
println "cdoc2-key-shares-openapi.version: ${keySharesOpenapi.info.version}"
10+
project.getProperties().setProperty('cdoc2-key-shares-openapi.version', keySharesOpenapi.info.version)

‎pom.xml‎

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<modelVersion>4.0.0</modelVersion>
66

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

71-
<dependencies></dependencies>
72-
7371
<build>
7472
<plugins>
7573
<plugin>
@@ -85,14 +83,13 @@
8583
</dependencies>
8684
<executions>
8785
<execution>
88-
<id>parse-info.version-from-cdoc2-key-capsules-openapi.yaml</id>
86+
<id>parse-info.version-from-yaml-files</id>
8987
<phase>initialize</phase>
9088
<goals>
9189
<goal>execute</goal>
9290
</goals>
9391
<configuration>
9492
<properties>
95-
9693
<buildbasedir>${project.basedir}</buildbasedir>
9794
</properties>
9895
<!-- Path variables on Win are not encoded properly if included directly into pom.xml -->
@@ -133,7 +130,6 @@
133130
<goal>install-file</goal>
134131
</goals>
135132
<configuration>
136-
137133
<file>${project.basedir}/cdoc2-key-capsules-openapi.yaml</file>
138134
<groupId>ee.cyber.cdoc2.openapi</groupId>
139135
<artifactId>cdoc2-key-capsules-openapi</artifactId>
@@ -142,6 +138,21 @@
142138
<packaging>yaml</packaging>
143139
</configuration>
144140
</execution>
141+
<execution>
142+
<id>deploy-openapi-cdoc2-key-shares</id>
143+
<phase>install</phase>
144+
<goals>
145+
<goal>install-file</goal>
146+
</goals>
147+
<configuration>
148+
<file>${project.basedir}/cdoc2-key-shares-openapi.yaml</file>
149+
<groupId>ee.cyber.cdoc2.openapi</groupId>
150+
<artifactId>cdoc2-key-shares-openapi</artifactId>
151+
<!-- cdoc2-key-shares-openapi.version value is set by groovy-maven-plugin, parsed from openapi file -->
152+
<version>${cdoc2-key-shares-openapi.version}</version>
153+
<packaging>yaml</packaging>
154+
</configuration>
155+
</execution>
145156
</executions>
146157
</plugin>
147158

@@ -168,6 +179,24 @@
168179
<url>${project.distributionManagement.repository.url}</url>
169180
</configuration>
170181
</execution>
182+
<execution>
183+
<id>deploy-openapi-cdoc2-key-shares</id>
184+
<phase>deploy</phase>
185+
<goals>
186+
<goal>deploy-file</goal>
187+
</goals>
188+
<configuration>
189+
<skip>false</skip>
190+
<file>${project.basedir}/cdoc2-key-shares-openapi.yaml</file>
191+
<groupId>ee.cyber.cdoc2.openapi</groupId>
192+
<artifactId>cdoc2-key-shares-openapi</artifactId>
193+
<!-- cdoc2-key-shares-openapi.version value is set by groovy-maven-plugin, parsed from openapi file -->
194+
<version>${cdoc2-key-shares-openapi.version}</version>
195+
<packaging>yaml</packaging>
196+
<repositoryId>${project.distributionManagement.repository.id}</repositoryId>
197+
<url>${project.distributionManagement.repository.url}</url>
198+
</configuration>
199+
</execution>
171200
</executions>
172201

173202
<configuration>

0 commit comments

Comments
 (0)