P-SLAPOS.Certificate.Authority.Swagger.API.Specification-en-001.yml 7.56 KB
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