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 [base64](https://tools.ietf.org/html/rfc4648#section-4) 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"
        "406":
          description: Content type in Accept header not supported.
      description: Information about the vendor and product.
      x-annotation-state:
        - Locked
        - Operational
        - Unprovisioned
      x-annotation-role:
        - Public
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /health/alive:
    get:
      responses:
        "200":
          description: NetHSM is fully started and in state *Locked* or *Unprovisioned*.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: NetHSM is not in state *Locked* or *Unprovisioned*.
      description: |
        Retrieve whether NetHSM is fully started but not ready to take traffic.
        This corresponds to the state *Locked* or *Unprovisioned*.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
        - Unprovisioned
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /health/ready:
    get:
      responses:
        "200":
          description: NetHSM is in state *Operational*.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: NetHSM is not in state *Operational*.
      description: |
        Retrieve whether NetHSM is in state *Operational* and thus ready to take traffic.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /health/state:
    get:
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStateData"
        "406":
          description: Content type in Accept header not supported.
      description: Retrieve the state of NetHSM.
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
        - Operational
        - Unprovisioned
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /metrics:
    get:
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetricsData"
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Get metrics.
        Precondition: NetHSM is *Operational* and a **R-Metrics** can be authenticated.
      security:
        - basic: []
      x-annotation-role:
        - Metrics
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /provision:
    post:
      responses:
        "204":
          description: Provisioning was successful, NetHSM is *Operational* now.
        "400":
          description: Malformed request data (e.g. malformed time, weak passphrase).
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Unprovisioned*).
      description: |-
        Initial provisioning, only available in *Unprovisioned* state.

        *WARNING:* The unlock passphrase can't be reset by an admin user without
        knowing the current value, so if the unlock passphrase is lost, neither
        can it be reset to a new value nor can the NetHSM be unlocked.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProvisionRequestData"
        required: true
      x-annotation-role:
        - Public
      x-annotation-state:
        - Unprovisioned
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /unlock:
    post:
      responses:
        "204":
          description: Unlock was successful, NetHSM is *Operational* now.
        "400":
          description: Bad request (invalid passphrase).
        "403":
          description: Unlock failed (access denied).
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Locked*).
      description: Brings a *Locked* NetHSM into *Operational* state.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnlockRequestData"
        required: true
      x-annotation-role:
        - Public
      x-annotation-state:
        - Locked
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /lock:
    post:
      responses:
        "204":
          description: Lock was successful, NetHSM is *Locked* now.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Lock failed (access denied, e.g. user is in a namespace).
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Brings an *Operational* NetHSM into *Locked* state.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /random:
    post:
      responses:
        "200":
          description: Successful request for *length* random bytes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RandomData"
        "400":
          description: Bad request (invalid length).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Retrieve cryptographically strong random bytes from NetHSM.
        Precondition: NetHSM is *Operational* and a **R-Operator** can be authenticated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RandomRequestData"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Operator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /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.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Get a list of the identifiers of all keys that are currently stored in NetHSM.
        If the caller is in a namespace, only keys in that namespace are returned.
        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
      x-annotation-caller-namespace:
        - Root
        - Namespaced
    post:
      responses:
        "201":
          headers:
            location:
              description: Where to find the newly added key.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateResourceId"
          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.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Import a private key into NetHSM and let NetHSM generate a KeyID.
        The public key will be automatically derived.
        The parameters of the key can be passed as a PEM file or a JSON object.
        The key is stored in the caller's namespace.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrivateKey"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/PrivateKeyPem"
            encoding:
              key_file:
                contentType: application/x-pem-file
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /keys/generate:
    post:
      responses:
        "201":
          description: |
            Successful creation of new public and private key pair.
            Set Location header to the new KeyID.
          headers:
            location:
              description: Where to find the newly added key.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateResourceId"
        "400":
          description: Bad request (specified properties are invalid).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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.
        The key is stored in the caller's namespace.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KeyGenerateRequestData"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /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
                    public:
                      modulus: FhJQl11CiY0ifRHXeAqFh4rdSl6
                      publicExponent: FhJQl11CiY0ifRHXeAqFh4rdSl6
                    operations: 242

                ecdsa:
                  summary: "P* Keys"
                  value:
                    mechanisms:
                      - ECDSA_Signature
                    type: EC_P224
                    operations: 242
                    restrictions:
                      tags:
                        - berlin
                    public:
                      data: BMKlPJ60PNFgsekRwg7n5mTIJkWWy6XLy0ORj14HumKi5qH63JaJzFOWLxYiaB6KH0NOgEKb7rUt
                eddsa:
                  summary: "Curve25519"
                  value:
                    mechanisms:
                      - EdDSA_Signature
                    type: Curve25519
                    operations: 242
                    restrictions:
                      tags:
                        - berlin
                    public:
                      data: htnjTKRUz3XnLys5YD2+bKvzXZuu9cvXKwsCnWdzR+4=
                generic:
                  summary: Generic
                  value:
                    mechanisms:
                      - AES_Encryption_CBC
                      - AES_Decryption_CBC
                    type: Generic
                    operations: 242
                    restrictions:
                      tags:
                        - berlin
        "400":
          description: Invalid character in the KeyID.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "404":
          description: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Retrieve the public key.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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.
        "406":
          description: Content type in Accept header not supported.
        "409":
          description: Conflict, key already exists for this keyID.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Import a private key into NetHSM and store it under the *KeyID* path.
        The public key will be automatically derived.
        The parameters of the key can be passed as a PEM file or a JSON object.
        The key is stored in the caller's namespace.
      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/json:
            schema:
              $ref: "#/components/schemas/PrivateKey"
            examples:
              rsa:
                summary: RSA
                value:
                  type: RSA
                  mechanisms:
                    - RSA_Signature_PSS_SHA256
                  private:
                    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
                  private:
                    data: "BgcqhkjOPQIBBgUrgQQAIQM6AATZOhHS/Sed4w=="
                  restrictions:
                    tags:
                      - berlin
              eddsa:
                summary: Curve25519
                value:
                  type: Curve25519
                  mechanisms:
                    - EdDSA_Signature
                  private:
                    data: "m0o4HHT5tiwxxJ3hCzK6H9pXt9R854qyJ+q4Lmei/Kg="
                  restrictions:
                    tags:
                      - berlin
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/PrivateKeyPem"
            encoding:
              key_file:
                contentType: application/x-pem-file
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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 in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Delete a pair of public and private key.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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"
        "400":
          description: Invalid character in the KeyID.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "404":
          description: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Retrieve public key in PEM format.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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"
        "400":
          description: Bad request (specified properties are invalid).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "404":
          description: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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-caller-namespace:
        - Root
        - Namespaced
      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 in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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-annotation-caller-namespace:
        - Root
        - Namespaced
      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 in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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-annotation-caller-namespace:
        - Root
        - Namespaced
      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 in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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-annotation-caller-namespace:
        - Root
        - Namespaced
      x-test-value-KeyID: myKey1
    parameters:
      - name: KeyID
        in: path
        required: true
        schema:
          type: string
  /keys/{KeyID}/cert:
    get:
      responses:
        "200":
          description: ""
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
        "400":
          description: Invalid character in the KeyID.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "404":
          description: Key for KeyID not found in namespace.
        "406":
          description: Content-Type in Accept header is not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Retrieve a stored certificate in the exact format it was stored.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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.
        "406":
          description: Content type in Accept header not supported.
        "409":
          description: Conflict, certificate already exists for this KeyID.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Store a certificate.
        Maximum size 1MB.
        The Content-Type must be application/octet-stream.
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Delete the certificate.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Add a tag to the authorized set
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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: Key for KeyID not found in namespace.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Delete a tag from the authorized set
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      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
  /namespaces:
    get:
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NamespaceList"
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. the caller is in a namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Get a list of all created namespaces. Note that users may be assigned namespaces
        not present in this list, as long as the namespace has not been created.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /namespaces/{NamespaceID}:
    put:
      responses:
        "204":
          description: Successful creation of namespace.
        "400":
          description: |
            Bad request (specified properties are invalid, e.g. invalid namespace name
            or namespace already exists).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user in a namespace or not an admin).
        "406":
          description: Content type in Accept header not supported.
        "409":
          description: Conflict - user already exists for this user-ID.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Create a namespace on keyfender. All users in that namespace can now be used, and all user management
        power is delegated to admins in that namespace.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
      x-test-value-NamespaceID: namespace3
    delete:
      responses:
        "204":
          description: Successful deletion of namespace.
        "400":
          description: Bad request.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user in a namespace or not an admin).
        "404":
          description: Namespace not found.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: "Delete a namespace. **WARNING: all keys from that namespace are deleted.**"
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
      x-test-value-NamespaceID: namespace1
    parameters:
      - name: NamespaceID
        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.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Get a list of all user ids that have accounts on NetHSM.
        If the caller is in a namespace, return only users in that namespace.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
    post:
      responses:
        "201":
          description: |
            Successful creation of user.
            The response contains a Location header,
            e.g. "https://nethsm.local/v1/users/I8mhHYJ1T3uk2lXrwXehVaw9KZzg7K".
          headers:
            location:
              description: Where to find the newly added user.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateResourceId"
        "400":
          description: Bad request (specified properties are invalid, e.g. weak passphrase).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. caller not administrator, or creating user in namespace not matching the caller's).
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Create a new user on NetHSM, inheriting the caller's namespace.
        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
      x-annotation-caller-namespace:
        - Root
        - Namespaced
  /users/{UserID}:
    get:
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserData"

        "400":
          description: Invalid character in the UserID.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user not in the same namespace)
        "404":
          description: User for UserID not found.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: "Get user info: name and role."
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
        - CallerIsRoot
      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 (e.g. caller not administrator, or creating user in namespace not matching the caller's).
        "406":
          description: Content type in Accept header not supported.
        "409":
          description: Conflict - user already exists for this user-ID.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Create a user on keyfender. The new user must either be in the same namespace as the caller,
        or be in a namespace not created yet if the caller has no namespace.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserPostData"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-test-value-UserID: newOperator
    post:
      responses:
        "201":
          description: |
            Successful creation of user.
            The response contains a Location header,
            e.g. "https://nethsm.local/v1/users/namespace1~I8mhHYJ1T3uk2lXrwXehVaw9KZzg7K".
          headers:
            location:
              description: Where to find the newly added user.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateResourceId"
        "400":
          description: Bad request (specified properties are invalid, e.g. weak passphrase).
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. caller not administrator, or creating user in namespace not matching the caller's).
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Create a new user on NetHSM, in the namespace specified as a prefix in the path with the format 'namespace~'.
        For example, a POST request on "https://nethsm.local/v1/users/namespace1~" will generate a user-ID and create that
        user in "namespace1". The namespace prefix *must* be present: for creating users without a namespace, use a POST on "/v1/users".
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserPostData"
        required: true
      security:
        - basic: []
      x-test-value-UserID: namespace3~
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
    delete:
      responses:
        "204":
          description: Successful deletion of user.
        "400":
          description: Bad request (cannot delete yourself)
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user not in the same namespace)
        "404":
          description: User not found for this user-ID.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Delete a user from keyfender.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
      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 (e.g. user not in the same namespace)
        "404":
          description: User not found for this user-ID.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
      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"
        "400":
          description: Invalid character in the UserID.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user not in the same namespace)
        "404":
          description: User not found for this user-ID.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Get the list of tags set to an Operator user.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
        - Operator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
        - CallerIsRoot
      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 (e.g. user not in the same namespace)
        "404":
          description: UserID not found.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Add a tag to the Operator user.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
      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 (e.g. user not in the same namespace)
        "404":
          description: Tag or user not found.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Delete a tag from the Operator user
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
      x-annotation-target-namespace:
        - SameAsCaller
      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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |-
        Update the unlock passphrase.

        *WARNING:* The unlock passphrase can't be reset by an admin user without
        knowing the current value, so if the unlock passphrase is lost, neither
        can it be reset to a new value nor can the NetHSM be unlocked.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnlockPassphraseConfig"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: "Read unattended boot configuration: is it on or off?"
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
    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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Get public key for NetHSMs https API.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
        "415":
          description: Content type in Accept header not supported or not present.
      description: Get certificate for NetHSMs https API.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
    put:
      responses:
        "201":
          description: Successfully set certificate.
        "400":
          description: Certificate malformed.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Get network configuration. IP address, netmask, router.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
    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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Configure network.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NetworkConfig"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
    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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |-
        Update the backup passphrase. If the backup passphrase is not set yet,
        use "" as currentPassphrase.

        *WARNING:* Like the unlock passphrase, this configuration can't be reset
        by an admin user without knowing the current value, so if the backup
        passphrase is lost, neither can it be reset to a new value nor can the
        created backups be restored.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BackupPassphraseConfig"
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Get system time.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
    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 (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      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
      x-annotation-caller-namespace:
        - Root
  /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.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: |
        Get detailed system information, including firmware, system, and hardware version.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/reboot:
    post:
      responses:
        "204":
          description: About to reboot NetHSM.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Reboot NetHSM.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/shutdown:
    post:
      responses:
        "204":
          description: About to shut down NetHSM.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Shut down NetHSM.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/factory-reset:
    post:
      responses:
        "204":
          description: About to reset NetHSM.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Reset NetHSM to factory settings.
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/update:
    post:
      responses:
        "200":
          description: Successfully verified update image (authenticity, integrity, and version number).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemUpdateData"
        "400":
          description: Update malformed.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "409":
          description: Conflict - Major version downgrade is not allowed.
        "412":
          description: Precondition failed (NetHSM was not *Operational*).
      description: Update NetHSM software.
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        required: true
      security:
        - basic: []
      x-annotation-role:
        - Administrator
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/commit-update:
    post:
      responses:
        "204":
          description: About to update NetHSM.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: |
            Precondition failed (NetHSM was not *Operational* 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
      x-annotation-caller-namespace:
        - Root
  /system/cancel-update:
    post:
      responses:
        "204":
          description: Update successfully cancelled.
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: |
            Precondition failed (NetHSM was not *Operational* 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
      x-annotation-caller-namespace:
        - Root
  /system/backup:
    post:
      responses:
        "200":
          description: Successful retrieval of backup data.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          description: Authentication required but none provided.
        "403":
          description: Access denied (e.g. user is in namespace)
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: |
            Precondition failed (NetHSM was not *Operational* or
            *Backup Passphrase* was not set).
      description: Back up the key store to a backup file.
      security:
        - basic: []
      x-annotation-role:
        - Backup
      x-annotation-state:
        - Operational
      x-annotation-caller-namespace:
        - Root
  /system/restore:
    post:
      responses:
        "204":
          description: Successful restore from backup data.
        "400":
          description: Bad request - restore did not apply.
        "406":
          description: Content type in Accept header not supported.
        "412":
          description: |
            Precondition failed (NetHSM was not *Unprovisioned* or
            *Operational*).
      description: |
        Restore the key store and user store from a backup file. If NetHSM is
        *Unprovisioned*, then the configuration is restored.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/RestoreRequest"
      security:
        - {}         # for complete restore
        - basic: []  # for partial restore
      x-annotation-role:
        - Public
      x-annotation-state:
        - Unprovisioned
        - Operational
      x-annotation-caller-namespace:
        - Root
        - Namespaced
components:
  schemas:
    AkPub:
      example:
        P256: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEup7z8QYvkzkBuLryG1SgVQjlPhSFW3PzYn1l3uLNd+pSBxX0OBpslcbnmPFr5wSs/iP46+H8MFlEAYUkYv6uuQ==
        P384: MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEfQiurLvEmjsAmumRtIqu70HKehRo8A/nVrqQGiR8Rcr+SUujwgtQByORX5BoRtv4sZNJW4FyLGqvXCIF9IV1puob2+9Qq5oEjz4x4malLbFdyXDmQK8o2NpvcbgOr215
      type: object
      properties:
        P256:
          type: string
        P384:
          type: string
    Pcr:
      example:
        0: 0f6064779fba55b102a6ecc20498c2020deaf2aebef23716ec293b25873647f8
        2: 2b0d25a4a92b4df5205742954243db9d306a4c3277a6b6958bcbaf3d47def26f
      type: object
      properties:
        0:
          type: string
        2:
          type: string
    Passphrase:
      minLength: 10
      type: string
    ID:
      pattern: ^[a-zA-Z0-9]+$
      minLength: 1
      maxLength: 128
      type: string
    UserID:
      pattern: ^([a-zA-Z0-9]+~)?[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
    CreateResourceId:
      example:
        id: ab0d5df406ddad1075ab
      type: object
      properties:
        id:
          type: string
      required:
        - id
    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:
        - id: KeyID
      type: array
      items:
        $ref: "#/components/schemas/KeyItem"
    KeyItem:
      example:
        id: KeyID
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
      required:
        - id
    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/UserID"
      required:
        - user
    NamespaceList:
      example:
        - id: namespace1
      type: array
      items:
        $ref: "#/components/schemas/NamespaceItem"
    NamespaceItem:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ID"
      required:
        - id
    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
        private:
          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"
        private:
          $ref: "#/components/schemas/KeyPrivateData"
        restrictions:
          $ref: "#/components/schemas/KeyRestrictions"
      required:
        - mechanisms
        - type
        - private
    PrivateKeyPem:
      example:
        arguments:
          mechanisms:
            - RSA_Signature_PSS_SHA256
          restrictions:
            tags:
              - munich
        key_file: privatekey.pem
      type: object
      properties:
        arguments:
          type: object
          properties:
            mechanisms:
              $ref: "#/components/schemas/KeyMechanisms"
            restrictions:
              $ref: "#/components/schemas/KeyRestrictions"
        key_file:
          $ref: "#/components/schemas/PemPrivateKey"
    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
        public:
          modulus: FhJQl11CiY0ifRHXeAqFh4rdSl6
          publicExponent: FhJQl11CiY0ifRHXeAqFh4rdSl6
        operations: 242
      type: object
      properties:
        mechanisms:
          $ref: "#/components/schemas/KeyMechanisms"
        type:
          $ref: "#/components/schemas/KeyType"
        restrictions:
          $ref: "#/components/schemas/KeyRestrictions"
        public:
          $ref: "#/components/schemas/KeyPublicData"
        operations:
          type: integer
      required:
        - mechanisms
        - type
        - restrictions
        - operations
    KeyPublicData:
      description: |
        The public key data is either a *modulus* and a *publicExponent* or
        a *data* field. The *data* field is used for EC keys.
        This field is null for Generic keys.
      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:
        newPassphrase: This is my new unlock passphrase
        currentPassphrase: UnlockPassphrase
      type: object
      properties:
        newPassphrase:
          $ref: "#/components/schemas/Passphrase"
        currentPassphrase:
          type: string
      required:
        - newPassphrase
        - currentPassphrase
    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:
        newPassphrase: This is my new backup passphrase
        currentPassphrase: backupPassphrase
      type: object
      properties:
        newPassphrase:
          $ref: "#/components/schemas/Passphrase"
        currentPassphrase:
          type: string
      required:
        - newPassphrase
        - currentPassphrase
    RestoreRequest:
      type: object
      properties:
        arguments:
          type: object
          properties:
            backupPassphrase:
              $ref: "#/components/schemas/Passphrase"
            systemTime:
              type: string
              format: date-time
        backup_file:
          type: string
          format: binary
    TimeConfig:
      example:
        time: "2018-10-30T11:20:50Z"
      type: object
      properties:
        time:
          type: string
          format: date-time
      required:
        - time
    SystemInfo:
      example:
        softwareVersion: "1.7"
        softwareBuild: f3f6292
        firmwareVersion: 1.0-devel
        hardwareVersion: prodrive-hermes-1.0
        deviceId: 5UMIP364R2
        akPub:
          P256: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEup7z8QYvkzkBuLryG1SgVQjlPhSFW3PzYn1l3uLNd+pSBxX0OBpslcbnmPFr5wSs/iP46+H8MFlEAYUkYv6uuQ==
          P384: MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEfQiurLvEmjsAmumRtIqu70HKehRo8A/nVrqQGiR8Rcr+SUujwgtQByORX5BoRtv4sZNJW4FyLGqvXCIF9IV1puob2+9Qq5oEjz4x4malLbFdyXDmQK8o2NpvcbgOr215
        pcr:
          0: 0f6064779fba55b102a6ecc20498c2020deaf2aebef23716ec293b25873647f8
          2: 2b0d25a4a92b4df5205742954243db9d306a4c3277a6b6958bcbaf3d47def26f
      type: object
      properties:
        softwareVersion:
          type: string
        softwareBuild:
          type: string
        firmwareVersion:
          type: string
        hardwareVersion:
          type: string
        deviceId:
          type: string
        akPub:
          $ref: "#/components/schemas/AkPub"
        pcr:
          $ref: "#/components/schemas/Pcr"
      required:
        - softwareVersion
        - softwareBuild
        - firmwareVersion
        - hardwareVersion
        - deviceId
        - akPub
        - pcr
    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
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes:
    basic:
      description: |
        NetHSM supports Basic Authentication.
      type: http
      scheme: basic
  links: {}
  callbacks: {}