aswi2021jmsd-gitlab/src/swagger.yaml @ bb4a9d1f

---
openapi: 3.0.0
info:
  title: X.509 certificate management
  description: API for certificate management created for YOSO company
  version: 1.2.0
servers:
- url: https://virtserver.swaggerhub.com/janpasek97/X509_management/1.2.0
  description: X509 management API
tags:
- name: certificates
  description: API for creating and querying certificates
paths:
  /api/certificates:
    get:
      tags:
      - certificates
      summary: get list of certificates
      description: Lists certificates based on provided filtering options
      operationId: getCertificateList
      parameters:
      - name: filtering
        in: query
        description: Filter certificate type to be queried
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/Filtering'
      - name: page
        in: query
        description: Page of the certificates to be displayed
        required: false
        style: form
        explode: true
        schema:
          type: integer
          example: 1
      - name: per_page
        in: query
        description: Number of certificates returned in one page
        required: false
        style: form
        explode: true
        schema:
          type: integer
          example: 10
      responses:
        "200":
          description: returning results matching filtering criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateListResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - certificates
      summary: create new certificate
      description: Create a new certificate based on given information
      operationId: createCertificate
      requestBody:
        description: Certificate data to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateRequest'
      responses:
        "201":
          description: item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedResponse'
        "400":
          description: invalid input, object invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}:
    get:
      tags:
      - certificates
      summary: get certificate by ID
      description: Get certificate in PEM format by ID
      operationId: getCertificateById
      parameters:
      - name: id
        in: path
        description: ID of a certificate to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PemResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - certificates
      summary: delete certificate by ID
      description: Delete certificate by id. If the specified certificate is an issuer of some other certificate, whole subtree is delted.
      operationId: deleteCertificateById
      parameters:
      - name: id
        in: path
        description: ID of a certificate to be deleted
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: certificate deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - certificates
      summary: revoke certificate by id
      description: Revoke a certificate specified by id
      operationId: revokeCertificateById
      parameters:
      - name: id
        in: path
        description: ID of a certificate to be deleted
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetStatusRequest'
      responses:
        "200":
          description: Certificate status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/chain:
    get:
      tags:
      - certificates
      summary: get certificate's trust chain by ID
      description: Get certificate trust chain in PEM format by ID
      operationId: getCertificateTrustChainById
      parameters:
      - name: id
        in: path
        description: ID of a child certificate whose chain is to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the trust chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PemResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/root:
    get:
      tags:
      - certificates
      summary: get certificate's root of trust chain by ID
      description: Get certificate's root of trust chain in PEM format by ID
      operationId: getCertificateRootById
      parameters:
      - name: id
        in: path
        description: ID of a child certificate whose root is to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the root of trust chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PemResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/details:
    get:
      tags:
      - certificates
      summary: get certificate's details by ID
      description: Get certificate details by ID
      operationId: getCertificateDetailsById
      parameters:
      - name: id
        in: path
        description: ID of a certificate whose details are to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the certificate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/publickey:
    get:
      tags:
      - certificates
      summary: get public key of given certificate
      description: Get public key that belongs to the selected certificate
      operationId: getPublicKeyOfCertificateById
      parameters:
      - name: id
        in: path
        description: ID of a certificate whose public key is to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the certificate's public key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PemResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/privatekey:
    get:
      tags:
      - certificates
      summary: get private key of given certificate
      description: Get private key that belongs to the selected certificate
      operationId: getPrivateKeyOfCertificateById
      parameters:
      - name: id
        in: path
        description: ID of a certificate whose private key is to be queried
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      responses:
        "200":
          description: returning the certificate's private key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PemResponse'
        "404":
          description: the certificate was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "400":
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/certificates/{id}/identity:
    post:
      tags:
      - certificates
      summary: Create a PCKS12 identity
      description: Create a PCKS12 identity based on the selected certificate. The identity includes the whole chain of trust and uses a specified name and password
      operationId: createIdentityById
      parameters:
      - name: id
        in: path
        description: ID of a certificate whose PKCS12 identity should be created
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/IdParameter'
      requestBody:
        description: Identity data to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
      responses:
        "200":
          description: identity successfully generated and returned
          content:
            application/x-pkcs12:
              schema:
                type: string
                format: binary
        "400":
          description: missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CertificateUsage:
      properties:
        CA:
          type: boolean
        authentication:
          type: boolean
        digitalSignature:
          type: boolean
        SSL:
          type: boolean
    IssuerListItem:
      required:
      - CN
      - id
      properties:
        id:
          type: integer
          example: 547
        CN:
          type: string
          example: Root CA s.r.o.
    CertificateListResponse:
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CertificateListItem'
    CertificateListItem:
      properties:
        id:
          type: integer
          example: 547
        CN:
          type: string
          example: Root CA s.r.o.
        notBefore:
          type: string
          format: date
          example: 2021-03-31
        notAfter:
          type: string
          format: date
          example: 2021-07-01
        usage:
          $ref: '#/components/schemas/CertificateUsage'
        issuer:
          $ref: '#/components/schemas/IssuerListItem'
    Filtering:
      properties:
        type:
          $ref: '#/components/schemas/CertificateType'
        usage:
          $ref: '#/components/schemas/CertificateUsage'
        issuedby:
          type: integer
          example: 517
    Subject:
      required:
      - CN
      properties:
        C:
          type: string
          description: Country code
          example: CZ
        ST:
          type: string
          description: State/Province
          example: Pilsen Region
        L:
          type: string
          description: Locality
          example: Pilsen
        CN:
          type: string
          description: Common name
          example: Root CA s.r.o.
        O:
          type: string
          description: Organization
          example: Root CA s.r.o.
        OU:
          type: string
          description: Organization Unit
          example: IT department
        emailAddress:
          type: string
          description: Email Address
          example: [e-mail]
    Certificate:
      required:
      - notAfter
      - notBefore
      - status
      - subject
      - usage
      properties:
        subject:
          $ref: '#/components/schemas/Subject'
        notBefore:
          type: string
          format: date
          example: 2021-03-31
        notAfter:
          type: string
          format: date
          example: 2021-07-01
        usage:
          $ref: '#/components/schemas/CertificateUsage'
        CA:
          type: integer
          description: ID of the new item
          example: 547
        status:
          type: string
          enum:
          - valid
          - expired
          - revoked
    CertificateRequest:
      required:
      - subject
      - usage
      - validityDays
      properties:
        subject:
          $ref: '#/components/schemas/Subject'
        validityDays:
          type: integer
          example: 30
        usage:
          type: array
          items:
            type: string
            enum:
            - CA
            - authentication
            - digitalSignature
            - SSL
        CA:
          type: integer
          description: ID of the new item
          example: 547
        key:
          $ref: '#/components/schemas/PrivateKey'
        extensions:
          type: string
          example: subjectAltName=IP:192.168.7.1
    SuccessResponse:
      required:
      - data
      - success
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          example: Operation was successfull
      description: Operation successfull
    CreatedResponse:
      required:
      - data
      - success
      properties:
        success:
          type: boolean
          example: true
        data:
          type: integer
          example: 457
      description: Item was created
    ErrorResponse:
      required:
      - data
      - success
      properties:
        success:
          type: boolean
          example: false
        data:
          type: string
          example: An error occured
    CertificateResponse:
      required:
      - data
      - success
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Certificate'
    PemResponse:
      required:
      - data
      - success
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Single PEM file or concatenation of multiple PEM formatted certificates
          example: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----'
    IdParameter:
      required:
      - id
      properties:
        id:
          type: integer
          example: 444
    SetStatusRequest:
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - revoked
          - valid
        reason:
          type: string
          enum:
          - unspecified
          - keyCompromise
          - CACompromise
          - affiliationChanged
          - superseded
          - cessationOfOperation
          - certificateHold
          - removeFromCRL
    CertificateType:
      properties:
        RootCA:
          type: boolean
        IntermediateCA:
          type: boolean
        EndCertificate:
          type: boolean
    PrivateKey:
      properties:
        password:
          type: string
          example: passphrase
        key_pem:
          type: string
          example: '-----BEGIN PRIVATE_KEY-----...-----END PRIVATE_KEY-----'
    IdentityRequest:
      properties:
        name:
          type: string
          example: Jane Doe
          required: true
        password:
          type: string
          example: passphrase
          required: true