{
"openapi": "3.1.0",
"info": {
"title": "VaultCode API",
"description": "VaultCode service that runs JAR and WebAssembly executables in isolated runtimes.\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.4.1",
"x-vaultcode-effective-limits": {
"maxInputBytes": 10485760,
"maxStdoutBytes": 10485760,
"maxStderrBytes": 10485760,
"maxExecutableBytes": 31457280,
"defaultExecutionTimeoutMillis": 60000,
"maxExecutionTimeoutMillis": 300000,
"maxRuntimeMemoryBytes": 536870912,
"maxJarMetaspaceBytes": 134217728,
"maxOpenFiles": 256,
"maxConcurrentExecutions": "unlimited"
}
},
"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, core WebAssembly version 1 module, or WebAssembly Component. WASM uploads skip JAR signer verification; fingerprint restrictions still apply. WASM execution uses Wasmtime and supports WASI Preview 1 core modules and WASI Preview 2 command components. A detached .sig file is required when upload signature public keys or certificates are configured, and is verified before the executable is stored. Upload replaces the active executable.\n\nJAR, Core WASM and WASIp2 artifacts share the effective maximum size of 30 MiB (31457280 bytes).",
"operationId": "uploadExecutionCode",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"signature": {
"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",
"description": "Executes the currently loaded JAR, WASI Preview 1 module, or WASI Preview 2 command component. The Base64-encoded input and execution context are delivered to the executable through stdin. The response contains the Base64-encoded executable output, cryptographic hashes, timestamps, signatures, the executable fingerprint, and execution evidence. A request signature is required when request-signature allowlisting is enabled.\n\nEffective limits: input 10 MiB (10485760 bytes), stdout and stderr 10 MiB (10485760 bytes) each, default timeout 1 min (60000 ms), maximum timeout 5 min (300000 ms).",
"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": "60s"
}
}
},
"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": "60s"
},
"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": "60s"
},
"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 loaded JAR or WebAssembly executable via stdin. This should be base64-encoded. The executable needs to base64-decode this itself. Effective maximum UTF-8 length of this Base64 field: 10 MiB (10485760 bytes).",
"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. If omitted, the effective default is 1 min (60000 ms); the effective maximum is 5 min (300000 ms).",
"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 The raw executable stdout limit before Base64 encoding is 10 MiB (10485760 bytes)."
},
"outputSignature": {
"type": "string",
"description": "Output signature in base64. SHA256_WITH_RSA"
},
"timestamp": {
"type": "string",
"description": "Timestamp in base64"
},
"timestampData": {
"type": "string",
"description": "RFC 3161 data-to-be-stamped in base64. The decoded value is a JSON object containing executionCodeFingerprint and inputHash"
},
"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"
}
}
},
"PublicKeyDto": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationSignature": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PublicKeysDto": {
"type": "object",
"properties": {
"outputKey": {
"$ref": "#/components/schemas/PublicKeyDto",
"description": "Key used to sign the output of an execution."
},
"timestampKey": {
"$ref": "#/components/schemas/PublicKeyDto",
"description": "Key used to sign the timestamp of an execution."
},
"evidenceKey": {
"$ref": "#/components/schemas/PublicKeyDto",
"description": "Key used to sign the evidence of an execution (environment information)."
},
"encryptKey": {
"$ref": "#/components/schemas/PublicKeyDto",
"description": "Key used to decrypt a JAR executable (if uploaded encrypted)."
}
}
},
"EvidenceDto": {
"type": "object",
"properties": {
"executionCodeFingerprint": {
"type": "string",
"description": "SHA-256 hash of the JAR executable in base64"
},
"timestamp": {
"type": "string",
"description": "Timestamp in base64"
},
"timestampData": {
"type": "string",
"description": "RFC 3161 data-to-be-stamped in base64. The decoded value is a JSON object containing executionCodeFingerprint"
},
"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"
}
}
}
}
}
}