cdoc2-openapi/cdoc2-key-shares-openapi.yaml at master · open-eid/cdoc2-openapi · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
openapi: 3.0.3
info:
  contact:
    url: http://ria.ee
  title: cdoc2-key-shares
  version: 1.0.1
  description: |
    API for exchanging CDOC2 key material shares.

    `KeyShare` objects defined here are created by splitting cryptographic material required for
    encrypting/decrypting CDOC2 document. `KeyShare` objects required for combining original cryptographic material
    are stored in CDOC2 header `KeySharesCapsule` [FBS](https://github.com/open-eid/cdoc2-java-ref-impl/blob/master/cdoc2-schema/src/main/fbs/recipients.fbs) object.

    To access `KeyShare` objects, recipient must authenticate himself by including `x-cdoc2-auth-ticket`
    and `x-cdoc2-auth-x5c` headers for `getKeyShareByShareId` operation.

    * `x-cdoc2-auth-ticket` is sd-jwt defined in WIP https://open-eid.github.io/CDOC2/2.0/ .
      Java implementation for `x-cdoc2-auth-ticket` can be found WIP https://github.com/open-eid/cdoc2-auth
      `x-cdoc2-auth-ticket` is signed by Smart-ID [authentication](https://github.com/SK-EID/smart-id-documentation?tab=readme-ov-file#2310-authentication-session)
      certificate or [Mobile-ID authentication](https://github.com/SK-EID/MID?tab=readme-ov-file#32-initiating-signing-and-authentication) certificate.
    * `x-cdoc2-auth-x5c` is PEM encoded X509 certificate (without newlines) that was used to sign x-cdoc2-auth-ticket.
      Certificate holders identify is specified in Subject "serialnumber" field. 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)

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://github.com/open-eid/CDOC2/blob/master/cdoc2-system-docs/docs/03_system_architecture/ch06_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. 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: |
            Base64 encoded Key Share. Binary format.

        recipient:
          type: string
          minLength: 12
          maxLength: 32
          description: |
            Recipient who can download this share. ETSI319412-1. Example "etsi/PNOEE-48010010101".
            Must match certificate subject serialnumber field (without "etsi/" prefix).
            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