Spec — ICP-Brasil digital signature (Koder Signer contract)

Version: 0.1.0 — Draft Status: Proposed (20260513)

*osition in multijurisdiction architecture (202605-20).*Per rfcs/signing-RFC-001-multi-jurisdiction.kmd (draft), Koder Signer is designed as a single service issuing signatures under three jurisdictions (BR, EU, US). This spec is the *R profile*of that design — it stays normative for everything ICP-Brasil related; sibling profiles (eidas.kmd, esign.kmd) open when their waves begin. Consumers select the jurisdiction per request via ?jurisdiction=br|eu|us; this spec applies when br is selected.

*cope.*This spec defines the contract Koder Signer (services/crypto/signer/) exposes for digital signature with legal validity in Brazil. It governs both the *nternal implementation*of Signer and the *onsumer contract*that every other Koder component (Koder Sign, Flow, custom integrations) follows when requesting a signature. The provider side (key generation, HSM integration, root CA store) is covered separately when those sub-components mature.

*egal anchor.*MP 2.200-2/2001 (still in force) distinguishes two types of electronic signature in Brazil:

• *rt. 10 §1º*— Signatures via ICP-Brasil PKI carry legal

  validity equivalent to handwritten signature by presumption.

• *rt. 10 §2º*— Other forms (drawn, typed, OTP-based)

  are valid when both parties agree.

Koder Sign (products/horizontal/sign/) currently implements only §2º (drawn/typed + email OTP). This spec covers what is needed for §1º — strict ICP-Brasil compliance.

R1 — Supported signature formats

Signer *UST*support these output formats:

ETSI TS 103 171 / TS 103 173 / TS 103 172 normative reference for PAdESCAdESXAdES respectively. ICPBrasil profile DOCICP-15 adds Brazilian-specific OIDs and policy URLs.

PDF Signature Visual representation: required when signature should appear graphically in the document; SHOULD respect specs/koder-app/ visual conventions when rendered by Koder Sign.

R2 — Signature policies

Signer *UST*support these ICP-Brasil signature policies (in order of cryptographic strength):

The policy is encoded as an OID + URL in the signed attributes per DOCICP15.

*efault* ADRT (timestamp gives nonrepudiation across cert expiry). Caller MAY request ADRB (lightweight) or ADRV (long-term archival).

R3 — Key material sources

Signer *UST*accept two key sources:

R3.1 — A1 certificate (file-based)

PKCS#12 (.pfx/.p12) file containing the private key encrypted with a passphrase. Loaded via the API:

POST /v1/sign/pades
Content-Type: multipart/form-data
  document: <PDF>
  cert: <PFX>
  passphrase: <string>
  policy: AD-RT

The passphrase *UST NOT*be persisted server-side after the request completes. The PFX *UST*be wiped from memory using crypto/subtlestyle constanttime zeroing.

R3.2 — A3 hardware token (PKCS#11)

Smartcard or USB token (SafeNet eToken, Watchdata Proxkey, Gemalto IDPrime, Morpho, etc.) accessed via PKCS#11 driver. Two deployment modes:

• *erver-side token* Signer host has the token attached + driver

  installed. API receives PIN, calls C_Sign via the driver.

• *lient-side token* end user has the token at their machine.

  Signer generates the hashtosign, returns it; client signs with the token; signed hash is returned to Signer for finalization. REQUIRES koder_kit PKCS#11 binding (or koder_web_kit WebAuthn bridge for browser flow).

The PIN *UST NOT*be persisted. Failed PIN attempts *UST*be rate-limited (token has hardware lockout typically at 3 attempts; Signer should also enforce its own backoff to avoid lockout).

R4 — Certificate chain validation

Signer *UST*validate every certificate against the ICP-Brasil chain rooted at the official AC-Raiz (current generation as of 2026: ACRaiz v5; older v2v3v4 trusted for legacy verifyonly).

The full chain set is published by ITI; Signer *UST*ship with a bundled icp-brasil-chains.pem and refresh it on a schedule (default: daily check + reload). Bundle versioning *UST*be recorded in audit logs (which chain version validated which signature).

Required checks per cert in chain:

• notBefore / notAfter valid for signing time
• KeyUsage contains digitalSignature (signer cert) or keyCertSign

  (CAs)

• ExtendedKeyUsage compatible with intended action
• BasicConstraints CA-flag correct for chain position
• Subject DN includes OU=ICP-Brasil for ICP certs
• Cert is not revoked (see R5)

R5 — Revocation checking

Signer *UST*check certificate revocation status before producing a signature, in this order:

1. *CSP*— if cert carries an AuthorityInformationAccess OCSP

   responder URL, query it. Response cached per ICP-Brasil policy (max 7 days, but typically 1-24h).

2. *RL*— if OCSP unavailable, fall back to CRL listed in

   CRLDistributionPoints. CRL freshness: max 24h.

Failure modes:

• Revocation status = revoked → reject; emit KSIGNER-SIGN-3001
• OCSP+CRL unreachable → softfail OR hardfail based on policy

  (default: softfail for ADRB, hardfail for ADRT/AD-RV)

• Cert revoked before signing time but signing requested

  retroactively → reject

For *D-RV* the CRL/OCSP responses *UST*be embedded in the signature container for offline verification later.

R6 — Timestamp authority (TSA)

For ADRT and ADRV, Signer *UST*obtain a qualified timestamp from an ICPBrasil accredited TSA. Default: ICPBrasil public TSA at ITI. Custom TSA configurable per deployment.

TSA protocol: RFC 3161 over HTTPS. Signer *UST*verify the TSA response signature against the TSA cert (also validated per R4-R5).

Time-stamp policy OIDs are encoded in the signature container.

R7 — Error map

Userfacing errors follow `specserrorsuserfacing-messages.kmd with the KSIGNER` product prefix:

All error codes localized enUS + ptBR per policies/language.kmd.

R8 — Multi-tenancy

Signer *UST*comply with policies/multi-tenant-by-default.kmd:

• Every signature request carries koder_user_id (and optional

  workspace_id).

• Audit logs include tenant scope (who signed, on whose behalf, for

  which workspace).

• Cross-tenant access returns 404, not 403.

Tenant isolation does *ot*apply to ICP-Brasil chain bundles (global, read-only) or TSA cache (global but keyed by hash, no PII).

T1-T6 — Test contract

Every Signer implementation *UST*pass:

• *1 — Valid A1 sign* PFX + correct passphrase → valid PAdES with

  policy AD-RT; ITI Verificador validates green.

• *2 — Valid A3 sign (server-side)* mocked PKCS#11 with valid

  cert + PIN → valid CAdES; verifies against bundled chain.

• *3 — Reject expired cert* PFX with notAfter < now → error

  KSIGNER-CERT-1002; no partial output written.

• *4 — Reject revoked cert* cert in test CRL → error

  KSIGNER-REV-3001.

• *5 — Cross-validate with reference signer* same input signed by

  signer-cli SERPRO and by Koder Signer produces semantically equivalent containers (byte-identical not required; both verify green via openssl cms -verify -policy … and ITI Verificador).

• *6 — Roundtrip* sign → embed in PDF → reopen → extract

  signature → verify signature is intact, policy is preserved, TSA proof present (for AD-RT).

Negative-path tests:

• *1 — Tampered document* modify PDF byte after sign → verify

  detects tamper.

• *2 — Wrong passphrase* error KSIGNER-CERT-1001; rate-limit

  applies after 3 attempts in 60s window.

• *3 — TSA unreachable* ADRT requested but TSA down → hardfail

  with KSIGNER-TSA-4001; no partial signature output.

Out of scope (v0.1.0)

• Signature visual templates (graphic representation in PDF).

  Tracked separately when Signer reaches consumer UI integration.

• ICPBrasil crossborder interoperability (eIDAS bridge).
• Longterm archival format LTV / PAdESLTA (planned for v0.3).
• SignerasHSM (Signer hosting keys directly, not just orchestrating

  signature against external token/file). Out of scope until KMS Sector (services/crypto/kms/) ships.

Roadmap

Open questions

• *mplementation language* Go (consistent with foundation/) vs.

  reuse JVM lib dss-eu via JNI bridge (mature ICP-Brasil support but adds JVM dependency). Decision deferred to ticket #003.

• *SA failover* ICP-Brasil has only ~3 public TSAs. Should Signer

  ship with a configurable fallback list, or fail-open if primary is down? (Affects R6.)

• *ert chain bundle distribution* ship inside the Signer binary

  (small, no fetch) vs. fetch on startup from ITI (always fresh, but bootstrap dependency)? Default proposal: ship + daily refresh.

Audit hooks

(Reserved for koder-spec-audit signing once a T1-T6 implementation template exists. Workflow path: .gitea/workflows/audit-signing.yml.)