P-SLAPOS.Certificate.Authority.Swagger.API.Specification-en-001.yml 6.17 KB
Newer Older
1 2
swagger: '2.0'
info:
Vincent Pelletier's avatar
Vincent Pelletier committed
3 4 5
  title: caucase
  description: Certificate Authority for Users, Certificate Authority for SErvices
  version: 0.2.0
6 7 8 9 10 11 12 13 14 15 16 17 18
  contact:
    name: Vincent Pelletier (Nexedi)
    url: 'http://www.nexedi.com'
    email: vincent@nexedi.com
basePath: /
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
  - application/pkix-cert
Vincent Pelletier's avatar
Vincent Pelletier committed
19 20
  - application/pkix-crl
  - application/pkcs10
21 22
  - application/x-x509-ca-cert
tags:
Vincent Pelletier's avatar
Vincent Pelletier committed
23 24
  - name: auth
    description: https client authentication required
25 26 27
paths:
  /csr:
    get:
Vincent Pelletier's avatar
Vincent Pelletier committed
28
      summary: List pending certificate signing requests
29
      operationId: getPendingCertificateRequestList
Vincent Pelletier's avatar
Vincent Pelletier committed
30 31 32 33
      tags:
        - auth
      produces:
        - application/json
34
      responses:
Vincent Pelletier's avatar
Vincent Pelletier committed
35 36 37 38
        '200':
          description: OK - CSR list returned
        '404':
          $ref: '#/responses/404'
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
    put:
      summary: Request a new certificate signature
      operationId: createCertificateSigningRequest
      consumes:
        - application/pkcs10
      parameters:
        - $ref: '#/parameters/csr'
      responses:
        '201':
          description: Created - Signing request was accepted
          headers:
            Location:
              description: URL of created resource
              type: string
        '507':
          $ref: '#/responses/507'
  /csr/{crt-id}:
    delete:
      summary: Reject a pending certificate signing request
      operationId: deletePendingCertificateRequest
Vincent Pelletier's avatar
Vincent Pelletier committed
59 60
      tags:
        - auth
61 62 63 64
      parameters:
        - $ref: '#/parameters/crt-id'
      responses:
        '204':
Vincent Pelletier's avatar
Vincent Pelletier committed
65
          description: No Content - CSR was successfuly rejected
66 67 68 69 70 71 72 73 74 75 76 77
        '404':
          $ref: '#/responses/404'
    get:
      summary: Retrieve a pending certificate signing request
      operationId: getCertificateSigningRequest
      produces:
        - application/pkcs10
      parameters:
        - $ref: '#/parameters/crt-id'
      responses:
        '200':
          description: OK - CSR retrieved
Vincent Pelletier's avatar
Vincent Pelletier committed
78 79
        '400':
          $ref: '#/responses/400'
80 81
        '404':
          $ref: '#/responses/404'
Vincent Pelletier's avatar
Vincent Pelletier committed
82
  /crt/{crt-id}:
83 84 85
    put:
      summary: Accept pending certificate signing request
      operationId: createCertificate
Vincent Pelletier's avatar
Vincent Pelletier committed
86 87
      tags:
        - auth
88 89
      parameters:
        - $ref: '#/parameters/crt-id'
90
      responses:
Vincent Pelletier's avatar
Vincent Pelletier committed
91 92
        '204':
          description: No Content - CSR was successfuly signed
93 94 95 96 97 98 99 100 101 102 103 104 105 106
        '404':
          $ref: '#/responses/404'
    get:
      summary: Retrieve a signed certificate
      operationId: getCertificate
      produces:
        - application/pkix-cert
      parameters:
        - $ref: '#/parameters/crt-id'
      responses:
        '200':
          description: OK - CRT retrieved
        '404':
          $ref: '#/responses/404'
Vincent Pelletier's avatar
Vincent Pelletier committed
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
  /crt/ca.crt.pem:
    get:
      summary: Retrieve current CA certificate
      operationId: getCACertificate
      produces:
        - application/x-x509-ca-cert
      responses:
        '200':
          description: OK - CA CRT retrieved
  /crt/ca.crt.json:
    get:
      summary: Retrieve current CA certificate trust chain
      description: Response schema is described separately.
      operationId: getCACertificateChain
      produces:
        - application/json
      responses:
        '200':
          description: OK - CA CRT chain retrieved
126 127 128
  /crt/revoke:
    put:
      summary: Revoke a certificate
Vincent Pelletier's avatar
Vincent Pelletier committed
129
      description: Signed operation payload schema is described separately.
130 131 132 133 134 135
      operationId: revokeCertificate
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/signed-operation'
      responses:
Vincent Pelletier's avatar
Vincent Pelletier committed
136 137
        '204':
          description: No Content - certificate revoked
138 139 140
  /crt/renew:
    put:
      summary: Renew a certificate
Vincent Pelletier's avatar
Vincent Pelletier committed
141
      description: Signed operation payload schema is described separately.
142 143 144 145 146 147
      operationId: renewCertificate
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/signed-operation'
      responses:
Vincent Pelletier's avatar
Vincent Pelletier committed
148 149
        '200':
          description: OK - Renewed certificate retrieved
150 151
  /crl:
    get:
152 153 154 155 156 157 158 159 160 161
      summary: Retrieve the list (as concatenated PEM-encoded chunks) of latest certificate revocation list for all authority keys
      operationId: getCertificateRevocationListList
      produces:
        - application/pkix-crl
      responses:
        '200':
          description: OK - CRL retrieved
  /crl/{authority-key-id}:
    get:
      summary: Retrieve latest certificate revocation list for given authority key
162
      operationId: getCertificateRevocationList
163 164
      parameters:
        - $ref: '#/parameters/authority-key-id'
165
      produces:
Vincent Pelletier's avatar
Vincent Pelletier committed
166
        - application/pkix-crl
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
      responses:
        '200':
          description: OK - CRL retrieved
definitions:
  csr:
    type: string
    description: application/pkcs10 data
  signed-operation:
    type: object
    required:
      - signature
      - payload
      - digest
    properties:
      digest:
        type: string
        description: Digest method name used to generate the signature (like "sha256", "sha512", etc)
      signature:
        type: string
        description: Base64-encoded signature generated by concatenating payload, digest and the space character (0x20), in this order.
      payload:
        type: string
        description: Operation parameters. This is a json-encoded value whose structure depends on the operation.
parameters:
  crt-id:
    name: crt-id
    in: path
    description: Opaque certificate signing request identifier
    required: true
    type: string
  csr:
    name: csr
    in: body
    description: x509 Certificate Signing Request
    required: true
    schema:
      $ref: '#/definitions/csr'
  signed-operation:
    name: signed-operation
    in: body
    description: An operation, signed with requester's private key
    schema:
      $ref: '#/definitions/signed-operation'
210 211 212 213 214 215
  authority-key-id:
    name: authority-key-id
    in: path
    description: decimal representation of an authority key identifier
    required: true
    type: string
216 217 218 219
responses:
  '400':
    description: Bad Request - you probably provided wrong parameters
  '404':
Vincent Pelletier's avatar
Vincent Pelletier committed
220
    description: Not Found - Requested resource does not exist, or you did not provide required transport-level credentials (x509 cert over https)
221 222
  '507':
    description: Insufficient Storage