{
"openapi": "3.0.1",
"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": "1.5.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": {
"required": [
"file"
],
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
}
}
},
"responses": {
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Request refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server 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"
}
}
},
"required": true
},
"responses": {
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Request refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server 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": {
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Request refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server 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": {
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"400": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"403": {
"description": "Request refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"501": {
"description": "Implementation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReasonBasedExceptionDto"
}
}
}
},
"500": {
"description": "Server 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",
"properties": {
"errorCode": {
"type": "integer",
"description": "The code of the error.",
"format": "int32"
},
"reason": {
"type": "string",
"description": "The reason for the error."
},
"message": {
"type": "string",
"description": "The message containing why the error was returned by the application."
}
},
"description": "Response for a specific error when an operation can not be completed successfully."
},
"ExecuteDto": {
"type": "object",
"properties": {
"executeRequest": {
"$ref": "#/components/schemas/InputDto"
},
"requestSignature": {
"$ref": "#/components/schemas/SignatureDto"
}
}
},
"InputDto": {
"type": "object",
"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."
},
"timeout": {
"type": "string",
"description": "Timeout after which the execution will be stopped. Format as simple strings, such as: 30s, 10m, 1h.",
"default": "30s"
}
},
"description": "Input to the execution."
},
"SignatureDto": {
"required": [
"digestAlgorithm",
"signature"
],
"type": "object",
"properties": {
"signature": {
"type": "string",
"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",
"format": "base64"
},
"digestAlgorithm": {
"type": "string",
"description": "The message digest algorithm that was used for computing the request signature.",
"example": "SHA-256",
"enum": [
"SHA-224",
"SHA-256",
"SHA-384",
"SHA-512",
"SHA3-224",
"SHA3-256",
"SHA3-384",
"SHA3-512"
]
},
"publicKey": {
"type": "string",
"description": "The public key (base64 encoded) that belongs to the private key used to calculate the signature.",
"format": "base64"
},
"certificate": {
"type": "string",
"description": "The certificate (base64 encoded) that belongs to the private key used to calculate the signature.",
"format": "base64"
}
},
"description": "Signature over the executeRequest to authorize the request. Prefer another method (JWT, mTLS) instead."
},
"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"
},
"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"
}
}
},
"PublicKeysDto": {
"type": "object",
"properties": {
"outputKey": {
"$ref": "#/components/schemas/outputKey"
},
"timestampKey": {
"$ref": "#/components/schemas/timestampKey"
},
"evidenceKey": {
"$ref": "#/components/schemas/evidenceKey"
},
"encryptKey": {
"$ref": "#/components/schemas/encryptKey"
}
}
},
"encryptKey": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Key used to decrypt a JAR executable (if uploaded encrypted)."
},
"evidenceKey": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Key used to sign the evidence of an execution (environment information)."
},
"outputKey": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Key used to sign the output of an execution."
},
"timestampKey": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
},
"attestation": {
"type": "string"
},
"attestationCertificateChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Key used to sign the timestamp of an execution."
},
"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"
},
"userCounter": {
"$ref": "#/components/schemas/UserCounterDto"
},
"evidenceSignature": {
"type": "string",
"description": "Signature over this struct, encoded as JSON, with SHA256_WITH_RSA, in base64"
}
}
},
"UserCounterDto": {
"type": "object",
"properties": {
"counter": {
"type": "integer",
"description": "Counter of successfully run execute endpoint.",
"format": "int64"
},
"counterId": {
"type": "string",
"description": "Counter id"
}
}
}
}
}
}