pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Sign CMS (RFC 5652 SignedData, attached or detached, Web Crypto signed)

sign_cms

Create an RFC 5652 SignedData with one signer over content or a precomputed digest for attached, detached, or PDF /ByteRange signatures, returning DER, PEM, or hex.

Instructions

Produce an RFC 5652 SignedData over content (attached, or detached:true) or over a precomputed contentDigest (detached only — the PDF /ByteRange case), with ONE signer: signer (a PKCS#8 key or a PKCS#12 file, imported as a NON-EXTRACTABLE Web Crypto key — nothing generates or exports a key here) and certificate (required with signer.key; a PKCS#12 bag's certificate serves otherwise), chain and crls parsed (never embedded unread) then embedded. Signed attributes are always written: contentType, messageDigest, signingTime (default PKINATIVE_MCP_AT or now, whole seconds; 'none' omits it — pin it for reproducible bytes), SigningCertificateV2 and CMSAlgorithmProtection (on by default; CAdES / PAdES need them), plus your signedAttributes / unsignedAttributes (DER Attributes as hex). sid defaults to issuerAndSerialNumber (keep it unless the reader is known). The new signature is verified against the signer certificate BEFORE it is returned (KEY_MISMATCH otherwise). RSA keys need signer.rsaScheme; SHA-1 needs allowSha1:true. Output DER (default; .p7s), PEM (label CMS) or hex, inline or as a sandbox file (never overwritten). Add a counter time-stamp afterwards with amend_cms.

Input Schema

Name	Required	Description	Default
`sid`	No	How the SignerInfo names the certificate. Keep issuerAndSerialNumber unless the reader is known: subjectKeyIdentifier (version 3) is refused by some deployed readers and needs the certificate's SKI extension.	issuerAndSerialNumber
`crls`	No	CRLs to embed (DER or X509 CRL PEM) (every PEM block of every item is taken).
`chain`	No	Further certificates to embed (the chain) (every PEM block of every item is taken). The signer certificate is always embedded once; a PKCS#12 bag's other certificates are added too.
`limits`	No	Raise pkinative's 22 named security bounds for this call (trusted input only; absent keys keep the engine defaults). A value above an operator ceiling (PKINATIVE_MCP_MAX_INPUT_BYTES, PKINATIVE_MCP_MAX_KDF_ITERATIONS, PKINATIVE_MCP_MAX_PATHS_EXPLORED) is LIMIT_CEILING_EXCEEDED; describe_engine lists the defaults and the ceilings.
`signer`	Yes	The signing key: exactly one of `key` (a PKCS#8 private key, plain or PBES2-encrypted, PEM or DER) or `p12` (a PKCS#12 file, PBES2 + PBMAC1 only). The key is imported into a NON-EXTRACTABLE Web Crypto key and never leaves the engine; no result ever carries a key byte. The algorithm follows the key: ECDSA on the key's curve, Ed25519/Ed448 (no hash), RSA REQUIRES rsaScheme ('pkcs1' \| 'pss' — pkinative has no default). SHA-1 only with the tool's allowSha1:true.
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`content`	No	The content to sign (hashed with the signer's digest; embedded unless detached): exactly one of text / base64 / path.
`pemMode`	No	'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers).	strict
`detached`	No	Omit the content from the SignedData (the signature travels without what it signs; most S/MIME and every PDF signature).
`encoding`	No	Artefact encoding: 'pem' (RFC 7468 text), 'der' (raw bytes), 'hex' (lowercase hex in structuredContent, inline only, ≤ 64 KiB). Default 'der'.	der
`allowSha1`	No	Accept or produce SHA-1 signatures (legacy material you already trust). Default false: refused with PKI_CRYPTO_ALGORITHM_REFUSED on read, VALIDATION_ERROR on write.
`outputMode`	No	'base64' (default) returns the artefact inline as an embedded resource (≤ 50 MiB). 'file' writes it inside PKINATIVE_MCP_OUTPUT_DIR (never overwrites; ≤ 1 GiB) and returns a resource_link.	base64
`outputPath`	No	Relative path inside the sandbox (only when outputMode='file'); the extension must match the encoding (.p7s .p7m .p7b .cms .der for der; .pem for pem). Key-bearing extensions (.key .p8 .p12 .pfx) are refused: nothing here writes a private key.
`certificate`	No	The signer certificate: exactly one of pem / derBase64 / path. Required with signer.key; optional with signer.p12 (the bag's certificate is used, and this one wins when both are given).
`contentType`	No	The eContentType (dotted OID). Default id-data (1.2.840.113549.1.7.1); any other makes a version 3 SignedData.
`signingTime`	No	The claimed signing time: an ISO 8601 instant, epoch milliseconds, 'now', or 'none' to omit the attribute (PAdES forbids it, S/MIME expects it). Whole seconds. Omitted: PKINATIVE_MCP_AT when pinned, else the wall clock — pin it for reproducible bytes.
`contentDigest`	No	The content's digest, already computed with the signer's digest algorithm (the PDF /ByteRange case). Requires detached:true. Exclusive with content. Hexadecimal (an 0x prefix, colons and spaces are tolerated).
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der
`signedAttributes`	No	Further signed attributes, each one DER Attribute as hex, written verbatim. A type the builder writes itself, a repeated type or a countersignature is refused (PKI_API_MISUSE).
`unsignedAttributes`	No	Unsigned attributes, each one DER Attribute as hex (a time-stamp token already in hand: amend_cms add-timestamp checks the imprint first). A signed-only type is refused.
`algorithmProtection`	No	Write CMSAlgorithmProtection (RFC 6211, RFC 8933 §4).
`signingCertificateV2`	No	Write the ESS SigningCertificateV2 attribute (RFC 5035), binding the signature to this certificate — CAdES, PAdES and RFC 3161 require it.

Output Schema

Name	Required	Description
`hex`	No	The artefact as lowercase hex (when encoding='hex').
`mode`	Yes
`sha256`	Yes	SHA-256 of the DER bytes (lowercase hex) — the reproducibility proof.
`summary`	Yes
`encoding`	Yes
`filePath`	No	Sandboxed absolute path (when outputMode='file').
`sizeBytes`	Yes	Size of the DER artefact.
`diagnostics`	Yes	Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one).
`diagnosticCounts`	Yes	Occurrences per diagnostic code.
`diagnosticsTruncated`	No	true when distinct diagnostics beyond the 200 listed were dropped.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 27, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the sparse annotations (readOnlyHint=false, idempotentHint=false) the description discloses the traits that actually matter for a signing tool: the key is imported as a non-extractable Web Crypto key, nothing generates or exports a key, no result ever carries a key byte, chain/crls are parsed before embedding, the signature is verified against the signer certificate before return (KEY_MISMATCH), and sandbox files are never overwritten.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Roughly 200 words for a 22-parameter tool, front-loaded with the operation and its modes before descending into key handling and output. It is dense but nearly every clause carries a constraint; the one cost is that the middle sentences are so compressed that an agent may have to re-read them to separate content, digest and attribute rules.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity signing tool the description covers the entry rules (content vs contentDigest, key vs p12, certificate requirement), the invariants (always-written signed attributes, verification before return), and the exit paths (der/pem/hex, inline base64 or sandbox file, then amend_cms). An output schema exists, so return shape need not be described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3; the description still adds cross-parameter meaning the schema's per-field docs do not — RSA keys require signer.rsaScheme, SHA-1 requires allowSha1, signingTime defaults to PKINATIVE_MCP_AT and should be pinned for reproducible bytes, sid's default and its reader-compatibility risk. Signed/unsigned attribute types and the certificate-vs-p12 precedence are clarified as well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Produce an RFC 5652 SignedData') plus the three input modes (content attached, content detached, contentDigest detached-only), and closes by routing counter-timestamping to amend_cms. An agent can distinguish this from verify_cms, inspect_cms and amend_cms without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete selection rules: detached for S/MIME and every PDF signature, contentDigest for the PDF /ByteRange case (detached only), 'keep issuerAndSerialNumber unless the reader is known', SHA-1 only with allowSha1. What's missing is an explicit statement of when NOT to use it (e.g. 'to check an existing signature use verify_cms'), though amend_cms is correctly named as the follow-up.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.