Notary Project · Schema
Notary Project Plugin Protocol
JSON Schema for the Notation plugin extensibility protocol. Notation plugins are executables that implement external key management and signing capabilities. Notation invokes plugins by passing a JSON request on stdin and reading the JSON response from stdout. Plugins must implement the get-plugin-metadata command and optionally implement signing (describe-key, generate-signature) and/or verification (generate-envelope, verify-signature) capability commands.
Cloud NativeContainer SecurityImage SigningIncubatingOCIVerification
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/api-evangelist/notary/blob/main/json-schema/notary-plugin-protocol-schema.json",
"title": "Notary Project Plugin Protocol",
"description": "JSON Schema for the Notation plugin extensibility protocol. Notation plugins are executables that implement external key management and signing capabilities. Notation invokes plugins by passing a JSON request on stdin and reading the JSON response from stdout. Plugins must implement the get-plugin-metadata command and optionally implement signing (describe-key, generate-signature) and/or verification (generate-envelope, verify-signature) capability commands.",
"type": "object",
"$defs": {
"GetPluginMetadataRequest": {
"type": "object",
"description": "Request payload for the get-plugin-metadata command. Notation sends this to discover what capabilities and contract versions the plugin supports.",
"required": ["contractVersion"],
"properties": {
"contractVersion": {
"type": "string",
"description": "The plugin contract version that Notation supports. The plugin should verify it supports this version.",
"pattern": "^\\d+\\.\\d+$"
}
}
},
"GetPluginMetadataResponse": {
"type": "object",
"description": "Response payload for the get-plugin-metadata command containing plugin identification and supported capabilities.",
"required": ["name", "description", "version", "url", "supportedContractVersions", "capabilities"],
"properties": {
"name": {
"type": "string",
"description": "Name of the plugin. Must match the plugin binary name suffix after 'notation-'.",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\-_]*$",
"minLength": 1,
"maxLength": 64
},
"description": {
"type": "string",
"description": "Human-readable description of the plugin and what key management or signing service it integrates with.",
"minLength": 1,
"maxLength": 512
},
"version": {
"type": "string",
"description": "Semantic version of the plugin following the SemVer 2.0 specification (e.g., 1.0.0).",
"pattern": "^v?\\d+\\.\\d+\\.\\d+([-+].+)?$"
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the plugin's documentation, homepage, or source repository."
},
"supportedContractVersions": {
"type": "array",
"description": "List of plugin contract versions this plugin supports. Must include at least one version.",
"minItems": 1,
"items": {
"type": "string",
"description": "A supported contract version string (e.g., '1.0').",
"pattern": "^\\d+\\.\\d+$"
}
},
"capabilities": {
"type": "array",
"description": "List of capabilities the plugin implements. Each capability requires implementing a specific set of commands. SIGNATURE_GENERATOR.RAW requires describe-key and generate-signature. SIGNATURE_VERIFIER.TRUSTED_IDENTITY and SIGNATURE_VERIFIER.REVOCATION_CHECK require verify-signature.",
"minItems": 1,
"items": {
"type": "string",
"description": "A capability identifier string.",
"enum": [
"SIGNATURE_GENERATOR.RAW",
"SIGNATURE_GENERATOR.ENVELOPE",
"SIGNATURE_VERIFIER.TRUSTED_IDENTITY",
"SIGNATURE_VERIFIER.REVOCATION_CHECK"
]
}
}
}
},
"DescribeKeyRequest": {
"type": "object",
"description": "Request payload for the describe-key command. Notation sends this to learn the key specification (algorithm and size) for a given key ID so it can select the appropriate signature algorithm.",
"required": ["contractVersion", "keyId"],
"properties": {
"contractVersion": {
"type": "string",
"description": "The plugin contract version being used for this invocation.",
"pattern": "^\\d+\\.\\d+$"
},
"keyId": {
"type": "string",
"description": "Plugin-specific identifier for the signing key. This is the value from the signing key configuration in Notation's keys.json.",
"minLength": 1
},
"pluginConfig": {
"type": "object",
"description": "Optional plugin-specific configuration key-value pairs passed from the signing key configuration.",
"additionalProperties": {
"type": "string",
"description": "Plugin configuration value."
}
}
}
},
"DescribeKeyResponse": {
"type": "object",
"description": "Response payload for the describe-key command containing the key specification for the requested key.",
"required": ["keyId", "keySpec"],
"properties": {
"keyId": {
"type": "string",
"description": "The key ID echoed from the request, confirming which key is being described."
},
"keySpec": {
"type": "string",
"description": "The key specification string identifying the key algorithm and size. Used by Notation to select the hash algorithm for signature generation.",
"enum": [
"RSA-2048",
"RSA-3072",
"RSA-4096",
"EC-256",
"EC-384",
"EC-521"
]
}
}
},
"GenerateSignatureRequest": {
"type": "object",
"description": "Request payload for the generate-signature command. Notation sends the payload to be signed (the signature envelope payload bytes) and the plugin returns the raw signature bytes signed with the specified key.",
"required": ["contractVersion", "keyId", "keySpec", "hashAlgorithm", "payload"],
"properties": {
"contractVersion": {
"type": "string",
"description": "The plugin contract version being used.",
"pattern": "^\\d+\\.\\d+$"
},
"keyId": {
"type": "string",
"description": "Plugin-specific identifier for the signing key to use.",
"minLength": 1
},
"keySpec": {
"type": "string",
"description": "Key specification of the signing key as returned by describe-key.",
"enum": [
"RSA-2048",
"RSA-3072",
"RSA-4096",
"EC-256",
"EC-384",
"EC-521"
]
},
"hashAlgorithm": {
"type": "string",
"description": "Hash algorithm to use when generating the signature. Must be compatible with the key spec.",
"enum": [
"SHA-256",
"SHA-384",
"SHA-512"
]
},
"payload": {
"type": "string",
"description": "Base64-encoded bytes of the data to be signed. This is the signature envelope payload as determined by Notation based on the signing algorithm.",
"format": "byte"
},
"pluginConfig": {
"type": "object",
"description": "Optional plugin-specific configuration key-value pairs.",
"additionalProperties": {
"type": "string",
"description": "Plugin configuration value."
}
}
}
},
"GenerateSignatureResponse": {
"type": "object",
"description": "Response payload for the generate-signature command containing the raw signature and certificate chain.",
"required": ["keyId", "signature", "signingAlgorithm", "certificateChain"],
"properties": {
"keyId": {
"type": "string",
"description": "The key ID echoed from the request."
},
"signature": {
"type": "string",
"description": "Base64-encoded raw signature bytes produced by signing the request payload with the specified key.",
"format": "byte"
},
"signingAlgorithm": {
"type": "string",
"description": "The signing algorithm used, expressed as a fully-qualified algorithm string matching the Notary Project signature specification.",
"enum": [
"RSASSA-PSS-SHA-256",
"RSASSA-PSS-SHA-384",
"RSASSA-PSS-SHA-512",
"ECDSA-SHA-256",
"ECDSA-SHA-384",
"ECDSA-SHA-512"
]
},
"certificateChain": {
"type": "array",
"description": "Ordered array of base64-encoded DER-format X.509 certificates forming the signing certificate chain. The first certificate is the leaf signing certificate; subsequent certificates are intermediates and the root CA.",
"minItems": 1,
"items": {
"type": "string",
"format": "byte",
"description": "Base64-encoded DER certificate bytes."
}
}
}
},
"VerifySignatureRequest": {
"type": "object",
"description": "Request payload for the verify-signature command sent to plugins that implement SIGNATURE_VERIFIER capabilities. Notation sends this for trusted identity validation and revocation checking.",
"required": ["contractVersion", "signature", "trustPolicy"],
"properties": {
"contractVersion": {
"type": "string",
"description": "The plugin contract version being used.",
"pattern": "^\\d+\\.\\d+$"
},
"signature": {
"type": "object",
"description": "The signature envelope being verified.",
"properties": {
"criticalAttributes": {
"type": "object",
"description": "Critical signed attributes from the signature envelope header.",
"properties": {
"contentType": {
"type": "string",
"description": "Content type of the signature payload."
},
"signingScheme": {
"type": "string",
"description": "The signing scheme used."
},
"signingTime": {
"type": "string",
"format": "date-time",
"description": "The time at which the signature was created."
},
"expiry": {
"type": "string",
"format": "date-time",
"description": "Optional expiry time after which the signature is no longer valid."
}
}
},
"unprocessedAttributes": {
"type": "object",
"description": "Signed attributes not processed by Notation, passed to the plugin for validation.",
"additionalProperties": true
},
"certificateChain": {
"type": "array",
"description": "Certificate chain from the signature envelope for revocation checking.",
"items": {
"type": "string",
"format": "byte",
"description": "Base64-encoded DER certificate."
}
}
}
},
"trustPolicy": {
"type": "object",
"description": "The trust policy statement that matched this artifact, providing the plugin with policy context.",
"properties": {
"trustedIdentities": {
"type": "array",
"description": "List of trusted identity patterns from the matching trust policy statement.",
"items": {
"type": "string",
"description": "A trusted identity string (e.g., x509.subject: CN=...)."
}
},
"signatureVerification": {
"type": "object",
"description": "Signature verification configuration from the trust policy.",
"properties": {
"level": {
"type": "string",
"description": "Verification level (strict, permissive, audit, skip)."
}
}
}
}
},
"pluginConfig": {
"type": "object",
"description": "Optional plugin-specific configuration key-value pairs.",
"additionalProperties": {
"type": "string"
}
}
}
},
"VerifySignatureResponse": {
"type": "object",
"description": "Response payload for the verify-signature command indicating which verifications the plugin performed and their outcomes.",
"required": ["verificationResults", "processedAttributes"],
"properties": {
"verificationResults": {
"type": "object",
"description": "Map of verification type to verification result. Each key is a capability type the plugin verified.",
"properties": {
"SIGNATURE_VERIFIER.TRUSTED_IDENTITY": {
"$ref": "#/$defs/VerificationResult"
},
"SIGNATURE_VERIFIER.REVOCATION_CHECK": {
"$ref": "#/$defs/VerificationResult"
}
},
"additionalProperties": {
"$ref": "#/$defs/VerificationResult"
}
},
"processedAttributes": {
"type": "array",
"description": "List of attribute names from unprocessedAttributes that the plugin consumed during verification.",
"items": {
"type": "string",
"description": "An attribute name that was processed by the plugin."
}
}
}
},
"VerificationResult": {
"type": "object",
"description": "The result of a single verification check performed by the plugin.",
"required": ["success"],
"properties": {
"success": {
"type": "boolean",
"description": "Whether the verification check passed."
},
"reason": {
"type": "string",
"description": "Human-readable explanation of the verification result, especially on failure."
}
}
},
"PluginErrorResponse": {
"type": "object",
"description": "Error response written to stderr when a plugin command fails. The plugin exits with a non-zero exit code and writes this JSON to stderr.",
"required": ["errorCode"],
"properties": {
"errorCode": {
"type": "string",
"description": "Machine-readable error code identifying the type of failure.",
"enum": [
"VALIDATION_ERROR",
"UNSUPPORTED_CONTRACT_VERSION",
"ACCESS_DENIED",
"TIMEOUT",
"THROTTLED",
"ERROR"
]
},
"errorMessage": {
"type": "string",
"description": "Human-readable error message describing what went wrong."
}
}
}
}
}