# CSC integration — Signing Server 1.0.0

Signing Server provides CSC API 2.2.0.0 digest signing with registered clients, OAuth authorization, SAML identification and separate exact-batch consent.

## Registration and configuration

select `service=csc-v1` explicitly in protected installation settings.
The existing service modes retain their contracts. Register each client's opaque
`client_id`, `kid`, canonical DER SubjectPublicKeyInfo RSA public-key file, display
name, exact HTTPS redirects and permitted Access connections. The client retains
its private requester key. No key URL or dynamic registration is accepted.

Supply distinct TLS, SAML signing, SAML decryption, document-signing and client
requester keys. The root compares public roles before opening document signing
backends. A client requester key cannot equal a configured IdP signing key.
Public client keys and configuration files must satisfy the existing protected
file policy. A changed pinned public client/access registry makes readiness fail;
there is no hot authorization-policy reload.

The Access connections file uses the existing pinned-metadata registry format.
Each configured CSC connection has its own SP/audience and exact
`https://<configured-origin>/csc/saml/acs/<connection>` ACS. Register the derived
requester entity URI `urn:se:idombud:csc:client:<SHA256-hex(client_id UTF8)>` for
each permitted connection. Configure one subject attribute and authentication
context per connection. Signing Server owns the separate consent display.

Directory entries map a public `credential_id` to a configured supplied PKCS12 or
pinned PKCS11 credential, owner reference, connection, permitted client IDs,
enabled flag and actual leaf-certificate SHA256. The owner reference is
`saml-` plus SHA256 hex of `idpEntityId + NUL + subjectAttribute + NUL +
SamlMatching.canonical(attributeValue)`. Assurance and identity-source references
are derived by the root from the configured SAML policy/trust snapshot. A caller
cannot submit these as identity evidence. IDs, certificate pins and paths in the
example are placeholders and must match actual protected material.

CSC accepts supplied static credentials. Dynamic or provisioned
activation selectors are rejected in CSC configuration; existing optional PKI
capabilities in the other modes are preserved. There is no CSC issuance API.

`logo_url` is an operator-supplied HTTPS URI for the required CSC discovery logo.
Publish a JPEG or PNG at most 256×256 pixels. Signing Server validates URI syntax
and returns it in `info.logo`; it never fetches that URI. Host the image at the configured address. No new logo HTTP route is added.

Structural bounds are 64 clients, 16 identity policies, 256 credentials, eight
redirects per client and 64 permitted clients per credential. The existing Access
registry additionally bounds its requester inventory to 32; every selected
client/connection must resolve there. Global configuration parser bounds of
65,536 UTF8 bytes, 512 nodes and depth 12 apply even when individual arrays have
higher ceilings. Referenced registries, uniqueness, RSA sizes, pins and protected
paths require runtime validation beyond JSON schema.

CSC requires distinct migration and runtime database accounts in every engine.
The migration account prepares only owned versioned objects; runtime receives
SELECT/INSERT/UPDATE on `csc_oauth_record`, SELECT/UPDATE on `csc_oauth_mutex` and
SELECT on `csc_oauth_schema_history`. It receives no DELETE, DDL, history-write or
grant delegation rights. Table grants are supplied explicitly by the operator;
startup never grants permissions or adopts/repairs an incomplete journal schema.

## Client and browser sequence

use Authorization Code with S256 PKCE and authenticated PAR only.
Obtain each client assertion using RS256 and the registered requester private key:
`iss=sub=client_id`, a unique bounded `jti`, integer `iat`/`exp` with at most 60s
lifetime, and `aud` equal to the exact receiving PAR/token/revocation endpoint.
The optional `kid` must match registration; no embedded/remote keys or extra JWT
claims/headers are accepted. Every valid assertion is durably consumed once.
Use a fresh assertion for each request, including retries after a failed action.

1. POST URL-encoded parameters to `/csc/v2/oauth2/pushed_authorize`: client
   assertion fields, `response_type=code`, exact `redirect_uri`, `scope`, opaque
   nonempty `state`, `code_challenge`, `code_challenge_method=S256` and `connection`.
   Scope `service` requests discovery only. Scope `credential` additionally requires
   `credentialID`, `numSignatures`, `hashes` and SHA256 `hashAlgorithmOID`.
   An optional bounded `description` is displayed as client-supplied text.
2. Open `/csc/v2/oauth2/authorize?client_id=...&request_uri=...` in the person's
   browser. These are the only query fields. The owned PAR URI is a capability,
   never a fetched URL. The response sets a private `__Host-csc_<flow>` cookie
   (`Secure; HttpOnly; SameSite=None; Path=/; Max-Age=180`) and a signed SAML POST
   form to the configured IdP. Continue in that same browser.
3. The IdP POSTs a fresh signed/encrypted response to the CSC ACS. Exact private
   cookie/flow, request ID, configured audience/recipient, signature/decryption,
   assurance, times and subject checks apply. A valid DSS callback cannot replace
   this proof. Callback replay rejects. A successful identity proof alone creates
   no service or signing token.
4. Signing Server displays the registered client name, escaped description and
   either discovery-only approval or the exact credential, RSA/SHA256 algorithm,
   count and every digest occurrence. The customer retains originals; unseen
   document meaning is a client assertion. POST the matching private cookie,
   CSRF and explicit approve/cancel decision to `/csc/consent/<flow>`.
5. The server returns 303 to the registered redirect, preserving any registered
   query. Response parameters contain original `state`, `iss` equal to the
   configured Signing Server origin, and either one `code` or `error=access_denied`.
   The client verifies state and issuer before accepting the code. The SAML IdP
   entity ID is not this OAuth issuer.
6. POST a fresh endpoint-bound assertion and `grant_type=authorization_code`,
   `code`, exact registered `redirect_uri` and `code_verifier` to the token endpoint.
   Code consumption and insertion of the new opaque token hash commit together.
   No refresh token, implicit/password grant, client_credentials human signing,
   dynamic registration or arbitrary request_uri retrieval is supported.

Discovery returns `info.oauth2=<origin>/csc/v2`. Append `oauth2/authorize`,
`oauth2/pushed_authorize`, `oauth2/token` or `oauth2/revoke` exactly once. This is
the direct CSC base representation; OAuth metadata discovery is not advertised.

## Service and exact signing authority

a service Bearer authorizes `credentials/list` for its own verified
signer. Optional `userID` must equal that opaque signer reference. It also permits
accessible `credentials/info`; `authInfo=true` returns `auth.mode=oauth2code`.
A service token alone never authorizes private signing.

Credential authorization requires fresh verified identity matching the configured
owner and separate exact-batch approval. It can start directly from a known
credential, without a service token. An optional service Bearer on PAR becomes a
bound parent for the same client/person; its revocation/expiry blocks subsequent
child consumption. There is no invented parent for a direct credential grant.

Authorization `hashes` is CSV base64url of 1..64 raw 32-byte SHA256 digests,
retaining duplicate occurrences. A canonical unpadded value or one correct final
`=` is accepted for each. `numSignatures` must exactly match the count.
`signatures/signHash` instead uses canonical padded standard Base64 hashes,
`hashAlgorithmOID=2.16.840.1.101.3.4.2.1` and
`signAlgo=1.2.840.113549.1.1.1`. The full approved multiset/count must match; order
may differ. The core signs one canonical ordered batch and only public results
are reordered to the signing request's order. Nothing is added, dropped or deduplicated.

For signHash, use a credential Bearer with SAD omitted, or a service Bearer plus
the credential token in SAD for the same client/person. If credential Bearer and
SAD are both present, they must be the same grant. A credential token also permits
info for exactly its own credential, never enumeration. Synchronous `operationMode=S`
is the only supported operation mode. Async-only `validity_period` and
`response_uri` are ignored and no URI is fetched; signAlgoParams is unsupported.
Consumers verify every returned signature against the retained original and the
configured credential certificate independently.

## Failure, expiry and restart

expiry is exclusive. Ceilings are PAR handle 120s, private ceremony 180s,
code redemption 30s, service token 300s and credential token 30s. The authority
deadline starts with PAR creation and is clamped by all applicable human proof,
certificate, transaction, consent and parent deadlines. A PAR handle's redemption
TTL and a code's redemption TTL differ from the underlying authority deadline;
redeeming them does not restart or extend that deadline. Actual issued tokens can
therefore have substantially less than the ceiling, including service tokens.

Both unstarted PAR private state and active browser/SAML state are process-bound
and discarded on restart. CSC requires a new authenticated
PAR after restart; it does not reconstruct a pending ceremony from journal metadata.
Unredeemed valid consent-created codes and exact durable grants retain only their
original finite authority. Consumed/revoked records remain consumed/revoked.

The final private gate rereads time after journal admission, checks current child
and every applicable service grant, commits consumption, then checks the resulting
deadline again after known commit before forwarding to private crypto. Waiting for
a lock or commit cannot extend a grant. The canonical transaction first consumes
its own AUTHORIZED→SIGNING authority. Crash/failure after either consumption never
resets or privately retries the transaction. A lost signing response is ambiguous;
do not use another token or change inputs to replay that transaction.

Missing/invalid/expired resource Bearer: 401 `invalid_token` with a Bearer
WWW-Authenticate challenge. Bad client assertion: 401 `invalid_client`.
Invalid code/client binding/redirect/PKCE/expiry at redemption: 400 `invalid_grant`;
unsupported grant type: 400 `unsupported_grant_type`. Malformed fields, CSRF or
exact-authority mismatch: 400 `invalid_request`. Wrong method: 405; media type:415;
unknown route:404. Unavailability/overload/unknown DB outcome:503
`temporarily_unavailable`. Unknown/other-client revocation returns the same empty
success; there is no token-existence oracle. Do not infer a known signing failure
or permission to retry privately from 503.

JSON and OAuth form bodies are at most 16,384 bytes; authorize query 4,096
characters; SAML form 524,288 bytes with decoded response at most 262,144 bytes.
Forms have at most 24 unique fields and strict UTF8/percent decoding. Duplicate
JSON/form names and ambiguous authorization/cookie headers reject. Work admission
is bounded to 16 concurrent requests, 64 pending ceremonies overall and eight per
registered client. The existing fixed Java HTTP connection/header/deadline limits
also apply. Responses explicitly close connections, carry no-store/no-referrer and
restrictive frame/form CSP; an early unavailable POST response does not drain an
untrusted body or ambiguously reuse that connection.

No raw tokens/codes/SAML assertions, browser secrets, descriptions, originals,
request bodies or private keys enter persistent authority metadata or application
logs. Canonical signing audit remains separate from optional CEF events.

## Database lifecycle and operator boundaries

CSC uses the existing canonical `signing_transaction`/`signing_audit`
family together with version1 `csc_oauth_record`, `csc_oauth_mutex` and
`csc_oauth_schema_history`. Prepare both families using the packaged
`schema-prepare` command, then supply runtime table grants before starting.
On PostgreSQL the owner needs the prepared `signing_schema` namespace and CREATE
in public; runtime has no schema CREATE or privileged role membership. Canonical
runtime grants are SELECT/INSERT/UPDATE for transactions, SELECT/INSERT for audit
and sequence USAGE. No DELETE, history writes, delegation or public/column grants
are part of the CSC runtime profile. MariaDB/SQL Server retain their existing
qualified direct-grant profiles and add the closed OAuth family.

Startup checks both canonical and OAuth schema/history/privileges before binding.
Runtime readiness checks current keys/metadata and a bounded read-only admission
row probe; it is not a complete repeated privileged schema or audit scan.
`diagnostics` validates OAuth schema and runtime privilege scope without a private
probe; its JSON names that limited scope. `recovery-diagnostics` is unsupported
for CSC and never reconstructs or resumes authority.

OAuth records contain bounded metadata and capability hashes. Expiry never means
that replay-consumption or audit records may be reset. CSC performs no
automatic journal deletion, truncation or schema repair. Retain the journal and
canonical state together; age alone does not authorize removing security evidence.
Separate ordinary cleanup of disposable test/build files from database lifecycle.
Any future compaction needs an explicit audited retention contract proving that
consumed/revoked identities cannot revive, including after clock rollback/restore.

Include all canonical and CSC tables, checksums and schema histories in the same
consistent database backup. Configured client/identity/trust/key references remain
separately protected operator inputs; private document keys are never copied into
the journal. The existing [database backup/restore boundaries](/products/signing-server/next/installation/databases/)
continue to apply. A stale restore can roll back both canonical consumption and
OAuth state. It must never be treated as permission to retry, reset grants, extend
expiry or resume traffic automatically. Keep signing stopped, compare with an
independent current checkpoint and follow the separate operator recovery decision.
No CSC restore/reset endpoint or automated recovery approval is provided. Use the documented operator recovery procedure for backup and restore.

Private PAR/authorize/ACS/consent state belongs to one process; a proxy must keep
one active browser ceremony on that process. Sharing a database does not recreate
pending browser state or establish HA support. Tokens/codes keep their original
durable finite state; the global mutex does not recreate pending browser ceremonies on another process.

For Linux install4j with file CEF output or SoftHSM, prepare an owned systemd
drop-in with only the required writable data directory and the protected
`SOFTHSM2_CONF` path. The generated Java25 service enables native access only for
`jdk.crypto.cryptoki`; caller requests never select native modules or key aliases.
The Windows prepared-identity installer worker explicitly recognizes `csc-v1`
for its read-only database connection check and TLS readiness check. It uses the
same closed configuration parser, runtime database account and listener as the
selected service, without issuing grants, applying DDL or probing a private key.
Unsupported modes or unavailable database/health checks return the existing
`UNAVAILABLE` private receipt; a receipt never authorizes signing or recovery.

On Windows, prepare the separate CEF event directory for the actual service
identity before startup: protected DACL, owner equal to that identity and no
other allow entries. Generic inherited administrator permissions do not satisfy
the existing event-file policy. Preserve existing event data; do not reset its
ACLs or ownership during an ordinary restart. 

Prepare the database with `schema-prepare` from the same exact packaged runtime
artifact that will start the service. Schema history binds the raw UTF-8 migration
resource bytes; source checkouts or rebuilt libraries with different line endings
are different migration inputs. First-party migration resources use LF across
build hosts. A checksum mismatch fails closed; never rewrite history checksums or
adopt an unknown schema to make startup succeed.
