nethsm-api.yaml

openapi: 3.0.0
info:
  title: NetHSM
  version: v1
  description: All endpoints expect exactly the specified JSON. Additional properties will cause a Bad Request Error (400). All HTTP errors contain a JSON structure with an explanation of type string. All <a href="https://tools.ietf.org/html/rfc4648#section-4">base64</a> encoded values are Big Endian.
servers:
  - url: https://{host}/api/{version}
    variables:
      host:
        default: nethsmdemo.nitrokey.com
      version:
        default: v1
paths:
  /info:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoData'
      description: Information about the vendor and product.
      x-annotation-state:
        - Locked
        - Operational
        - Unprovisioned
      x-annotation-role:
        - Public
  /health/alive:
    get:
      responses:
        '200':
          description: Yes, it is alive.
        '412':
          description: Not locked or unprovisioned (in operational state).
      description: Retrieve wether NetHSM is alive (powered up). This corresponds to the state <i>Locked</i> or <i>Unprovisioned</i>.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
        - Unprovisioned
  /health/ready:
    get:
      responses:
        '200':
          description: Yes, it is alive and ready.
        '412':
          description: Not alive and ready (not in operational state).
      description: Retrieve wether NetHSM is alive and ready to take traffic. This corresponds to the state <i>Operational</i>.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Operational
  /health/state:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStateData'
      description: Retrieve the state of NetHSM.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
        - Operational
        - Unprovisioned
  /metrics:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsData'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: 'Get metrics. Precondition: NetHSM is <i>Operational</i> and a <b>R-Metrics</b> can be authenticated.'
      security:
        - basic: []
      x-annotation-role:
        - Metrics
      x-annotation-state:
        - Operational
  /provision:
    post:
      responses:
        '204':
          description: Provisioning was successful, NetHSM is <i>Operational</i> now.
        '400':
          description: Malformed request data (e.g. malformed time, weak passphrase).
        '412':
          description: Precondition failed (NetHSM was not <i>Unprovisioned</i>).
      description: Initial provisioning, only available in <i>Unprovisioned</i> state.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionRequestData'
        required: true
      x-annotation-role:
        - Public
      x-annotation-state:
        - Unprovisioned
  /unlock:
    post:
      responses:
        '204':
          description: Unlock was successful, NetHSM is <i>Operational</i> now.
        '400':
          description: Bad request (invalid passphrase).
        '403':
          description: Unlock failed (access denied).
        '412':
          description: Precondition failed (NetHSM was not <i>Locked</i>).
      description: Brings a <i>Locked</i> NetHSM into <i>Operational</i> state.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlockRequestData'
        required: true
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
  /lock:
    post:
      responses:
        '204':
          description: Lock was successful, NetHSM is <i>Locked</i> now.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Lock failed (access denied).
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Brings an <i>Operational</i> NetHSM into <i>Locked</i> state.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /random:
    post:
      responses:
        '200':
          description: Successful request for <i>length</i> random bytes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RandomData'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: 'Retrieve cryptographically strong random bytes from NetHSM. Precondition: NetHSM is <i>Operational</i> and a <b>R-Operator</b> can be authenticated.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RandomRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Operator
      x-annotation-state:
        - Operational
  /keys:
    get:
      responses:
        '200':
          description: Successful request for the list of keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyList'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get a list of the identifiers of all keys that are currently stored in NetHSM. Separate requests need to be made to request the individual key data.
      parameters:
        - name: filter
          in: query
          description: Only return keys that are can be used by the requester, according to restrictions.
          schema:
            type: string
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
    post:
      responses:
        '201':
          description: Successful import of a private key. The response contains a Location header, e.g. "https://nethsm.local/v1/keys/I8mhHYJ1T3uk2lXrwXehVaw9KZzg7K".
        '400':
          description: Bad request (specified properties are invalid).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Import a private key into NetHSM and let NetHSM generate a KeyID. The public key will be automatically derived.
      requestBody:
        content:
          application/x-pem-file:
            schema:
              $ref: '#/components/schemas/PemPrivateKey'
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateKey'
        required: true
      parameters:
        - name: mechanisms
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/KeyMechanism'
        - name: tags
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ID'
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /keys/generate:
    post:
      responses:
        '201':
          description: Successful creation of new public and private key pair. Set Location header to the new KeyID.
        '400':
          description: Bad request (specified properties are invalid).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Generate a pair of public and private key and store it in NetHSM. KeyID is optional as a parameter and will be generated by NetHSM if not present.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyGenerateRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /keys/{KeyID}:
    get:
      responses:
        '200':
          description: |
            For response body with content type `application/json`:
            * *RSA* keys include `modulus` and `publicExponent` properties.
            * P* keys include the common format (0x04 followed by big-endian \
              encoded affine coordinates x and y).
            * Curve25519 keys are 32 byte, and follow the RFC8032 5.1.2 encoding \
              (little endian, x over y).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKey'
              examples:
                rsa:
                  summary: 'RSA'
                  value:
                    mechanisms:
                      - RSA_Signature_PSS_SHA256
                    type: RSA
                    restrictions:
                      tags:
                        - berlin
                    key:
                      modulus: FhJQl11CiY0ifRHXeAqFh4rdSl6
                      publicExponent: FhJQl11CiY0ifRHXeAqFh4rdSl6
                    operations: 242
                    
                ecdsa:
                  summary: 'P* Keys'
                  value:
                    mechanisms:
                      - ECDSA_Signature
                    type: EC_P224
                    operations: 242
                    restrictions:
                      tags:
                      - berlin
                    key:
                      data: BMKlPJ60PNFgsekRwg7n5mTIJkWWy6XLy0ORj14HumKi5qH63JaJzFOWLxYiaB6KH0NOgEKb7rUt
                eddsa:
                  summary: 'Curve25519'
                  value:
                    mechanisms:
                      - EdDSA_Signature
                    type: Curve25519
                    operations: 242
                    restrictions:
                      tags:
                      - berlin
                    key:
                      data: htnjTKRUz3XnLys5YD2+bKvzXZuu9cvXKwsCnWdzR+4=
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Retrieve the public key.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    put:
      responses:
        '204':
          description: Successful import of a private key.
        '400':
          description: Bad request (specified properties are invalid).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '409':
          description: Conflict, key already exists for this keyID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Import a private key into NetHSM and store it under the <i>KeyID</i> path. The public key will be automatically derived.
      requestBody:
        description: |
          For request body with content type `application/json`:
          * *RSA* includes `primeP`, `primeQ`, and `publicExponent` properties.
            The remaining properties `privateExponent`, `modulus`, ..) are computed.
          * *EC_P224*, *EC_P256*, *EC_P384*, *EC_P521* uses the `data` property.
            Keys are the raw (big endian) scalar.
          * *Curve25519* uses the `data` property.
            Keys are the raw (little endian) key.
        content:
          application/x-pem-file:
            schema:
              $ref: '#/components/schemas/PemPrivateKey'
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateKey'
            examples:
              rsa:
                summary: RSA
                value:
                  type: RSA
                  mechanisms:
                    - RSA_Signature_PSS_SHA256
                  key:
                    primeP: AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL
                    primeQ: ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv
                    publicExponent: AQAB
                  restrictions:
                    tags:
                      - berlin
              ecdsa:
                summary: P* Keys
                value:
                  type: EC_P224
                  mechanisms:
                    - ECDSA_Signature
                  key:
                    data: "BgcqhkjOPQIBBgUrgQQAIQM6AATZOhHS/Sed4w=="
                  restrictions:
                    tags:
                      - berlin
              eddsa:
                summary: Curve25519
                value:
                  type: Curve25519
                  mechanisms:
                    - EdDSA_Signature
                  key:
                    data: "m0o4HHT5tiwxxJ3hCzK6H9pXt9R854qyJ+q4Lmei/Kg="
                  restrictions:
                    tags:
                      - berlin
        required: true
      parameters:
        - name: mechanisms
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/KeyMechanism'
        - name: tags
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ID'
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: MyNewKey
    delete:
      responses:
        '204':
          description: Key was successfully deleted.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Delete a pair of public and private key.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/public.pem:
    get:
      responses:
        '200':
          description: |
            For response body with content type `application/x-pem-file`:
            * Returns the PEM encoded public key, as specified in PKCS #8.
          content:
            application/x-pem-file:
              schema:
                $ref: '#/components/schemas/PemPublicKey'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Retrieve public key in PEM format.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/csr.pem:
    post:
      responses:
        '200':
          description: Successful generation of certificate signing request.
          content:
            application/x-pem-file:
              schema:
                $ref: '#/components/schemas/PemCSR'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Retrieve a certificate signing request in PEM format.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistinguishedName'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/decrypt:
    post:
      responses:
        '200':
          description: |
            For response body with content type `application/json`:
            * Mode `RAW` returns the raw binary data.
            * Mode `PKCS1` returns the raw binary data.
            * Mode `OAEP_*` returns the raw binary data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecryptData'
        '400':
          description: |
            Bad Request, e.g. invalid encryption mode.
            * Mode `RAW` returns failure if input is bigger than key size.
            * Mode `PKCS1` returns failure if input is bigger than key size.
            * Mode `OAEP_*` returns failure is input is bigger than key size.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Decrypt an encrypted message with the secret key.
      requestBody:
        description: |
          For request body with content type `application/json`:
          * Mode `RAW` expects raw binary data.
          * Mode `PKCS1` expects PKCS1-encoded and padded binary data.
          * Mode `OAEP_*` expects EME-OAEP-encoded and padded binary data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecryptRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/encrypt:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptData'
        '400':
          description: Bad Request, e.g. invalid mechanism.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Encrypt a message with the secret key.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: MyAESKey
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/sign:
    post:
      responses:
        '200':
          description: |
            For response body with content type `application/json`:
            * Mode `PKCS1` returns the PKCS1 padded signature
              (no signatureAlgorithm OID prepended, since the used hash is not known).
            * Mode `PSS_*` returns the EMSA-PSS encoded signature.
            * Mode `EdDSA` returns the RFC 8032 (5.1.6) encoding:
              r appened with s, in total 64 bytes (each 32 bytes).
            * Mode `ECDSA` returns the ASN.1 DER encoded signature
              (a SEQUENCE of INTEGER r INTEGER s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignData'
        '400':
          description: |
            Bad Request, e.g. invalid signing mode.
            * Mode `PKCS1` returns failure if input is bigger than key size
            * Mode `PSS_*` returns failure if the input is not the hash length,
              or the private key is smaller than hash length.
            * Mode `ECDSA` returns failure if the input exceeds the group size in bits.
              The hash algorithm is not part of the encoding.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Key for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Sign a message with the secret key.
      requestBody:
        description: |
          For request body with content type `application/json`:
          * Mode `PKCS1` expects the already hashed data.
          * Mode `PSS_*` expects the already hashed data.
          * Mode `EdDSA` expects the raw message
            (ED25519 applies the SHA512 hash internally,
            also to derive the nonce).
          * Mode `ECDSA` expects the hashed data
            (using SHA224 for P224, SHA256 for P256,
            SHA384 for P384 and SHA512 for P521).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/cert:
    get:
      responses:
        '200':
          description: ''
          content:
            application/pgp-keys:
              schema:
                $ref: '#/components/schemas/PGPPrivateKey'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Certificate for KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Retrieve stored certificate. The content-type header will display the media type of the stored data.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    put:
      responses:
        '201':
          description: Successful import of a certificate.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '409':
          description: Conflict, certificate already exists for this KeyID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Store a certificate. Maximum size 1MB. The content-type header provides the media type. Only application/json, application/x-pem-file, application/x-x509-ca-cert, application/octet-stream, text/plain and application/pgp-keys is allowed.
      requestBody:
        content:
          application/x-pem-file:
            schema:
              $ref: '#/components/schemas/PemCert'
          application/x-x509-ca-cert:
            schema:
              type: string
          application/pgp-keys:
            schema:
              $ref: '#/components/schemas/PGPPrivateKey'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    delete:
      responses:
        '204':
          description: Successful deletion of a certificate.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Certificate with this KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Delete the certificate.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
        x-test-value: myKey1
  /keys/{KeyID}/restrictions/tags/{Tag}:
    put:
      responses:
        '204':
          description: Successful addition of the tag.
        '304':
          description: Tag is already present for this key.
        '400':
          description: Bad request, tag format is invalid.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: KeyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Add a tag to the authorized set
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
      x-test-value-Tag: MyNewTag
    delete:
      responses:
        '204':
          description: Successful deletion of the tag.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Tag or keyID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Delete a tag from the authorized set
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-KeyID: myKey1
      x-test-value-Tag: MyTag
    parameters:
      - name: Tag
        in: path
        required: true
        schema:
          type: string
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /users:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get a list of all user ids that have accounts on NetHSM.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    post:
      responses:
        '201':
          description: Successful creation of user. The response contains a Location header, e.g. "https://nethsm.local/v1/users/I8mhHYJ1T3uk2lXrwXehVaw9KZzg7K".
        '400':
          description: Bad request (specified properties are invalid, e.g. weak passphrase).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Create a new user on NetHSM. The user-ID is generated by NetHSM.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPostData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /users/{UserID}:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserData'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: User for UserID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: 'Get user info: name and role.'
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
    put:
      responses:
        '201':
          description: Successful creation of user.
        '400':
          description: Bad request (specified properties are invalid, e.g. weak passphrase).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '409':
          description: Conflict - user already exists for this user-ID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Create a user on keyfender.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPostData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-UserID: newOperator
    delete:
      responses:
        '204':
          description: Successful deletion of user.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: User not found for this user-ID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Delete a user from keyfender.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
    parameters:
      - name: UserID
        in: path
        required: true
        schema:
          type: string
  /users/{UserID}/passphrase:
    post:
      responses:
        '204':
          description: Successful change of passphrase.
        '400':
          description: Bad request - weak passphrase.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: User not found for this user-ID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Update the passphrase.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPassphrasePostData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
    parameters:
      - name: UserID
        in: path
        required: true
        schema:
          type: string
  /users/{UserID}/tags:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: User not found for this user-ID.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get the list of tags set to an Operator user.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
    parameters:
      - name: UserID
        in: path
        required: true
        schema:
          type: string
  /users/{UserID}/tags/{Tag}:
    put:
      responses:
        '204':
          description: Successful addition of the tag.
        '304':
          description: Tag is already present for this UserID.
        '400':
          description: Bad request, tag format is invalid or user is not an operator.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: UserID not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Add a tag to the Operator user.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
      x-test-value-Tag: munich
    delete:
      responses:
        '204':
          description: Successful deletion of the tag.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '404':
          description: Tag or user not found.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Delete a tag from the Operator user
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-test-value-UserID: operator
      x-test-value-Tag: berlin
    parameters:
      - name: UserID
        in: path
        required: true
        schema:
          type: string
      - name: Tag
        in: path
        required: true
        schema:
          type: string
  /config/unlock-passphrase:
    put:
      responses:
        '204':
          description: Successful change of passphrase.
        '400':
          description: Bad request - weak passphrase.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Update the unlock passphrase.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlockPassphraseConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/unattended-boot:
    get:
      responses:
        '200':
          description: Successful read of unattended boot configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnattendedBootConfig'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: 'Read unattended boot configuration: is it on or off?'
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    put:
      responses:
        '204':
          description: Successful change of unattended boot mode.
        '400':
          description: Bad request - invalid status setting.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: 'Configure unattended boot: switch it on or off (flip the switch).'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnattendedBootConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/tls/public.pem:
    get:
      responses:
        '200':
          description: Successful retrieval of public key.
          content:
            application/x-pem-file:
              schema:
                $ref: '#/components/schemas/PemPublicKey'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get public key for NetHSMs https API.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/tls/cert.pem:
    get:
      responses:
        '200':
          description: Successful retrieval of certificate.
          content:
            application/x-pem-file:
              schema:
                $ref: '#/components/schemas/PemCert'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get certificate for NetHSMs https API.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    put:
      responses:
        '201':
          description: Successfully set certificate.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Set certificate for NetHSMs https API e.g. to replace self-signed intital certificate.
      requestBody:
        content:
          application/x-pem-file:
            schema:
              $ref: '#/components/schemas/PemCert'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/tls/csr.pem:
    post:
      responses:
        '200':
          description: Successful generation of certificate signing request.
          content:
            application/x-pem-file:
              schema:
                $ref: '#/components/schemas/PemCSR'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get NetHSM certificate signing request e.g. to replace self-signed intital certificate.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistinguishedName'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/tls/generate:
    post:
      responses:
        '204':
          description: Successful creation of new public and private key pair for NetHSM's https API.
        '400':
          description: Bad request (specified properties are invalid).
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Generate a new pair of public and private key for NetHSM's https API.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TlsKeyGenerateRequestData'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/network:
    get:
      responses:
        '200':
          description: Successful retrieval of network configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkConfig'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get network configuration. IP address, netmask, router.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    put:
      responses:
        '204':
          description: Succesful update of network configuration.
        '400':
          description: Bad request - invalid input format.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Configure network.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/logging:
    get:
      responses:
        '200':
          description: Successful retrieval of logging configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoggingConfig'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get logging configuration. Protocol is always syslog over UDP. Configurable are IP adress and port, log level.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    put:
      responses:
        '204':
          description: Succesful update of logging configuration.
        '400':
          description: Bad request - invalid input format.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Configure log level and destination.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoggingConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/backup-passphrase:
    put:
      responses:
        '204':
          description: Successful change of passphrase.
        '400':
          description: Bad request - weak passphrase.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Update the backup passphrase.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupPassphraseConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /config/time:
    get:
      responses:
        '200':
          description: Successful retrieval of system time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeConfig'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get system time.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
    put:
      responses:
        '204':
          description: Succesful update of system time.
        '400':
          description: Bad request - invalid input format.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Configure system time.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeConfig'
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/info:
    get:
      responses:
        '200':
          description: Successful retrieval of system information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInfo'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Get detailed system information, including firmware version, system software version, hardware version.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/reboot:
    post:
      responses:
        '204':
          description: About to reboot NetHSM.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Reboot NetHSM.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/shutdown:
    post:
      responses:
        '204':
          description: About to shut down NetHSM.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Shut down NetHSM.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/factory-reset:
    post:
      responses:
        '204':
          description: About to reset NetHSM.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Reset NetHSM to factory settings.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/update:
    post:
      responses:
        '200':
          description: Successfully verified update image (authenticity, integrity, and version number).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemUpdateData'
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '409':
          description: Conflict - Major version downgrade is not allowed.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i>).
      description: Update NetHSM software.
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/commit-update:
    post:
      responses:
        '204':
          description: About to update NetHSM.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i> or update image is not present - call /update first).
      description: Commit update of NetHSM software.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/cancel-update:
    post:
      responses:
        '204':
          description: Update successfully cancelled.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i> or update image is not present - call /update first).
      description: Cancel update of NetHSM software.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
  /system/backup:
    post:
      responses:
        '200':
          description: Successful retrieval of backup data.
        '401':
          description: Authentication required but none provided.
        '403':
          description: Access denied.
        '412':
          description: Precondition failed (NetHSM was not <i>Operational</i> or <i>Backup Passphrase</i> was not set).
      description: Back up the key store to a backup file.
      security:
        - basic: []
      x-annotation-role:
        - Backup
      x-annotation-state:
        - Operational
  /system/restore:
    post:
      responses:
        '204':
          description: Successful restore from backup data.
        '400':
          description: Bad request - restore did not apply.
        '412':
          description: Precondition failed (NetHSM was not <i>Unprovisioned</i>).
      description: Restore the key store from a backup file. Only available in <i>Unprovisioned</i> state.
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
        required: true
      parameters:
        - name: backupPassphrase
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Passphrase'
        - name: systemTime
          in: query
          required: true
          schema:
            type: string
            format: date-time
      x-annotation-role:
        - Public
      x-annotation-state:
        - Unprovisioned
components:
  schemas:
    Passphrase:
      minLength: 1
      type: string
    ID:
      pattern: ^[a-zA-Z0-9]+$
      minLength: 1
      maxLength: 128
      type: string
    Base64:
      pattern: ^[a-zA-Z0-9+/]+={0,3}$
      type: string
    Switch:
      enum:
        - 'on'
        - 'off'
      type: string
    SystemState:
      enum:
        - Unprovisioned
        - Locked
        - Operational
      type: string
    UserRole:
      enum:
        - Administrator
        - Operator
        - Metrics
        - Backup
      type: string
    LogLevel:
      enum:
        - debug
        - info
        - warning
        - error
      type: string
    KeyType:
      enum:
        - RSA
        - Curve25519
        - EC_P224
        - EC_P256
        - EC_P384
        - EC_P521
        - Generic
      type: string
    TlsKeyType:
      enum:
        - RSA
        - Curve25519
        - EC_P224
        - EC_P256
        - EC_P384
        - EC_P521
      type: string
    KeyMechanism:
      enum:
        - RSA_Decryption_RAW
        - RSA_Decryption_PKCS1
        - RSA_Decryption_OAEP_MD5
        - RSA_Decryption_OAEP_SHA1
        - RSA_Decryption_OAEP_SHA224
        - RSA_Decryption_OAEP_SHA256
        - RSA_Decryption_OAEP_SHA384
        - RSA_Decryption_OAEP_SHA512
        - RSA_Signature_PKCS1
        - RSA_Signature_PSS_MD5
        - RSA_Signature_PSS_SHA1
        - RSA_Signature_PSS_SHA224
        - RSA_Signature_PSS_SHA256
        - RSA_Signature_PSS_SHA384
        - RSA_Signature_PSS_SHA512
        - EdDSA_Signature
        - ECDSA_Signature
        - AES_Encryption_CBC
        - AES_Decryption_CBC
      type: string
    EncryptMode:
      enum:
        - AES_CBC
      type: string
    DecryptMode:
      enum:
        - RAW
        - PKCS1
        - OAEP_MD5
        - OAEP_SHA1
        - OAEP_SHA224
        - OAEP_SHA256
        - OAEP_SHA384
        - OAEP_SHA512
        - AES_CBC
      type: string
    SignMode:
      enum:
        - PKCS1
        - PSS_MD5
        - PSS_SHA1
        - PSS_SHA224
        - PSS_SHA256
        - PSS_SHA384
        - PSS_SHA512
        - EdDSA
        - ECDSA
      type: string
    KeyList:
      example:
        - key: KeyID
      type: array
      items:
        $ref: '#/components/schemas/KeyItem'
    KeyItem:
      example:
        key: KeyID
      type: object
      properties:
        key:
          $ref: '#/components/schemas/ID'
      required:
        - key
    KeyRestrictions:
      type: object
      properties:
        tags:
          $ref: '#/components/schemas/TagList'
    UserList:
      example:
        - user: admin
        - user: backup
        - user: metrics
        - user: operator
      type: array
      items:
        $ref: '#/components/schemas/UserItem'
    UserItem:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/ID'
      required:
        - user
    TagList:
      example:
        - berlin
        - frankfurt
      type: array
      items:
        $ref: '#/components/schemas/ID'
    KeyMechanisms:
      type: array
      items:
        $ref: '#/components/schemas/KeyMechanism'
    PrivateKey:
      example:
        mechanisms:
          - RSA_Signature_PSS_SHA256
        type: RSA
        key:
          primeP: AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL
          primeQ: ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv
          publicExponent: AQAB
        restrictions:
          tags:
            - berlin
      type: object
      properties:
        mechanisms:
          $ref: '#/components/schemas/KeyMechanisms'
        type:
          $ref: '#/components/schemas/KeyType'
        key:
          $ref: '#/components/schemas/KeyPrivateData'
        restrictions:
          $ref: '#/components/schemas/KeyRestrictions'
      required:
        - mechanisms
        - type
        - key
    KeyPrivateData:
      type: object
      properties:
        primeP:
          $ref: '#/components/schemas/Base64'
        primeQ:
          $ref: '#/components/schemas/Base64'
        publicExponent:
          $ref: '#/components/schemas/Base64'
        data:
          $ref: '#/components/schemas/Base64'
    PublicKey:
      example:
        mechanisms:
          - RSA_Signature_PSS_SHA256
        type: RSA
        restrictions:
          tags:
            - berlin
        key:
          modulus: FhJQl11CiY0ifRHXeAqFh4rdSl6
          publicExponent: FhJQl11CiY0ifRHXeAqFh4rdSl6
        operations: 242
      type: object
      properties:
        mechanisms:
          $ref: '#/components/schemas/KeyMechanisms'
        type:
          $ref: '#/components/schemas/KeyType'
        restrictions:
          $ref: '#/components/schemas/KeyRestrictions'
        key:
          anyOf:
            - $ref: '#/components/schemas/KeyPublicData'
            - type: object
              nullable: true
        operations:
          type: integer
      required:
        - mechanisms
        - type
        - restrictions
        - key
        - operations
    KeyPublicData:
      type: object
      properties:
        modulus:
          $ref: '#/components/schemas/Base64'
        publicExponent:
          $ref: '#/components/schemas/Base64'
        data:
          $ref: '#/components/schemas/Base64'
    DistinguishedName:
      example:
        countryName: DE
        stateOrProvinceName: ''
        localityName: Berlin
        organizationName: Nitrokey
        organizationalUnitName: ''
        commonName: nethsm.local
        emailAddress: info@nitrokey.com
      type: object
      properties:
        countryName:
          type: string
        stateOrProvinceName:
          type: string
        localityName:
          type: string
        organizationName:
          type: string
        organizationalUnitName:
          type: string
        commonName:
          type: string
        emailAddress:
          type: string
      required:
        - commonName
    InfoData:
      example:
        vendor: Nitrokey GmbH
        product: NetHSM
      type: object
      properties:
        vendor:
          type: string
        product:
          type: string
      required:
        - vendor
        - product
    HealthStateData:
      example:
        state: Unprovisioned
      type: object
      properties:
        state:
          $ref: '#/components/schemas/SystemState'
      required:
        - state
    MetricsData:
      example:
        keyOperations: 1132412
        someOtherMetric: 2222
      type: object
    ProvisionRequestData:
      example:
        unlockPassphrase: UnlockPassphrase
        adminPassphrase: Administrator
        systemTime: '2018-10-30T11:20:50Z'
      type: object
      properties:
        unlockPassphrase:
          $ref: '#/components/schemas/Passphrase'
        adminPassphrase:
          $ref: '#/components/schemas/Passphrase'
        systemTime:
          type: string
          format: date-time
      required:
        - unlockPassphrase
        - adminPassphrase
        - systemTime
    UnlockRequestData:
      example:
        passphrase: UnlockPassphrase
      type: object
      properties:
        passphrase:
          $ref: '#/components/schemas/Passphrase'
      required:
        - passphrase
    RandomRequestData:
      example:
        length: 5
      type: object
      properties:
        length:
          minimum: 1
          maximum: 1024
          type: integer
      required:
        - length
    RandomData:
      example:
        random: VGhlIHE=
      type: object
      properties:
        random:
          $ref: '#/components/schemas/Base64'
      required:
        - random
    KeyGenerateRequestData:
      example:
        mechanisms:
          - RSA_Signature_PSS_SHA256
        type: RSA
        length: 2048
        id: myKey2
      type: object
      properties:
        mechanisms:
          $ref: '#/components/schemas/KeyMechanisms'
        type:
          $ref: '#/components/schemas/KeyType'
        length:
          minimum: 128
          maximum: 8192
          type: integer
        id:
          $ref: '#/components/schemas/ID'
        restrictions:
          $ref: '#/components/schemas/KeyRestrictions'
      required:
        - mechanisms
        - type
    TlsKeyGenerateRequestData:
      example:
        type: RSA
        length: 2048
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TlsKeyType'
        length:
          minimum: 128
          maximum: 8192
          type: integer
      required:
        - type
    EncryptRequestData:
      example:
        mode: AES_CBC
        message: nhrfotu32409ru0rgert45z54z099u23r03498uhtrq=
        iv: aYlwUI4A9zL9tjs4dMAq+A==
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/EncryptMode'
        message:
          $ref: '#/components/schemas/Base64'
        iv:
          $ref: '#/components/schemas/Base64'
      required:
        - mode
        - message
    EncryptData:
      example:
        encrypted: HQsTMBVvk19G9wrVQXPT0sDfjIglsJyZJl+VNWVSc0s=
        iv: aYlwUI4A9zL9tjs4dMAq+A==
      type: object
      properties:
        encrypted:
          $ref: '#/components/schemas/Base64'
        iv:
          $ref: '#/components/schemas/Base64'
      required:
        - encrypted
        - iv
    DecryptRequestData:
      example:
        mode: RAW
        encrypted: nhrfotu32409ru0rgert45z54z099u23r03498uhtr==
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/DecryptMode'
        encrypted:
          $ref: '#/components/schemas/Base64'
        iv:
          $ref: '#/components/schemas/Base64'
      required:
        - mode
        - encrypted
    DecryptData:
      example:
        decrypted: IBCS8Sc4NkG/O+kqInz7mq/+Pr+5eJUJ/QpfwMp7pPjLn02U7ggyUrxJfN97MChHGekvGEK4Q1LCJ2juHTgjxJ94/QoEAN0dWZ7x3NxjlUgw7yBm7ylldVvToum3lWOVo3wPm5ozSGxpslrqgz2Rid9+uH5ytV8//CrkMOlqlUoj0DWMYbp/sUbYDGwG8lcfvKua67AxT3X/exSKCAwBuxPBr2p3DCTHepdmZCyexL809ZvBRopOQ41ve9X1jXqKzihrCPeoCwEok06EGYhPt3/EKFoer401S0MYtz5J1BvO1cv7ITDOYUCG4Ze8aXEjtnt6MMRx4jY7IqssYO8GrA==
      type: object
      properties:
        decrypted:
          $ref: '#/components/schemas/Base64'
      required:
        - decrypted
    SignRequestData:
      example:
        mode: PKCS1
        message: nhrfotu32409ru0rgert45z54z099u23r03498uhtr==
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/SignMode'
        message:
          $ref: '#/components/schemas/Base64'
      required:
        - mode
        - message
    SignData:
      example:
        signature: n4geMX1g8zcfipfcmn+XjM1ccWZULemAa0cuYoh1aXG9UhbE6f54NMp4NjboLf63SQyieJYjjV8q+/o1rFlkZCtKtHAheds+g90zdjOMmXFlXyBTKMhGOSHuleGz0c99x7Alg19KN9wB3Jj2niwweBOR/F4Qv0mdBUv+oO8uPl6vM1fS4tX/VJoCZkDnZzL8duKRNFT0SNQZ+ryLiqQMG53fEPhTplK/wK0Cco8JAYCMh9cxSzpBoCEO+9woxoBGehAjHuLxs6ed6q08W67leuibxZ8c6Q6upmwDlca/gSw0y4w1VIxxts2PORZdNsTWcr3lojcNgWXJcfAqF9/n4A==
      type: object
      properties:
        signature:
          $ref: '#/components/schemas/Base64'
      required:
        - signature
    UserPostData:
      example:
        realName: Jane User
        role: Administrator
        passphrase: My cool passphrase
      type: object
      properties:
        realName:
          type: string
        role:
          $ref: '#/components/schemas/UserRole'
        passphrase:
          $ref: '#/components/schemas/Passphrase'
      required:
        - realName
        - role
        - passphrase
    UserData:
      example:
        realName: Jane User
        role: Administrator
      type: object
      properties:
        realName:
          type: string
        role:
          $ref: '#/components/schemas/UserRole'
      required:
        - realName
        - role
    UserPassphrasePostData:
      example:
        passphrase: Some cool new passphrase
      type: object
      properties:
        passphrase:
          $ref: '#/components/schemas/Passphrase'
      required:
        - passphrase
    UnlockPassphraseConfig:
      example:
        passphrase: This is my unlock passphrase
      type: object
      properties:
        passphrase:
          $ref: '#/components/schemas/Passphrase'
      required:
        - passphrase
    UnattendedBootConfig:
      example:
        status: 'off'
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Switch'
      required:
        - status
    NetworkConfig:
      example:
        ipAddress: 192.168.1.1
        netmask: 255.255.255.0
        gateway: 0.0.0.0
      type: object
      properties:
        ipAddress:
          type: string
        netmask:
          type: string
        gateway:
          type: string
      required:
        - ipAddress
        - netmask
        - gateway
    LoggingConfig:
      example:
        ipAddress: 0.0.0.0
        port: 514
        logLevel: info
      type: object
      properties:
        ipAddress:
          type: string
        port:
          type: integer
        logLevel:
          $ref: '#/components/schemas/LogLevel'
      required:
        - ipAddress
        - port
        - logLevel
    BackupPassphraseConfig:
      example:
        passphrase: This is my backup passphrase
      type: object
      properties:
        passphrase:
          $ref: '#/components/schemas/Passphrase'
      required:
        - passphrase
    TimeConfig:
      example:
        time: '2018-10-30T11:20:50Z'
      type: object
      properties:
        time:
          type: string
          format: date-time
      required:
        - time
    SystemInfo:
      example:
        firmwareVersion: N/A
        softwareVersion: '1.7'
        hardwareVersion: N/A
        buildTag: TAG-NN-g1234567-dirty
      type: object
      properties:
        firmwareVersion:
          type: string
        softwareVersion:
          type: string
        hardwareVersion:
          type: string
        buildTag:
          type: string
      required:
        - firmwareVersion
        - softwareVersion
        - hardwareVersion
        - buildTag
    SystemUpdateData:
      example:
        releaseNotes: Some new feature is available.
      type: object
      properties:
        releaseNotes:
          type: string
      required:
        - releaseNotes
    PemPrivateKey:
      example: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIEpAIBAAKCAQEAseU3o1Ix2euXUi50ht/mpDYnE2J4maJrIOLmDrmz+jv20hsR
        vPsWnKevYZqEYmvQFNO2Mv9DB5MZfnJ3jL3Aq71Ls1wqOnW9++bZAvqvEVUtlHh0
        5Rz9k1Ga32/OaHHEZj+lG9PlKI8y63K+sKZLuDYiVy1/gzARjpf2hCmTyQSAvtcA
        07WXAqorNI8mhcbIhnrGCeKfB8HYJ1T3uk2lXrwXehVaw9KZzg7KuRO0Qnk+IfR6
        LZjiKiEB9malzqSx3N20vibI672bMR+fqID2oC+ovNOEdRhPlCnztaY1HsnDhJt8
        MDTjlVGveCElvesuSVnNVHmVugDjEYTU1KV3TwIDAQABAoIBAQClSL5QDX9p5R28
        apMz+XYW3oWh2h0JScHVVVvBFMNm3S3vet0ZRAV3Wcl2mxUjSN6Vazte2JKTyBWo
        yXvQFUGdj4x1Qk2t8VWqZYr93KKqLQTjbKPXd/8WUHzf2sbhfcqn4bxrRY4mCB6c
        aglIocm6hvmTHB/caN33KbQOiX7ZBbwoZG3AKgoJU3SMXnVUfQzl/xnVrWLKESqm
        5kL0OTGLP091jZyMhcceh54RIuaJjPU4opL0bm46DLeQE4z20GfGCcRK/CUt4bNc
        c0wvuOyyzGI5p7QB/HCUJqR33m9ydwDkqC4vrORDxpMaSRNerpoGA+cNHREULh2P
        gaPydXq5AoGBAN3xIhci5LpIVvscNjPyxD6WQq5EZx251IzTnwQ/5E/+qxfYHvwe
        qAuLJ2+QvNQBuNKk85jwZsfUgPR6kku9dOt3n61lnrBRgGcqWnR0j8/NbpVe1qOe
        WArLeijpKKnCZ6uwpE6NND398dCmm3WLZZH64+1eLT8PbX/AIzId5zyzAoGBAM0x
        vWEsKi4pjNMBdaawJMbHEoDmMuib4t+FkbHDkqqSe/OIkHZ9tDQuHWpzDHmb30Na
        KNwQSNLwu3QK64z1NcjZUJFmu0+3NxSyI/EvNA9tiGCT5iSonsz04oa51AYt+IK5
        7JjMjo128INrQwtRFSYHx3hoVVW06tZNE037NiD1AoGABqeNOx5bt04l9X+CDIqx
        4aKFu03nvZdtzQ8nTGxR/ygGnz9mpm6Q4U+5zfmL/9tRXFd/yk0i98jiWPI34rd6
        gvjiO8O5P1YiQHWforBAA54IO8hNLTi5MRGqxwE+q+BdVWOFeal4MIelsXjdXmfg
        ksDwBpT1TFe9E8CCDaWh4ksCgYAhHCiR2H2J61x04+RnHD8i8BZ1RC/sxtKp/LSQ
        uZ0d9vsXRe8Bn7EHRnWqqpvVt6gkBxVWxS3rE7s7s1Nk8GBYY3CTtb790vOJXGFe
        Vp6Q6ry50MOvIKJXMiCnWq7yvFJATd32nfNWsl2G5zTvS4sdEt5F+Jfkd4f5QoCd
        8a4/TQKBgQDEdY3XTibkDt80zUFIP6RRAyfM6p2grk+o08De0BBZD/1GX9V9ARNT
        bC3+2qXXDYGxbMWgsoqsQTREJD78+sdD3q+IfIc1m7XvuIgyLMAalm+Kd1HlUF/J
        7VCKjgchT0OKwmi0d52TEOiz6U35Jv4GWBstsh1KVpHYiTnwnhAwKg==
        -----END RSA PRIVATE KEY-----
      type: string
    PemPublicKey:
      example: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx7ghfro+VEepYmy2V7HP
        n5PSRdmGzxewcpmzxTtrZ10BygbEqhPsAr4fWI9pG7iRXzeza7DMjrQptzKsfSy6
        dBFmSEZer+hJxuOdhBG/FX6pjwRrZpbOQxyr+aTlE3jm2XP12Cqx0wsYGIoJlWHb
        Gb90IAx9zpdYQgHoJZ4x5ims5vo7h3puPEyVycJH5fMBB9h+2Bxc4BxaPKMm15JR
        1B7ToB3g16SJY2B1t/aqNmqSBZC4HP1fCuSbBm83OgqRhdk1P6r/vqOVKrxVupDq
        Kkdcf/dRBiQalJ9tQbVbs9OOYfQ6n25GvJTvGtqOEuggit32tV16JXCZjnYePAvt
        NwIDAQAB
        -----END PUBLIC KEY-----
      type: string
    PemCSR:
      example: |
        -----BEGIN CERTIFICATE REQUEST-----
        MIICpzCCAY8CAQAwYjFgMAkGA1UEBhMCREUwDQYDVQQHDAZCZXJsaW4wDwYDVQQK
        DAhOaXRyb2tleTATBgNVBAMMDG5ldGhzbS5sb2NhbDAeBgkqhkiG9w0BCQEWEWlu
        Zm9Abml0cm9rZXkuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
        x7ghfro+VEepYmy2V7HPn5PSRdmGzxewcpmzxTtrZ10BygbEqhPsAr4fWI9pG7iR
        Xzeza7DMjrQptzKsfSy6dBFmSEZer+hJxuOdhBG/FX6pjwRrZpbOQxyr+aTlE3jm
        2XP12Cqx0wsYGIoJlWHbGb90IAx9zpdYQgHoJZ4x5ims5vo7h3puPEyVycJH5fMB
        B9h+2Bxc4BxaPKMm15JR1B7ToB3g16SJY2B1t/aqNmqSBZC4HP1fCuSbBm83OgqR
        hdk1P6r/vqOVKrxVupDqKkdcf/dRBiQalJ9tQbVbs9OOYfQ6n25GvJTvGtqOEugg
        it32tV16JXCZjnYePAvtNwIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBABVz67ib
        ngef9acHkwTYHHQk3MHxQRSLOxUKoDjk1URMgJ2hgL5HR91yQ3gBPxVuEGWdEQXJ
        C4sM9S3OoM5yFJFj56Y8MaASHFo58V5N1FaFqf3BbVKNzM4Jgrtghw1teJU45xZR
        0+sjA0YjVJwGnNXfBJdQVNXgWJcXy4bmPSaF7khxDnoP7dmxMcpQ2HKL8X9E/kef
        KOhz+HtlCWoqwD77aR3wKrYWdn+fwMeTRGNpJLPdKl7vyleb8pjtWUYnNTIP4Zh+
        BLX93udZxl8sVpJBnLcIWplwJB16hxk5ZODjWUOrhkwZ0MbiPFbKkihc8GMLLEyp
        dHRjrbgAUrx5DuY=
        -----END CERTIFICATE REQUEST-----
      type: string
    PemCert:
      example: |
        -----BEGIN CERTIFICATE-----
        MIIEvDCCAqQCCQCZ9VKHZSKydDANBgkqhkiG9w0BAQsFADAgMQ4wDAYDVQQIDAVo
        ZWxsbzEOMAwGA1UEBwwFaGVsbG8wHhcNMTgxMDMwMTI0MDQ3WhcNMTkxMDMwMTI0
        MDQ3WjAgMQ4wDAYDVQQIDAVoZWxsbzEOMAwGA1UEBwwFaGVsbG8wggIiMA0GCSqG
        SIb3DQEBAQUAA4ICDwAwggIKAoICAQC8WRImgeu4U6Yg5q0/SvoieQL5JwPHaCrN
        6Cc0mj8pnzTBu/f0QYNentcnu0EclD99kla6/gdiJnt0b/IT23o37+t2n0BvEgVQ
        MJxJ/BjIqSZCykq4SWHKia1OS7tJKE2Q/hgGq/RQJ0zecWKA9SuafXDt0plw0saz
        P8ZosFyToMYnPB54SzXj4qeD5t2L2dOamTTyziw/GJDGdwssImEDfeWyMRRyHcIa
        u9HNGaTxjCdBGzCR+PEX3ZHhGzl5iMlgtZUICgXMgAvFZHHEYNtyCW9ZzUB2ZKE2
        nMbu8hbl7GXRCdJaAqlJfKiGp/WvbmrLhCzcwqhu4UnqGXOxeEQryrkPAbiLafqb
        fPLHB7dr8OEGlUzp1SCHR1JxwdBVohuO2lL+O5nMD3ZVdVnh2F5Et6I9lO4w9+5n
        aI6pmO4oy9PsqKvUjxVnEeo1Ee1n9o/4T6fe6XBIQLPqEmy2IXynZP0eJn1Yu9SF
        TkTSmJ+jRiU7EMaagQrM4Ds5seVNVWKOvUjDQCV+QRZaaPcrkMoFtjLCVMhLgy7M
        /Dfl63qCcdVkPwdbI/apjfG8qMrez4k3qAZDYgS3fujyuq9wv7xbq2+o0Ck4Ono2
        mMAA6JDSZr8XwR3ac/UK1KGv+weh1fOVO+c6mSN9M+W1MtkJS+i4/Aj2yDCJzVk3
        GZpd5/E6WwIDAQABMA0GCSqGSIb3DQEBCwUAA4ICAQAB+8+1dk20P6R+RvDRs1mo
        e1CegaPH2bl9t1WVuXJIUkrIGDceVr5f19pcaNQRYwZuoQd8VQXCZUpWbo//TWxl
        ItS3prQgcrfcTi7gCzp1+q1bZk6H21tzESDJTXPFp019/ypdUB4Jsty7qQL73sE3
        nj67DH+srPCknAhfFag0dPOOjAY19IrIomtBMlvYNpb5XupEUAQFCjk6VdLVAzzl
        M5Swj+kmLA0OUHTF2zAwj2k+B9RAkbetu/lXLwUiiQNG00j8YP03lErxDd29m2jl
        NFlSn8YYsgzmihF5fUFTJXP5tS7lF4FnLNbw9pfdeVZBT1uTOcckmFv6n6edttZS
        FhC70hBB8tFFtemGFquZ0N7w8O7DmIYI936n283rzxyuWdi+JqOUQ0KzpGbFOP3t
        AOdVcx/JW8kjDdWRcRDr85M4MnkG6HEzW4uzGBtxBplL7KH0L8LX+lx6ySjIrbRD
        QtwBxwZGtHZJAqskO6vobzzybCKuVUaQwkPrQsK5iLA6Nn1Yxu6XmtlvoPeNIc63
        Pa3ix8vNFbBTtS6iBdbOPse5qgRV0DC94ocedzKw4QzQRa5REIniJ2X8hVoVAcBh
        3nQKyZApl2I/pZMlbZ0Cg5yxjhBaxKwci7jyoMerMMo2EdbZN87gP+2x6tKuY1MO
        35mqzHn+FjWq0eAtpzhO5Q==
        -----END CERTIFICATE-----
      type: string
    PGPPrivateKey:
      example: |
        -----BEGIN PGP PRIVATE KEY BLOCK-----
        Version: GnuPG v2

        MIIEvDCCAqQCCQCZ9VKHZSKydDANBgkqhkiG9w0BAQsFADAgMQ4wDAYDVQQIDAVo
        ZWxsbzEOMAwGA1UEBwwFaGVsbG8wHhcNMTgxMDMwMTI0MDQ3WhcNMTkxMDMwMTI0
        MDQ3WjAgMQ4wDAYDVQQIDAVoZWxsbzEOMAwGA1UEBwwFaGVsbG8wggIiMA0GCSqG
        SIb3DQEBAQUAA4ICDwAwggIKAoICAQC8WRImgeu4U6Yg5q0/SvoieQL5JwPHaCrN
        6Cc0mj8pnzTBu/f0QYNentcnu0EclD99kla6/gdiJnt0b/IT23o37+t2n0BvEgVQ
        MJxJ/BjIqSZCykq4SWHKia1OS7tJKE2Q/hgGq/RQJ0zecWKA9SuafXDt0plw0saz
        P8ZosFyToMYnPB54SzXj4qeD5t2L2dOamTTyziw/GJDGdwssImEDfeWyMRRyHcIa
        u9HNGaTxjCdBGzCR+PEX3ZHhGzl5iMlgtZUICgXMgAvFZHHEYNtyCW9ZzUB2ZKE2
        nMbu8hbl7GXRCdJaAqlJfKiGp/WvbmrLhCzcwqhu4UnqGXOxeEQryrkPAbiLafqb
        fPLHB7dr8OEGlUzp1SCHR1JxwdBVohuO2lL+O5nMD3ZVdVnh2F5Et6I9lO4w9+5n
        aI6pmO4oy9PsqKvUjxVnEeo1Ee1n9o/4T6fe6XBIQLPqEmy2IXynZP0eJn1Yu9SF
        TkTSmJ+jRiU7EMaagQrM4Ds5seVNVWKOvUjDQCV+QRZaaPcrkMoFtjLCVMhLgy7M
        /Dfl63qCcdVkPwdbI/apjfG8qMrez4k3qAZDYgS3fujyuq9wv7xbq2+o0Ck4Ono2
        mMAA6JDSZr8XwR3ac/UK1KGv+weh1fOVO+c6mSN9M+W1MtkJS+i4/Aj2yDCJzVk3
        GZpd5/E6WwIDAQABMA0GCSqGSIb3DQEBCwUAA4ICAQAB+8+1dk20P6R+RvDRs1mo
        e1CegaPH2bl9t1WVuXJIUkrIGDceVr5f19pcaNQRYwZuoQd8VQXCZUpWbo//TWxl
        ItS3prQgcrfcTi7gCzp1+q1bZk6H21tzESDJTXPFp019/ypdUB4Jsty7qQL73sE3
        nj67DH+srPCknAhfFag0dPOOjAY19IrIomtBMlvYNpb5XupEUAQFCjk6VdLVAzzl
        M5Swj+kmLA0OUHTF2zAwj2k+B9RAkbetu/lXLwUiiQNG00j8YP03lErxDd29m2jl
        NFlSn8YYsgzmihF5fUFTJXP5tS7lF4FnLNbw9pfdeVZBT1uTOcckmFv6n6edttZS
        FhC70hBB8tFFtemGFquZ0N7w8O7DmIYI936n283rzxyuWdi+JqOUQ0KzpGbFOP3t
        AOdVcx/JW8kjDdWRcRDr85M4MnkG6HEzW4uzGBtxBplL7KH0L8LX+lx6ySjIrbRD
        QtwBxwZGtHZJAqskO6vobzzybCKuVUaQwkPrQsK5iLA6Nn1Yxu6XmtlvoPeNIc63
        Pa3ix8vNFbBTtS6iBdbOPse5qgRV0DC94ocedzKw4QzQRa5REIniJ2X8hVoVAcBh
        3nQKyZApl2I/pZMlbZ0Cg5yxjhBaxKwci7jyoMerMMo2EdbZN87gP+2x6tKuY1MO
        35mqzHn+FjWq0eAtpzhO5Q==
        -----END PGP PRIVATE KEY BLOCK-----
      type: string
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes:
    basic:
      description: |
        NetHSM supports Basic Authentication.
      type: http
      scheme: basic
  links: {}
  callbacks: {}