From 5cce31933b0e08a4b2e9d779dfdd7c3f110e861d Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Wed, 15 May 2024 19:01:42 +0200 Subject: [PATCH] Include API spec in repository Including the API spec makes it possible to reproducibly re-generate the client code and to select the exact spec version that is used for the generation. Fixes: https://github.com/Nitrokey/nethsm-sdk-rs/issues/23 --- .openapi-generator/VERSION | 2 +- Makefile | 2 + nethsm-api.yaml | 2606 ++++++++++++++++++++++++++++++++++++ update_openapi.sh | 4 +- 4 files changed, 2611 insertions(+), 3 deletions(-) create mode 100644 Makefile create mode 100644 nethsm-api.yaml diff --git a/.openapi-generator/VERSION b/.openapi-generator/VERSION index 0f78c31..ecb2186 100644 --- a/.openapi-generator/VERSION +++ b/.openapi-generator/VERSION @@ -1 +1 @@ -7.2.0-SNAPSHOT \ No newline at end of file +7.6.0-SNAPSHOT diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..a0e8258 --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +nethsm-api.yaml: + curl "https://nethsmdemo.nitrokey.com/api_docs/nethsm-api.yaml" --output nethsm-api.yaml diff --git a/nethsm-api.yaml b/nethsm-api.yaml new file mode 100644 index 0000000..de6496e --- /dev/null +++ b/nethsm-api.yaml @@ -0,0 +1,2606 @@ +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 + /health/alive: + get: + responses: + "200": + description: Yes, it is alive. + "406": + description: Content type in Accept header not supported. + "412": + description: Not locked or unprovisioned (in operational state). + description: | + Retrieve wether NetHSM is alive (powered up). + This corresponds to the state *Locked* or *Unprovisioned*. + x-annotation-role: + - Public + x-annotation-state: + - Locked + - Unprovisioned + /health/ready: + get: + responses: + "200": + description: Yes, it is alive and ready. + "406": + description: Content type in Accept header not supported. + "412": + description: Not alive and ready (not in operational state). + description: | + Retrieve wether NetHSM is alive and ready to take traffic. + This corresponds to the state *Operational*. + x-annotation-role: + - Public + x-annotation-state: + - Operational + /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 + /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 + /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 + /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 + /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). + "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 + /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 + /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. + Separate requests need to be made to request the individual key data. + parameters: + - name: filter + in: query + description: Only return keys that are can be used by the requester, according to restrictions. + schema: + type: string + security: + - basic: [] + x-annotation-role: + - Administrator + - Operator + x-annotation-state: + - Operational + post: + responses: + "201": + 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. + 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 + /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. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/KeyGenerateRequestData" + required: true + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + /keys/{KeyID}: + get: + responses: + "200": + description: | + For response body with content type `application/json`: + * *RSA* keys include `modulus` and `publicExponent` properties. + * P* keys include the common format (0x04 followed by big-endian \ + encoded affine coordinates x and y). + * Curve25519 keys are 32 byte, and follow the RFC8032 5.1.2 encoding \ + (little endian, x over y). + content: + application/json: + schema: + $ref: "#/components/schemas/PublicKey" + examples: + rsa: + summary: "RSA" + value: + mechanisms: + - RSA_Signature_PSS_SHA256 + type: RSA + restrictions: + tags: + - berlin + 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. + "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-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. + 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-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. + "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-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. + "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-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. + "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-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. + "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-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. + "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-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. + "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-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: Certificate for KeyID not found. + "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-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-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: There is no certificate for this KeyID. + "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-test-value-KeyID: myKey1 + parameters: + - name: KeyID + in: path + required: true + schema: + type: string + x-test-value: myKey1 + /keys/{KeyID}/restrictions/tags/{Tag}: + put: + responses: + "204": + description: Successful addition of the tag. + "304": + description: Tag is already present for this key. + "400": + description: Bad request, tag format is invalid. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: KeyID not found. + "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-test-value-KeyID: myKey1 + x-test-value-Tag: MyNewTag + delete: + responses: + "204": + description: Successful deletion of the tag. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: Tag or keyID not found. + "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-test-value-KeyID: myKey1 + x-test-value-Tag: MyTag + parameters: + - name: Tag + in: path + required: true + schema: + type: string + - name: KeyID + in: path + required: true + schema: + type: string + /users: + get: + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UserList" + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "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. + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + post: + responses: + "201": + description: | + Successful creation of user. + The response contains a Location header, + e.g. "https://nethsm.local/v1/users/I8mhHYJ1T3uk2lXrwXehVaw9KZzg7K". + 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. + "406": + description: Content type in Accept header not supported. + "412": + description: Precondition failed (NetHSM was not *Operational*). + description: Create a new user on NetHSM. The user-ID is generated by NetHSM. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UserPostData" + required: true + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + /users/{UserID}: + get: + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UserData" + + "400": + description: Invalid character in the UserID. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "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-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. + "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. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UserPostData" + required: true + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + x-test-value-UserID: newOperator + delete: + responses: + "204": + description: Successful deletion of user. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: User not found for this user-ID. + "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-test-value-UserID: operator + parameters: + - name: UserID + in: path + required: true + schema: + type: string + /users/{UserID}/passphrase: + post: + responses: + "204": + description: Successful change of passphrase. + "400": + description: Bad request - weak passphrase. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: User not found for this user-ID. + "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-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. + "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-test-value-UserID: operator + parameters: + - name: UserID + in: path + required: true + schema: + type: string + /users/{UserID}/tags/{Tag}: + put: + responses: + "204": + description: Successful addition of the tag. + "304": + description: Tag is already present for this UserID. + "400": + description: Bad request, tag format is invalid or user is not an operator. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: UserID not found. + "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-test-value-UserID: operator + x-test-value-Tag: munich + delete: + responses: + "204": + description: Successful deletion of the tag. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "404": + description: Tag or user not found. + "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-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. + "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 + /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. + "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 + 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. + "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 + /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. + "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 + /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. + "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 + 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. + "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 + /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. + "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 + /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. + "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 + 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. + "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 + /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. + "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 + 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. + "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 + /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. + "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 + /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. + "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 + 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. + "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 + /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 + /system/reboot: + post: + responses: + "204": + description: About to reboot NetHSM. + "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: Reboot NetHSM. + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + /system/shutdown: + post: + responses: + "204": + description: About to shut down NetHSM. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "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 + /system/factory-reset: + post: + responses: + "204": + description: About to reset NetHSM. + "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: Reset NetHSM to factory settings. + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + /system/update: + post: + responses: + "200": + description: Successfully verified update image (authenticity, integrity, and version number). + content: + application/json: + schema: + $ref: "#/components/schemas/SystemUpdateData" + "400": + description: Update malformed. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "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 + /system/commit-update: + post: + responses: + "204": + description: About to update NetHSM. + "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* or + update image is not present - call `/update` first). + description: Commit update of NetHSM software. + security: + - basic: [] + x-annotation-role: + - Administrator + x-annotation-state: + - Operational + /system/cancel-update: + post: + responses: + "204": + description: Update successfully cancelled. + "401": + description: Authentication required but none provided. + "403": + description: Access denied. + "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 + /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. + "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 + /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" + x-annotation-role: + - Public + x-annotation-state: + - Unprovisioned + - Operational +components: + schemas: + Passphrase: + minLength: 10 + type: string + ID: + pattern: ^[a-zA-Z0-9]+$ + minLength: 1 + maxLength: 128 + type: string + Base64: + pattern: ^[a-zA-Z0-9+/]+={0,3}$ + type: string + Switch: + enum: + - "on" + - "off" + type: string + SystemState: + enum: + - Unprovisioned + - Locked + - Operational + type: string + UserRole: + enum: + - Administrator + - Operator + - Metrics + - Backup + type: string + LogLevel: + enum: + - debug + - info + - warning + - error + type: string + 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/ID" + required: + - user + TagList: + example: + - berlin + - frankfurt + type: array + items: + $ref: "#/components/schemas/ID" + KeyMechanisms: + type: array + items: + $ref: "#/components/schemas/KeyMechanism" + PrivateKey: + example: + mechanisms: + - RSA_Signature_PSS_SHA256 + type: RSA + 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: + type: object + pcr: + type: object + 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: {} diff --git a/update_openapi.sh b/update_openapi.sh index c2dd014..7576469 100755 --- a/update_openapi.sh +++ b/update_openapi.sh @@ -2,5 +2,5 @@ docker build -t crust:latest generator -docker run --rm -u $UID -v "${PWD}:/out" -v "${PWD}/generator_conf.yaml:/conf.yaml" crust:latest generate -i=https://nethsmdemo.nitrokey.com/api_docs/nethsm-api.yaml -o out -g crust -c /conf.yaml -cargo fmt \ No newline at end of file +docker run --rm -v "${PWD}:/out" -v "${PWD}/nethsm-api.yaml:/nethsm-api.yaml" -v "${PWD}/generator_conf.yaml:/conf.yaml" crust:latest generate -i=/nethsm-api.yaml -o out -g crust -c /conf.yaml +cargo fmt