certificate_authority: More specification work.

slapos/certificate_authority/doc/P-SLAPOS.Certificate.Authority.Swagger.API.Specification-en-001.yml

+swagger: '2.0'
+info:
+  title: Certificate Authority
+  description: Automated x509 certificate authority for use with non-http services
+  version: 0.0.1
+  contact:
+    name: Vincent Pelletier (Nexedi)
+    url: 'http://www.nexedi.com'
+    email: vincent@nexedi.com
+basePath: /
+schemes:
+  - http
+  - https
+consumes:
+  - application/json
+  - application/pkcs10
+produces:
+  - application/xml
+  - application/json
+  - application/pkix-cert
+  - application/x-x509-ca-cert
+tags:
+  - name: todo
+    description: Known as not fully specified yet
+paths:
+  /csr:
+    get:
+      tags:
+        - todo
+      summary: List pending certificate signing requests - XXX PROPFIND, not GET !
+      operationId: getPendingCertificateRequestList
+      schemes:
+        - https
+      parameters:
+        - $ref: '#/parameters/x-auth'
+      responses:
+        '401':
+          $ref: '#/responses/401'
+        '403':
+          $ref: '#/responses/403'
+        '500':
+          $ref: '#/responses/500'
+    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
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+        '507':
+          $ref: '#/responses/507'
+  /csr/{crt-id}:
+    delete:
+      summary: Reject a pending certificate signing request
+      operationId: deletePendingCertificateRequest
+      schemes:
+        - https
+      parameters:
+        - $ref: '#/parameters/x-auth'
+        - $ref: '#/parameters/crt-id'
+      responses:
+        '204':
+          description: No Content - CSR was rejected
+        '401':
+          $ref: '#/responses/401'
+        '403':
+          $ref: '#/responses/403'
+        '404':
+          $ref: '#/responses/404'
+        '500':
+          $ref: '#/responses/500'
+    get:
+      summary: Retrieve a pending certificate signing request
+      operationId: getCertificateSigningRequest
+      produces:
+        - application/pkcs10
+      parameters:
+        - $ref: '#/parameters/crt-id'
+      responses:
+        '200':
+          description: OK - CSR retrieved
+        '404':
+          $ref: '#/responses/404'
+        '500':
+          $ref: '#/responses/500'
+  /crt:
+    put:
+      summary: Accept pending certificate signing request
+      operationId: createCertificate
+      schemes:
+        - https
+      consumes:
+        - application/pkcs10
+      parameters:
+        - $ref: '#/parameters/x-auth'
+        - $ref: '#/parameters/csr'
+      responses:
+        '201':
+          description: Created - Certificate was signed
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '401':
+          $ref: '#/responses/401'
+        '404':
+          $ref: '#/responses/404'
+        '403':
+          $ref: '#/responses/403'
+        '500':
+          $ref: '#/responses/500'
+  /crt/{crt-id}:
+    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'
+        '500':
+          $ref: '#/responses/500'
+  /crt/revoke:
+    put:
+      summary: Revoke a certificate
+      description: >
+        Response status 400 may mean operation could not be authenticated (signature hash mechanism not supported by server, signature did not match...). Signed operation payload schema is described separately.
+      operationId: revokeCertificate
+      consumes:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/signed-operation'
+      responses:
+        '201':
+          description: Created - Signing request was revoked
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+  /crt/renew:
+    put:
+      summary: Renew a certificate
+      description: >
+        Response status 400 may mean operation could not be authenticated (signature hash mechanism not supported by server, signature did not match...), in addition to createCertificateSigningRequest status 400 reasons. Signed operation payload schema is described separately.
+      operationId: renewCertificate
+      consumes:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/signed-operation'
+      responses:
+        '201':
+          description: Created - Renewwal request was accepted
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+  /crl:
+    get:
+      summary: Retrieve latest certificate revocation list
+      operationId: getCertificateRevocationList
+      produces:
+        - application/x-x509-ca-cert
+      responses:
+        '200':
+          description: OK - CRL retrieved
+        '500':
+          $ref: '#/responses/500'
+definitions:
+  csr:
+    type: string
+    description: application/pkcs10 data
+  Error:
+    type: object
+    required:
+      - code
+      - name
+      - message
+    properties:
+      code:
+        type: integer
+        description: application-specific error code
+      name:
+        type: string
+        description: the explicit error name
+      message:
+        type: string
+        description: describes the error
+  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
+  x-auth:
+    name: Authorization
+    in: header
+    description: Credentials for this request
+    type: string
+    required: true
+  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'
+responses:
+  '400':
+    description: Bad Request - you probably provided wrong parameters
+    schema:
+      $ref: '#/definitions/Error'
+  '401':
+    description: Unauthorized - No Authorization header provided
+    headers:
+      Authenticate:
+        type: string
+        description: Requests that client provides credentials
+    schema:
+      $ref: '#/definitions/Error'
+  '403':
+    description: Forbidden - Authorization headed provided, but does not grant access
+    schema:
+      $ref: '#/definitions/Error'
+  '404':
+    description: Not Found - Requested resource does not exist
+    schema:
+      $ref: '#/definitions/Error'
+  '500':
+    description: Internal Server Error
+  '507':
+    description: Insufficient Storage