---
#-----------------------------------------------------------------------------------------------------------------------
#   Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
#
#  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
#  with the License. A copy of the License is located at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
#  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
#  and limitations under the License.
#-----------------------------------------------------------------------------------------------------------------------
openapi: 3.0.0
info:
  title: 'AWS Connected Device Framework: Bulk Certs'
  description: REST API for creating device certificates in bulk.
  version: 1.0.0

tags:
  - name: 'Bulk Certificate Creation'
    description: |
      Allows for the asynchronous creation of device certifcates in bulk.  

      Optionally, the certificates may be registered with AWS IoT.  This allows for scenarios such as JITP (just-in-time provisioning).

paths:
  /certificates/{taskId}:
    parameters:
      - $ref: '#/components/parameters/taskId'

    get:
      tags:
        - Bulk Certificate Creation
      summary: Retrieve a batch of pre-generated certificates (the outcome of a batch certificate creation task) either as a downloadable zip file (default) or as a list of pre-signed urls.
      operationId: getCertificates
      parameters:
        - $ref: '#/components/parameters/downloadType'

      responses:
        '200':
          description: OK. Either a zip file as the response (default), or a list of s3 presigned urls (when ?downloadType=signedUrl).
          content:
            application/vnd.aws-cdf-v1.0+json:
              schema:
                type: array
                items:
                  type: string
            application/zip:
              schema:
                type: string
                format: binary
        '303':
          description: If certificate creation is still in progress, a redirect to the certificate task status endpoint.
        '404':
          $ref: '#/components/responses/NotFound'

  /certificates/{taskId}/task:
    parameters:
      - $ref: '#/components/parameters/taskId'

    get:
      tags:
        - Bulk Certificate Creation
      summary: Retrieve status of a create certificates task.
      operationId: getCertificatesTask

      responses:
        '200':
          description: OK.
          content:
            application/vnd.aws-cdf-v1.0+json:
              schema:
                $ref: '#/components/schemas/CertificateBatchTaskStatus'
        '404':
          $ref: '#/components/responses/NotFound'

  /supplier/{supplierId}/certificates:
    parameters:
      - $ref: '#/components/parameters/supplierId'

    post:
      tags:
        - Bulk Certificate Creation
      summary: Creates a batch of device certificates for a specific supplier.

      operationId: 'createSupplierCertificates'
      requestBody:
        required: true
        content:
          application/vnd.aws-cdf-v1.0+json:
            schema:
              $ref: '#/components/schemas/CertificateBatchRequest'
            examples:
              simple:
                summary: Create a batch of certificates using application defaults set at deployment time.
                value:
                  quantity: 2
              custom_cert_info:
                summary: Create a batch of certificates, specifying certificate values to set.
                value:
                  quantity: 2
                  certInfo:
                    country: US
              common_name_list_generator:
                summary: Create a batch of certificates, auto-generating common name based on a provided list in commonNameList.
                value:
                  certInfo:
                    commonName: '`templateFoo::`${list}'
                    commonNameList:
                      - AB1CD79EF1
                      - AB1CD79EF2
                      - AB1CD79EF3
                    organization: 'AWS Connected Device Framework'
                    organizationalUnit: 'CDF'
                    locality: 'Denver'
                    stateName: 'CO'
                    country: 'US'
                    emailAddress: 'info@connecteddeviceframework.com'
                    distinguishedNameQualifier: ''
                    includeCA: true
                  quantity: 100

              common_name_static_generator:
                summary: Create a batch of certificates, auto-generating static common name.
                value:
                  certInfo:
                    commonName: '`templateFoo::`AB1CD79EF${static}'
                    organization: 'AWS Connected Device Framework'
                    organizationalUnit: 'CDF'
                    locality: 'Denver'
                    stateName: 'CO'
                    country: 'US'
                    emailAddress: 'info@connecteddeviceframework.com'
                    distinguishedNameQualifier: ''
                    includeCA: true
                  quantity: 100

              common_name_increment_generator:
                summary: Create a batch of certificates, auto-generating incremental common names.
                value:
                  certInfo:
                    commonName: '`templateFoo::`AB1CD79EF${increment(100)}'
                    organization: 'AWS Connected Device Framework'
                    organizationalUnit: 'CDF'
                    locality: 'Denver'
                    stateName: 'CO'
                    country: 'US'
                    emailAddress: 'info@connecteddeviceframework.com'
                    distinguishedNameQualifier: ''
                    includeCA: true
                  quantity: 100

      responses:
        '202':
          description: Acceptd.
          content:
            application/vnd.aws-cdf-v1.0+json:
              schema:
                $ref: '#/components/schemas/CertificateBatchTask'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  parameters:
    taskId:
      in: path
      name: taskId
      description: Id of the bulk certificate creation task
      required: true
      schema:
        type: string
    downloadType:
      in: query
      name: downloadType
      description: ID of device template to publish
      schema:
        type: string
        enum:
          - signedUrl
          - zip
        default: zip
    supplierId:
      in: path
      name: supplierId
      description: Id (alias) of supplier for which to create device  certificates.
      required: true
      schema:
        type: string

  responses:
    Created:
      description: Created successfully
      headers:
        location:
          schema:
            type: string
    BadRequest:
      description: Invalid input
      content:
        application/vnd.aws-cdf-v1.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/vnd.aws-cdf-v1.0+json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    CertificateBatchTask:
      type: object
      properties:
        taskId:
          type: string
        status:
          type: string
          enum:
            - pending
            - in_progress
            - complete

    CertificateBatchTaskStatus:
      allOf:
        - $ref: '#/components/schemas/CertificateBatchTask'
        - type: object
          properties:
            batchDate:
              type: number
            chunksPending:
              type: number
            chunksTotal:
              type: number

    CertificateBatchRequest:
      type: object
      properties:
        quantity:
          type: number
          description: Quantity of device certificates to create.
        register:
          type: boolean
          description: Optionally register device certificates with AWS IoT.
          default: false
        certInfo:
          $ref: '#/components/schemas/CertInfo'
      required:
        - quantity

    CertInfo:
      type: object
      properties:
        commonName:
          description: Specify a common name to add to a certificate, or a generator used to auto-generate the common name.
          oneOf:
            - type: string
            - $ref: '#/components/schemas/CommonNameGenerator'
        commonNameList:
          description: A list of ids to be used in the generation of the commonNames.
          type: array
          items:
            type: string
        organization:
          description: Organization to set within the certificate.
          type: string
        organizationalUnit:
          description: Organizational unit to set within the certificate.
          type: string
        locality:
          description: Locality to set within the certificate.
          type: string
        stateName:
          description: State name to set within the certificate.
          type: string
        country:
          description: Country to set within the certificate.
          type: string
        emailAddress:
          description: Email address to set within the certificate.
          type: string
        distinguishedNameQualifier:
          description: Distinguished Name Qualifier to set within the certificate.
          type: string
        includeCA:
          description: If true, the public certificate of the CA used to sign the device certificate will be appended to the device certificate.
          type: boolean
        daysExpiry:
          type: number
          description: SSL Certificate Max validity period. The maximum validity period of TLS/SSL certificates is 825 days (2 years, 3 month, and 5 days).

    CommonNameGenerator:
      type: object
      description: |
        Will Auto-generates the common name based on the properties provided in the command structure "\`prefix\`commonNameStart${generator(quantity)}".

        As an example the following command "\`templateFoo::\`AB1CD79EF${incement(5)}" will generate 5 incremental commonNames starting from templateFoo:AB1CD79EF1 to templateFoo:AB1CD79EF5 

        Please refer to the bellow documentation for guidance on each of the properties in the command
      properties:
        generator:
          type: string
          description: |

            If `increment`, the commonName will be generated by combining the prefix and the incremented commonNameStart hexadecimal value.

            If `list`, the commonName will be generated by combining the prefix and the values provided in the commonNameList. Please note that in this mode the number of elements in the array determines the number of certificates being generated and not the quantity value

            If `static`, a static value will be generated by combining the prefix and commanNameStart.
          enum:
            - increment
            - list
            - static
        prefix:
          description: Static string prefix that can be used as a prefix in the construction of the commonName
          type: string
        commonNameStart:
          description: A hexadecimal string that can be used where incremental generator is requiered.
          type: string
        quantity:
          description: A numerical value, representing the number of certificates that are to be genrated
          type: number

    Error:
      type: object
      properties:
        message:
          description: Error message
          type: string