pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Encode X.509 structure (one building block to DER, from a JSON spec)

encode_x509_structure

Idempotent

Encodes one X.509 building block—such as a name, extension, or validity—into deterministic DER bytes from a closed spec, producing a hex, DER, or PEM fragment for use in certificate tooling.

Instructions

Encode ONE X.509 building block to DER through pkinative's structural encoders, deterministically (the same spec gives the same bytes): structure is name, name-attribute, validity, spki, algorithm-identifier, attribute, extension, extensions, basic-constraints, key-usage, extended-key-usage, subject-alt-name, subject-key-identifier, authority-key-identifier or signature-algorithm; spec holds that structure's members (closed objects — an unknown or missing member is refused with VALIDATION_ERROR naming spec <path>; validity takes explicit notBefore AND notAfter, never an implicit now; a key identifier comes as hex or is computed from a certificate / CSR / PUBLIC KEY input). signature-algorithm takes signer instead of a spec (the key is imported NON-EXTRACTABLE and only its algorithm is read: ECDSA, Ed25519/Ed448, RSA with the REQUIRED rsaScheme — KEY_TYPE_REQUIRED for an encrypted key without keyType, SECRET_REQUIRED without a password). Output hex by default (structuredContent.hex, ≤ 64 KiB), or DER / PEM (PEM needs label), inline or as a sandbox file (never overwritten). The bytes are a fragment, not a signed object: nothing here signs. Use encode_asn1 for arbitrary ASN.1 and create_certificate / create_csr for whole objects.

Input Schema

Name	Required	Description	Default
`spec`	No	The structure's members (a closed object; an unknown member is refused with VALIDATION_ERROR naming it). name: a distinguished name — { "C": "FR", "O": "Acme", "CN": "x" } or an array of RDNs [[{ "type", "value", "stringType"? }], …]. name-attribute: { "type": "CN" \| registry name \| dotted OID, "value", "stringType"?: utf8\|printable\|ia5\|numeric }. validity: { "notBefore", "notAfter" } — both ISO 8601 instants or epoch ms (required; no implicit now; whole seconds). spki: { "algorithm": dotted OID, "publicKey": hex of the BIT STRING content, "parameters"?: hex DER }. algorithm-identifier: { "oid", "parameters"?: hex DER }. attribute: { "oid", "values": [hex DER, …] }. extension: { "oid", "critical"?: false, "value": hex of the extnValue content }. extensions: the same closed object as create_certificate's spec.extensions (basicConstraints, keyUsage, extendedKeyUsage, subjectAltName, issuerAltName, subjectKeyIdentifier / authorityKeyIdentifier as hex, raw[]) — no key is at hand, so true for a key identifier is refused. basic-constraints: { "ca": boolean, "pathLen"?: n }. key-usage: ["digitalSignature", …] or { "usages": [...] }. extended-key-usage: ["serverAuth", "1.3.6.1.5.5.7.3.2", …] or { "purposes": [...] }. subject-alt-name: { "dns": [], "email": [], "uri": [], "ip": [], "registeredId": [], "directoryName": [<name>] }. subject-key-identifier: { "keyId": hex } or { "publicKey": <pem \| derBase64 \| path of a certificate, a CSR or a PUBLIC KEY> } (RFC 5280 §4.2.1.2 SHA-1 of the key bits). authority-key-identifier: { "keyId": hex } or { "issuerCertificate": <pem \| derBase64 \| path> } (its subjectKeyIdentifier, else the SHA-1 of its key bits). signature-algorithm takes no spec (signer decides it).
`label`	No	The RFC 7468 label for encoding:'pem' (required then, refused otherwise); a key-bearing label is refused.
`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`	No	signature-algorithm only: 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. Nothing is signed here — only the AlgorithmIdentifier the key would write (RSA-PSS carries its digest and salt length).
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`pemMode`	No	'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers).	strict
`encoding`	No	Artefact encoding: 'pem' (RFC 7468 text), 'der' (raw bytes), 'hex' (lowercase hex in structuredContent, inline only, ≤ 64 KiB). Default 'hex'.	hex
`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.
`structure`	Yes	The X.509 building block to encode.
`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 (.der .bin .asn1 for der; .pem for pem). Key-bearing extensions (.key .p8 .p12 .pfx) are refused: nothing here writes a private key.
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der

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.8/5.0

Behavior5/5

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

Goes well beyond the annotations: closed-object validation with VALIDATION_ERROR naming `spec <path>`, explicit notBefore/notAfter (never implicit now), the non-extractable key import with algorithm-only read, KEY_TYPE_REQUIRED / SECRET_REQUIRED failure modes, output default hex ≤64 KiB, file output never overwritten. Annotations only carry the side-effect flags, so this detail is substantive, not redundant.

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?

Front-loaded with verb, resource and the determinism guarantee, and every clause carries real constraints. It is, however, a single dense run-on paragraph packing error codes, key handling and output modes together, which makes it slower to scan than a short bulleted structure would be.

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 12-parameter, deeply nested tool with an output schema, this covers the remaining ground: output shapes (hex in structuredContent, DER/PEM inline or sandbox file), determinism, validation and crypto error codes, and the explicit non-goal of signing. Nothing an agent needs in order to invoke it correctly is missing.

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 100%, so the baseline is 3; the description earns a bump by explaining cross-parameter semantics the schema cannot, e.g. that signature-algorithm takes `signer` instead of `spec`, that PEM requires `label`, and that a key identifier is either hex or computed from a certificate / CSR / public key input. Per-structure member detail largely restates the already-rich `spec` schema field.

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?

Specific verb (encode) plus resource (ONE X.509 building block to DER) with the deterministic guarantee stated. It enumerates the exact `structure` values and explicitly routes whole objects and arbitrary ASN.1 elsewhere, so it is distinguishable from every sibling without opening a schema.

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

Usage Guidelines5/5

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

Explicit boundaries: 'Use encode_asn1 for arbitrary ASN.1 and create_certificate / create_csr for whole objects', plus 'The bytes are a fragment, not a signed object: nothing here signs'. It also names the within-tool alternative for signature-algorithm, which takes `signer` instead of a spec.

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