api.yml

openapi: 3.0.0

info:
  title: balenaSign API
  version: 0.10.0

paths:
  /bootstrap:
    post:
      operationId: app.bootstrap
      description: Create all the signing material needed in one step
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bootstrapRequest"
      responses:
        200:
          description: Values of created signing material
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bootstrapResponse"

  /import:
    post:
      operationId: vault.import_secrets
      description: Import signing material from an encrypted file
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/importRequest"
      responses:
        204:
          description: Signing material successfully imported

  /export:
    post:
      operationId: vault.export_secrets
      description: Encrypt signing material and export as a single file
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/exportRequest"
      responses:
        200:
          description: Signing material successfully exported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/exportResponse"

  /gpg/keys:
    get:
      operationId: gpg.keys
      responses:
        200:
          description: Fingerprints of GPG keys available on the server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gpgKeysResponse"

  /gpg/key/{key_id}:
    get:
      operationId: gpg.key
      parameters:
        - $ref: "#/components/parameters/gpgKey"
      responses:
        200:
          description: Armored GPG public key for the given fingerprint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gpgKeyResponse"

  /gpg/key:
    post:
      operationId: gpg.new
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/gpgNewRequest"
      responses:
        200:
          description: Fingerprint of the newly created GPG key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gpgNewResponse"

  /gpg/sign:
    post:
      operationId: gpg.sign
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/gpgSignRequest"
      responses:
        200:
          description: base64-encoded GPG signature of the given payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gpgSignResponse"

  /cert:
    post:
      operationId: cert.new
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/certNewRequest"
      responses:
        200:
          description: Newly created certificate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/certNewResponse"

  /cert/{cert_id}:
    get:
      operationId: cert.get
      parameters:
        - $ref: "#/components/parameters/certId"
      responses:
        200:
          description: The requested certificate in PEM format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/certNewResponse"

  /cert/sign:
    post:
      operationId: cert.sign
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/certSignRequest"
      responses:
        200:
          description: Signature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/certSignResponse"

  /secureboot/pk/{cert_id}:
    get:
      operationId: secureboot.get_pk
      parameters:
        - $ref: "#/components/parameters/certIdList"
      responses:
        200:
          description: base64-encoded platform key for UEFI
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootPKResponse"

  /secureboot/pk:
    post:
      operationId: secureboot.sign_pk
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/securebootInternalESLSignRequest"
      responses:
        200:
          description: empty
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootESLSignResponse"

  /secureboot/kek/{cert_id}:
    get:
      operationId: secureboot.get_kek
      parameters:
        - $ref: "#/components/parameters/certIdList"
      responses:
        200:
          description: base64-encoded key exchange key for UEFI
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootKEKResponse"

  /secureboot/kek:
    post:
      operationId: secureboot.sign_kek
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/securebootInternalESLSignRequest"
      responses:
        200:
          description: empty
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootESLSignResponse"

  /secureboot/db/{cert_id}:
    get:
      operationId: secureboot.get_db
      parameters:
        - $ref: "#/components/parameters/certIdList"
      responses:
        200:
          description: base64-encoded db for UEFI
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootDbResponse"

  /secureboot/db:
    post:
      operationId: secureboot.sign_db
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/securebootInternalESLSignRequest"
                - $ref: "#/components/schemas/securebootExternalESLSignRequest"
      responses:
        200:
          description: empty
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootESLSignResponse"

  /secureboot/dbx:
    post:
      operationId: secureboot.sign_dbx
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/securebootInternalESLSignRequest"
                - $ref: "#/components/schemas/securebootExternalESLSignRequest"
      responses:
        200:
          description: empty
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootESLSignResponse"

  /secureboot/efi:
    post:
      operationId: secureboot.sign_efi
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/securebootSignRequest"
      responses:
        200:
          description: base64-encoded signed EFI binary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/securebootSignResponse"

  /kmod/cert/{cert_id}:
    get:
      operationId: kmod.cert
      parameters:
        - $ref: "#/components/parameters/certId"
      responses:
        200:
          description: Certificate to verify kernel modules signature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/kmodCertResponse"

  /kmod/sign:
    post:
      operationId: kmod.sign
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/kmodSignRequest"
      responses:
        200:
          description: base64-encoded signed kernel module
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/kmodSignResponse"

  /rsa/keys:
    get:
      operationId: rsa.keys
      responses:
        200:
          description: Fingerprints of RSA keys available on the server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rsaKeysResponse"

  /rsa/key/{key_id}:
    get:
      operationId: rsa.key
      parameters:
        - $ref: "#/components/parameters/rsaKey"
      responses:
        200:
          description: RSA public key for the given fingerprint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rsaKeyResponse"

  /rsa/key:
    post:
      operationId: rsa.new
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/rsaNewRequest"
      responses:
        200:
          description: Fingerprint of the newly created RSA key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rsaNewResponse"

  /rsa/sign:
    post:
      operationId: rsa.sign
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/rsaSignRequest"
      responses:
        200:
          description: base64-encoded RSA signature of the given payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rsaSignResponse"

  /imx/pkis:
    get:
      operationId: imx.pkis
      responses:
        200:
          description: Ids of PKI trees available on the server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/pkisResponse"

  /imx/efuses/{pki_id}:
    get:
      operationId: imx.efuses
      parameters:
        - $ref: "#/components/parameters/pkiId"
      responses:
        200:
          description: Efuses hash file for the given PKI tree ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/efusesResponse"

  /imx/pki:
    post:
      operationId: imx.new
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/pkiNewRequest"
      responses:
        200:
          description: Id of the newly created PKI tree
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/pkiNewResponse"

  /imx/cst:
    post:
      operationId: imx.cst
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/cstRequest"
      responses:
        200:
          description: base64-encoded CSF binary of the given CSF description file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/cstResponse"

components:
  securitySchemes:
    apiKey:
      x-apikeyInfoFunc: auth.validate
      type: apiKey
      in: header
      name: X-API-Key

  parameters:
    gpgKey:
      name: key_id
      description: Fingerprint of the GPG key to fetch
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/gpgKeyFingerprint"

    rsaKey:
      name: key_id
      description: Fingerprint of the RSA key to fetch
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/rsaKeyFingerprint"

    pkiId:
      name: pki_id
      description: Id of the PKI tree to fetch
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/pkiId"

    certId:
      name: cert_id
      description: ID of the certificate to fetch
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/certId"

    certIdList:
      name: cert_id
      description: Multiple IDs of the certificates to fetch
      in: path
      required: true
      explode: true
      schema:
        $ref: "#/components/schemas/certIdList"

  schemas:
    base64:
      type: string
      pattern: "^[a-zA-Z0-9_/\\+\\-]+=?=?$"

    sha256:
      type: string
      pattern: "^[a-fA-F0-9]{64}$"

    certId:
      type: string

    certSubject:
      type: string
      example: "/C=US/ST=Washington/L=Seattle/O=Balena, Inc./OU=IT/CN=balena-cloud.com"

    certData:
      type: string
      example: "-----BEGIN CERTIFICATE-----\nMIIDxzCCAq+gAwIBAgIUSuCy+XvUSQSSDinU0qUAmt4lnZ0wDQYJKoZIhvcNAQEL\nBQAwczELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcM\nB1NlYXR0bGUxFTATBgNVBAoMDEJhbGVuYSwgSW5jLjELMAkGA1UECwwCSVQxGTAX\nBgNVBAMMEGJhbGVuYS1jbG91ZC5jb20wHhcNMjMwMjA4MjMyOTM0WhcNMzMwMjA1\nMjMyOTM0WjBzMQswCQYDVQQGEwJVUzETMBEGA1UECAwKV2FzaGluZ3RvbjEQMA4G\nA1UEBwwHU2VhdHRsZTEVMBMGA1UECgwMQmFsZW5hLCBJbmMuMQswCQYDVQQLDAJJ\nVDEZMBcGA1UEAwwQYmFsZW5hLWNsb3VkLmNvbTCCASIwDQYJKoZIhvcNAQEBBQAD\nggEPADCCAQoCggEBAMBUb+7YMkQqJiTZPAVd62ifTWP3+AjjYIfNoroTZFnLVPQ3\n54dv1sAoPek7xesBwwCuq9HoKBHp7Uk9bNiE13JsMp5DucnndHIuiQGd+XYkHTAQ\nhhrUrzaBX+R7fzaL2ziHz7sRgUn1HK17Vasc9zOmiF7grrG89QYkBa53Se9q2/rA\nqOqi12FdnhcBUwha+/58CpCXi/m8fKj6U9z46GJkx++Lx65I7nWvdJFTT9oKZAQT\nzV9igB3SU2QHREE5bQoLr2h8Lc8l3znyyy9MV0xrUsccct8VSMd0jiETJfpA/Bjp\n/oTajcJKjebQeskFCKdxoAb2hQosBUhvBIswUxkCAwEAAaNTMFEwHQYDVR0OBBYE\nFBck/AQEhIe4i0l1H5dN6KsaI9HrMB8GA1UdIwQYMBaAFBck/AQEhIe4i0l1H5dN\n6KsaI9HrMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAJWEw5df\nngqgMyp0mvyRV+BodQweAUIQ/DpCTY+EHET1DncNKVSB3M4JolGbbD7qnQpN1+PE\ng7J+ukxtfc2QmsEs9Wi+/+01j9iCm0m+H5JoOxBKJ+kBYJEciHjcosTCRCqc++Dm\nXhBG2DjASP/oOOLc9NzUPMXiSNXfBNkheluJNbNGMV6qDnEVnTG/5/hnbvylGONi\nb2UxbEo0J8l+1iXkWMLkH6U5NDit/97WvJlaE/oJJVCp+DNbupH/E8b19jW+ht7/\nEKt5BlUoE+d4UQJfai8nROkqqw64cxv+f6VgYYZHIqTbKn75SYBEy85mHsdv3TYN\nCRhjJiTOvxQg9FE=\n-----END CERTIFICATE-----\n"

    certIdList:
      type: array
      items:
        $ref: "#/components/schemas/certId"

    certDays:
      type: integer
      default: 7305
      minimum: 1

    csf:
      type: string
      example : '[Header]\n	Version = 4.3\n	Hash Algorithm = sha256\n	Engine = CAAM\n	Engine Configuration = 0\n	Certificate Format = X509\n	Signature Format = CMS\n\n[Install SRK]\n	File = "../crts/SRK_1_2_3_4_table.bin"\n	Source index = 0\n\n[Install CSFK]\n	File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"\n\n[Authenticate CSF]\n\n[Unlock]\n	Engine = CAAM\n	Features = MID\n\n[Install Key]\n	Verification index = 0\n	Target index = 2\n	File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"\n\n[Authenticate Data]\n	Verification index = 2\n	Blocks =  \\n'
    keyLength:
      type: integer
      default: 2048
      enum:
        - 2048
        - 4096

    bootstrapRequest:
      type: object
      required:
        - gpg
        - rsa
        - hab
        - ahab
        - certificates
      properties:
        gpg:
          $ref: "#/components/schemas/gpgNewRequest"
        rsa:
          $ref: "#/components/schemas/rsaNewRequest"
        hab:
          $ref: "#/components/schemas/pkiNewRequest"
        ahab:
          $ref: "#/components/schemas/pkiNewRequest"
        certificates:
          type: object
          required:
            - pk
            - kek
            - kmod
          properties:
            pk:
              $ref: "#/components/schemas/certNewRequest"
            kek:
              $ref: "#/components/schemas/certNewRequest"
            db:
              $ref: "#/components/schemas/certNewRequest"
            kmod:
              $ref: "#/components/schemas/certNewRequest"

    bootstrapResponse:
      type: object
      required:
        - gpg
        - rsa
        - pkiHab
        - pkiAhab
        - certificates
      properties:
        gpg:
          $ref: "#/components/schemas/gpgNewResponse"
        rsa:
          $ref: "#/components/schemas/rsaNewResponse"
        pkiHab:
          $ref: "#/components/schemas/pkiNewResponse"
        pkiAhab:
          $ref: "#/components/schemas/pkiNewResponse"
        certificates:
          type: object
          required:
            - pk
            - kek
            - kmod
          properties:
            pk:
              $ref: "#/components/schemas/certData"
            kek:
              $ref: "#/components/schemas/certData"
            db:
              $ref: "#/components/schemas/certData"
            kmod:
              $ref: "#/components/schemas/certData"

    gpgKey:
      type: string

    gpgKeyFingerprint:
      type: string
      pattern: "^[a-fA-F0-9]+$"
      example: "61D762833B1F104A4237E7E5B9C6464953950D96"

    gpgKeyFingerprintList:
      type: array
      items:
        $ref: "#/components/schemas/gpgKeyFingerprint"

    gpgKeyNameReal:
      type: string
      example: "balenaOS build server"

    gpgKeyNameEmail:
      type: string
      example: "security@balena.io"

    gpgKeyNameComment:
      type: string
      default: ""

    importRequest:
      type: object
      required:
        - key
        - data
        - salt
      properties:
        key:
          $ref: "#/components/schemas/base64"
        data:
          $ref: "#/components/schemas/base64"
        salt:
          $ref: "#/components/schemas/base64"

    exportRequest:
      type: object
      required:
        - key
      properties:
        key:
          $ref: "#/components/schemas/base64"

    exportResponse:
      type: object
      required:
        - data
        - salt
      properties:
        data:
          $ref: "#/components/schemas/base64"
        salt:
          $ref: "#/components/schemas/base64"

    certSignRequest:
      type: object
      required:
        - cert_id
        - digest
      properties:
        cert_id:
          $ref: "#/components/schemas/certId"
        digest:
          $ref: "#/components/schemas/sha256"

    certSignResponse:
      type: object
      required:
        - signature
      properties:
        signature:
          $ref: "#/components/schemas/base64"

    gpgKeysResponse:
      type: object
      required:
        - keys
      properties:
        keys:
          $ref: "#/components/schemas/gpgKeyFingerprintList"

    gpgNewRequest:
      type: object
      required:
        - name_real
        - name_email
      properties:
        name_real:
          $ref: "#/components/schemas/gpgKeyNameReal"
        name_email:
          $ref: "#/components/schemas/gpgKeyNameEmail"
        name_comment:
          $ref: "#/components/schemas/gpgKeyNameComment"
        key_length:
          $ref: "#/components/schemas/keyLength"

    gpgNewResponse:
      type: object
      required:
        - fingerprint
      properties:
        fingerprint:
          $ref: "#/components/schemas/gpgKeyFingerprint"

    gpgKeyResponse:
      type: object
      required:
        - key
      properties:
        key:
          $ref: "#/components/schemas/gpgKey"

    gpgSignRequest:
      type: object
      required:
        - key_id
        - payload
      properties:
        key_id:
          $ref: "#/components/schemas/gpgKeyFingerprint"
        payload:
          $ref: "#/components/schemas/base64"

    gpgSignResponse:
      type: object
      required:
        - signature
      properties:
        signature:
          $ref: "#/components/schemas/base64"

    rsaKey:
      type: string

    rsaKeyFingerprint:
      type: string
      pattern: "^[a-fA-F0-9]+$"
      example: "61D762833B1F104A4237E7E5B9C6464953950D96"

    rsaKeyFingerprintList:
      type: array
      items:
        $ref: "#/components/schemas/rsaKeyFingerprint"

    rsaKeysResponse:
      type: object
      required:
        - keys
      properties:
        keys:
          $ref: "#/components/schemas/rsaKeyFingerprintList"

    rsaNewRequest:
      type: object

    rsaNewResponse:
      type: object
      required:
        - fingerprint
      properties:
        fingerprint:
          $ref: "#/components/schemas/rsaKeyFingerprint"

    rsaKeyResponse:
      type: object
      required:
        - key
      properties:
        key:
          $ref: "#/components/schemas/rsaKey"

    rsaSignRequest:
      type: object
      required:
        - key_id
        - payload
      properties:
        key_id:
          $ref: "#/components/schemas/rsaKeyFingerprint"
        payload:
          $ref: "#/components/schemas/base64"

    rsaSignResponse:
      type: object
      required:
        - signature
      properties:
        signature:
          $ref: "#/components/schemas/base64"

    pkiId:
      type: string
      pattern: "^[a-fA-F0-9]+$"
      example: "61D762833B1F104A4237E7E5B9C6464953950D96"

    pkiIdList:
      type: array
      items:
        $ref: "#/components/schemas/pkiId"

    pkisResponse:
      type: object
      required:
        - pkis
      properties:
        pkis:
          $ref: "#/components/schemas/pkiIdList"

    pkiNewRequest:
      type: object
      required:
        - hab_type 
      properties:
        hab_type:
          $ref: "#/components/schemas/pkiHabType"

    pkiNewResponse:
      type: object
      required:
        - pki_id
      properties:
        pki_id:
          $ref: "#/components/schemas/pkiId"

    pkiHabType:
      type: string
      pattern: "^(hab|ahab)$"
      example: "hab"

    efusesResponse:
      type: object
      required:
        - efuses
      properties:
        efuses:
          $ref: "#/components/schemas/base64"

    cstRequest:
      type: object
      required:
        - pki_id
        - hab_type
        - payload
        - csf
      properties:
        pki_id:
          $ref: "#/components/schemas/pkiId"
        hab_type:
          $ref: "#/components/schemas/pkiHabType"
        payload:
          $ref: "#/components/schemas/base64"
        csf:
          $ref: "#/components/schemas/csf"

    cstResponse:
      type: object
      required:
        - csf_bin
      properties:
        csf_bin:
          $ref: "#/components/schemas/base64"

    certNewRequest:
      type: object
      required:
        - subject
        - cert_id
      properties:
        cert_id:
          $ref: "#/components/schemas/certId"
        subject:
          $ref: "#/components/schemas/certSubject"
        key_length:
          $ref: "#/components/schemas/keyLength"
        days:
          $ref: "#/components/schemas/certDays"

    certNewResponse:
      type: object
      required:
        - cert
      properties:
        cert:
          $ref: "#/components/schemas/certData"

    securebootPKResponse:
      type: object
      required:
        - pk
      properties:
        pk:
          $ref: "#/components/schemas/base64"

    securebootKEKResponse:
      type: object
      required:
        - kek
      properties:
        kek:
          $ref: "#/components/schemas/base64"

    securebootDbResponse:
      type: object
      required:
        - db
      properties:
        db:
          $ref: "#/components/schemas/base64"

    securebootInternalESLSignRequest:
      type: object
      required:
        - key_id
      properties:
        append:
          type: boolean
        key_id:
          oneOf:
            - $ref: "#/components/schemas/certId"
            - $ref: "#/components/schemas/certIdList"
        signing_key_id:
          $ref: "#/components/schemas/certId"

    securebootExternalESLSignRequest:
      type: object
      required:
        - esl
        - signing_key_id
      properties:
        append:
          type: boolean
        esl:
          $ref: "#/components/schemas/base64"
        signing_key_id:
          $ref: "#/components/schemas/certId"

    securebootESLSignResponse:
      type: object

    securebootSignRequest:
      type: object
      required:
        - key_id
        - payload
      properties:
        key_id:
          $ref: "#/components/schemas/certId"
        payload:
          $ref: "#/components/schemas/base64"

    securebootSignResponse:
      type: object
      required:
        - signed
      properties:
        signed:
          $ref: "#/components/schemas/base64"

    kmodCertResponse:
      type: object
      required:
        - cert
      properties:
        cert:
          type: string

    kmodSignRequest:
      type: object
      required:
        - key_id
        - payload
      properties:
        key_id:
          $ref: "#/components/schemas/certId"
        payload:
          $ref: "#/components/schemas/base64"

    kmodSignResponse:
      type: object
      required:
        - signed
      properties:
        signed:
          $ref: "#/components/schemas/base64"