swagger: '2.0'
info:
  title: caucase
  description: Certificate Authority for Users, Certificate Authority for SErvices
  version: 0.2.0
  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
  - application/pkix-crl
  - application/pkcs10
  - application/x-x509-ca-cert
tags:
  - name: auth
    description: https client authentication required
paths:
  /csr:
    get:
      summary: List pending certificate signing requests
      operationId: getPendingCertificateRequestList
      tags:
        - auth
      produces:
        - application/json
      responses:
        '200':
          description: OK - CSR list returned
        '404':
          $ref: '#/responses/404'
    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
      tags:
        - auth
      parameters:
        - $ref: '#/parameters/crt-id'
      responses:
        '204':
          description: No Content - CSR was successfuly rejected
        '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
        '400':
          $ref: '#/responses/400'
        '404':
          $ref: '#/responses/404'
  /crt/{crt-id}:
    put:
      summary: Accept pending certificate signing request
      operationId: createCertificate
      tags:
        - auth
      parameters:
        - $ref: '#/parameters/crt-id'
      responses:
        '204':
          description: No Content - CSR was successfuly signed
        '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'
  /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
  /crt/revoke:
    put:
      summary: Revoke a certificate
      description: Signed operation payload schema is described separately.
      operationId: revokeCertificate
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/signed-operation'
      responses:
        '204':
          description: No Content - certificate revoked
  /crt/renew:
    put:
      summary: Renew a certificate
      description: Signed operation payload schema is described separately.
      operationId: renewCertificate
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/signed-operation'
      responses:
        '200':
          description: OK - Renewed certificate retrieved
  /crl:
    get:
      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
      operationId: getCertificateRevocationList
      parameters:
        - $ref: '#/parameters/authority-key-id'
      produces:
        - application/pkix-crl
      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'
  authority-key-id:
    name: authority-key-id
    in: path
    description: decimal representation of an authority key identifier
    required: true
    type: string
responses:
  '400':
    description: Bad Request - you probably provided wrong parameters
  '404':
    description: Not Found - Requested resource does not exist, or you did not provide required transport-level credentials (x509 cert over https)
  '507':
    description: Insufficient Storage