Skip to content

Fortified IDDocs

Organization seal

Machine-to-machine sealing of documents with an organization key, using signed JWS requests and no human signer.

An organization seal is a signature made under authority that the administrator has assigned to an organization. There is no signer, browser, identity provider or consent step, but the requesting system must still authenticate with a registered key.

The mode is selected with service set to organization-seal-v1 and runs as a separate server instance. Organization seals use machine authorization and the configured organization credential. Use the DSS or CSC service for human document signing.

Send POST /api/seal/v1 over HTTPS with Content-Type: application/jose, no query string and no content encoding. The body is one compact JWS of at most 131,072 bytes.

The protected header contains exactly:

Member Value
alg RS256, the only accepted algorithm.
kid The identifier of the requester's registered key.
typ idombud-seal-request+jws

The administrator pins each requester's RSA public key. Keys, URLs, certificates or algorithms supplied in a request cannot establish trust, and unknown or duplicate members are rejected.

The payload is at most 65,536 decoded bytes and contains exactly these members:

Field Meaning
version The integer 1.
request_id 20–96 characters matching [A-Za-z0-9][A-Za-z0-9._:-]*, unique per requester.
audience The exact configured audience URI.
organization A registered organization identifier.
profile A registered organization profile identifier.
issued_at UTC RFC 3339 instant.
expires_at Exclusive UTC expiry, later than issued_at and at most 60 seconds after it.
inputs An ordered array of 1–8 inputs, each with an id and signed_attributes.

signed_attributes is standard Base64 of DER CMS signed attributes, at most 8,192 decoded bytes, in the detached CMS SHA-256 with RSA form. The original documents stay with the requesting system. The request cannot name a credential, key alias, native module or person.

The key identified by kid determines the requester, and a configured grant must allow the exact organization and profile. The server selects the signing credential from the profile.

On success the server returns 200 with application/json:

Field Meaning
version, request_id As in the request.
transaction_id seal- followed by SHA-256 of the requester, a zero byte and the request ID.
organization, profile The registered values used.
algorithm RSA_PKCS1_SHA256
completed_at Server completion time. This is not a trusted time stamp.
certificate_chain The configured public chain as Base64 DER.
leaf_sha256 SHA-256 of the leaf certificate.
results The ordered {id, signature} entries, Base64.

The requesting system must verify each signature over its exact DER attributes, check the messageDigest against the retained original, and check the certificate against the organization certificate it expects.

Errors are returned as { "error": "..." } without submitted values or internal details.

Status error Action
400 invalid_request Correct the syntax or limits. Nothing was signed.
401 unauthenticated Check the registered key and the JWS.
403 not_authorized Check the audience and the organization and profile grant.
408 expired_request Nothing was signed for this attempt. Reconcile any earlier attempt before using new authority.
409 duplicate_request The request ID is already consumed. Reconcile and do not create another ID silently.
413 request_too_large Reduce the request.
415 unsupported_media_type Use application/jose.
429 capacity_exceeded Retry the same request ID within its lifetime.
503 unavailable The server was not ready. Nothing was consumed.
503 outcome_unknown Signing may have happened. Reconcile before doing anything else.

A request ID is consumed durably before the private-key operation. A consumed operation is never resumed or reset, and there is no way to fetch an earlier result. After a timeout, a lost connection or outcome_unknown, reconcile in your own business process and never submit a new ID automatically.

The configuration root contains schema_version, service, listener, database, audience, requesters, profiles and optionally resources and event_log. Human SAML, DSS and identity provider sections are rejected in this mode. The listener and database sections are described under Configuration.

Section Description
audience The absolute URI that requests must name. Each independent authorization domain needs its own audience. Instances that share an audience and requesters must share the database.
requesters Each entry has requester, a unique kid, public_key_file (RSA 2048–4096 bits as DER SubjectPublicKeyInfo) and grants, each with an organization and a profile.
profiles Each entry has organization, profile, certificate_sha256 (the lowercase hex SHA-256 of the leaf certificate) and a signing section for PKCS#12 or PKCS#11.
resources Optional untrusted_work (1–64, default 8), trusted_work (1–32, default 4) and trusted_per_requester (1–trusted_work, default 2). A full budget returns 429 without consuming an ID.

The signing key of each profile must be distinct from every TLS and requester key, judged by the actual public key. The leaf certificate must not carry an Extended Key Usage extension. Registrations are read at startup, and a changed file makes readiness fail instead of reloading.

The launcher supports config-check, database-check, schema-prepare, start, health-check and diagnostics. Startup prints SIGNING_READY service=organization-seal-v1. The diagnostics command reads public registrations and aggregate audit counts without signing and without starting a listener.

Keep consumed request IDs when you back up or migrate the database. A restored, stale database cannot show that an ID was never consumed.