{
"openapi": "3.1.0",
"info": {
"title": "VaultCode API",
"description": "VaultCode service that runs JAR executables in an isolated runtime.\nWhen this service runs in a Primus HSM, it can securely attest to the executions and their runtime environment.\n\nFor details, see the [documentation](https://docs.securosys.com/vaultcode/overview).\n",
"contact": {
"name": "Contact Support",
"url": "https://support.securosys.com/external"
},
"license": {
"name": "Securosys End-User License Agreement (EULA)",
"url": "https://www.securosys.com/eula"
},
"version": "2.3.0"
},
"servers": [
{
"url": "https://demo-vaultcode.securosys.com",
"description": "Generated server url"
}
],
"paths": {
"/api/v1/upload_execution_code": {
"post": {
"tags": [
"VaultCode Controller"
],
"summary": "Upload new executable file",
"description": "Upload a compiled .jar file.",
"operationId": "uploadExecutionCode",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
},
"required": [
"file"
]
}
}
}
},
"responses": {
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Forbidden: Missing or invalid JWT token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessExceptionDto"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"200": {
"description": "OK"
}
}
}
},
"/api/v1/execute": {
"post": {
"tags": [
"VaultCode Controller"
],
"summary": "Run the loaded executable file",
"operationId": "execute",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteDto"
},
"examples": {
"Without request signature": {
"summary": "Execute when request-signature allowlisting is disabled",
"description": "Without request signature",
"value": {
"executeRequest": {
"input": "c3RyaW5n",
"timeout": "30s"
}
}
},
"With request signature": {
"summary": "Execute with a signature and a public key",
"description": "Replace signature and publicKey with real Base64 values. publicKey is the Base64-encoded DER key without PEM headers. The signature covers the executeRequest JSON object.",
"value": {
"executeRequest": {
"input": "c3RyaW5n",
"timeout": "30s"
},
"requestSignature": {
"signature": "BASE64_SIGNATURE",
"signatureAlgorithm": "SHA256withRSA",
"publicKey": "BASE64_DER_PUBLIC_KEY"
}
}
},
"With ML-DSA request signature": {
"summary": "Execute with an ML-DSA-44, ML-DSA-65 or ML-DSA-87 signature",
"description": "publicKey is the Base64-encoded DER SubjectPublicKeyInfo without PEM headers. The signature covers the executeRequest JSON object.",
"value": {
"executeRequest": {
"input": "c3RyaW5n",
"timeout": "30s"
},
"requestSignature": {
"signature": "BASE64_ML_DSA_SIGNATURE",
"signatureAlgorithm": "ML-DSA",
"publicKey": "BASE64_ML_DSA_DER_PUBLIC_KEY"
}
}
}
}
}
},
"required": true
},
"responses": {
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Forbidden: Missing or invalid JWT token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessExceptionDto"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutputDto"
}
}
}
}
}
}
},
"/api/v1/get_public_key": {
"get": {
"tags": [
"VaultCode Controller"
],
"summary": "Get public keys",
"description": "Returns the public key and attestation for outputKey, timestampKey, evidenceKey and encryptKey.",
"operationId": "getPublicKeys",
"responses": {
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Forbidden: Missing or invalid JWT token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessExceptionDto"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicKeysDto"
}
}
}
}
}
}
},
"/api/v1/get_evidence": {
"get": {
"tags": [
"VaultCode Controller"
],
"summary": "Get evidence",
"description": "Returns evidence about the state of VaultCode. Fingerprint of which executable is loaded, timestamp, environment information, an execution counter and HSM signed signature of the execution itself.",
"operationId": "getEvidence",
"responses": {
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Forbidden: Missing or invalid JWT token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessExceptionDto"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvidenceDto"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ReasonBasedExceptionDto": {
"type": "object",
"description": "Response for a specific error when an operation can not be completed successfully.",
"properties": {
"errorCode": {
"type": "integer",
"format": "int32",
"description": "The code of the error."
},
"reason": {
"type": "string",
"description": "The reason for the error."
},
"message": {
"type": "string",
"description": "The message containing why the error was returned by the application."
}
}
},
"BusinessExceptionDto": {
"type": "object",
"properties": {
"errorCode": {
"type": "integer",
"format": "int32"
},
"reason": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"ExecuteDto": {
"type": "object",
"properties": {
"executeRequest": {
"$ref": "#/components/schemas/InputDto",
"description": "Input to the execution."
},
"requestSignature": {
"$ref": "#/components/schemas/SignatureDto",
"description": "Signature over the executeRequest to authorize the request. Prefer another method (JWT, mTLS) instead."
}
},
"required": [
"executeRequest"
]
},
"InputDto": {
"type": "object",
"description": "Input to the execution.",
"properties": {
"input": {
"type": "string",
"description": "Input to be passed to the JAR executable via stdin. This should be base64-encoded. The JAR needs to base64-decode this itself.",
"example": "c3RyaW5n"
},
"timeout": {
"type": "string",
"default": "30s",
"description": "Timeout after which the execution will be stopped. Format as simple strings, such as: 30s, 10m, 1h.",
"maxLength": 32,
"minLength": 0
}
},
"required": [
"input"
]
},
"SignatureDto": {
"type": "object",
"properties": {
"signature": {
"type": "string",
"format": "base64",
"description": "Signature for a JSON object (base64 encoded).
Format of the signature is depending on the algorithm used and as returned when using a JDK's native Signature.sign() method.
Example (EC key):
echo \"MEUCIDOsDySFOWOcMKulHmR3uB8YCF7oX+vQ4dU8ooYC1OCvAiEApwMbu7nF19woZhO/KCIRV1api8oa/QCV2M2pcINAnEQ=\" | base64 -D | openssl asn1parse -inform DER
0:d=0 hl=2 l= 69 cons: SEQUENCE
\"\n 2:d=1 hl=2 l= 32 prim: INTEGER :33AC0F248539639C30ABA51E6477B81F18085EE85FEBD0E1D53CA28602D4E0AF
36:d=1 hl=2 l= 33 prim: INTEGER :A7031BBBB9C5D7DC286613BF2822115756A98BCA1AFD0095D8CDA97083409C44",
"maxLength": 6172,
"minLength": 0
},
"signatureAlgorithm": {
"type": "string",
"description": "The signature algorithm that was used for computing the request signature.",
"enum": [
"SHA224withRSA/PSS",
"SHA256withRSA/PSS",
"SHA384withRSA/PSS",
"SHA512withRSA/PSS",
"NONEwithRSA",
"SHA224withRSA",
"SHA256withRSA",
"SHA384withRSA",
"SHA512withRSA",
"DOUBLE_SHA256_WITH_ECDSA",
"NONESHA224withRSA",
"NONESHA256withRSA",
"NONESHA384withRSA",
"NONESHA512withRSA",
"NONEwithECDSA",
"SHA1withECDSA",
"SHA224withECDSA",
"SHA256withECDSA",
"SHA384withECDSA",
"SHA512withECDSA",
"SHA3224withECDSA",
"SHA3256withECDSA",
"SHA3384withECDSA",
"SHA3512withECDSA",
"SHA256withECDDSA",
"EdDSA",
"KECCAK224withECDSA",
"KECCAK256withECDSA",
"KECCAK384withECDSA",
"KECCAK512withECDSA",
"SHA1withRSA",
"SHA1withDSA",
"NONESHA1withRSA",
"SHA1withRSA/PSS",
"ML-DSA"
],
"example": "SHA256withRSA",
"maxLength": 64,
"minLength": 0
},
"publicKey": {
"type": "string",
"format": "base64",
"description": "The public key (base64 encoded) that belongs to the private key used to calculate the signature.",
"maxLength": 3584,
"minLength": 0
},
"certificate": {
"type": "string",
"format": "base64",
"description": "The certificate (base64 encoded) that belongs to the private key used to calculate the signature.",
"maxLength": 1572864,
"minLength": 0
}
}
},
"OutputDto": {
"type": "object",
"properties": {
"output": {
"type": "string",
"description": "Executable output in base64"
},
"outputSignature": {
"type": "string",
"description": "Output signature in base64. SHA256_WITH_RSA"
},
"timestamp": {
"type": "string",
"description": "Timestamp in base64"
},
"inputHash": {
"type": "string",
"description": "Input SHA256 hash in base64"
},
"outputHash": {
"type": "string",
"description": "Output SHA256 hash in base64"
},
"executionCodeFingerprint": {
"type": "string",
"description": "Executable SHA256 hash in base64"
},
"environmentInformation": {
"type": "string",
"description": "Environment information in base64"
},
"environmentSignature": {
"type": "string",
"description": "Environment signature in base64. SHA256_WITH_RSA"
},
"executionCounter": {
"$ref": "#/components/schemas/UserCounterDto"
},
"requestSignature": {
"type": "string",
"description": "Request Signature"
},
"requestCertificate": {
"type": "string",
"description": "Request Certificate"
},
"requestPublicKey": {
"type": "string",
"description": "Request PublicKey"
},
"evidenceSignature": {
"type": "string",
"description": "Signature of above in base64. SHA256_WITH_RSA"
}
}
},
"UserCounterDto": {
"type": "object",
"properties": {
"counter": {
"type": "integer",
"format": "int64",
"description": "Counter of successfully run execute endpoint."
},
"counterId": {
"type": "string",
"description": "Counter id"
}
}
},
"PublicKeysDto": {
"type": "object",
"properties": {
"outputKey": {
"$ref": "#/components/schemas/outputKey",
"description": "Key used to sign the output of an execution."
},
"timestampKey": {
"$ref": "#/components/schemas/timestampKey",
"description": "Key used to sign the timestamp of an execution."
},
"evidenceKey": {
"$ref": "#/components/schemas/evidenceKey",
"description": "Key used to sign the evidence of an execution (environment information)."
},
"encryptKey": {
"$ref": "#/components/schemas/encryptKey",
"description": "Key used to decrypt a JAR executable (if uploaded encrypted)."
}
}
},
"encryptKey": {
"type": "object",
"description": "Key used to decrypt a JAR executable (if uploaded encrypted).",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationSignature": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"evidenceKey": {
"type": "object",
"description": "Key used to sign the evidence of an execution (environment information).",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationSignature": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"outputKey": {
"type": "object",
"description": "Key used to sign the output of an execution.",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationSignature": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"timestampKey": {
"type": "object",
"description": "Key used to sign the timestamp of an execution.",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationSignature": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"EvidenceDto": {
"type": "object",
"properties": {
"executionCodeFingerprint": {
"type": "string",
"description": "SHA-256 hash of the JAR executable in base64"
},
"timestamp": {
"type": "string",
"description": "Timestamp in base64"
},
"environmentInformation": {
"type": "string",
"description": "Environment information in base64"
},
"environmentSignature": {
"type": "string",
"description": "Signature over the environment information, with SHA256_WITH_RSA, in base64"
},
"executionCounter": {
"$ref": "#/components/schemas/UserCounterDto"
},
"evidenceSignature": {
"type": "string",
"description": "Signature over this struct, encoded as JSON, with SHA256_WITH_RSA, in base64"
}
}
}
}
}
}