Skip to content

Fortified IDDocs

Document signing with a requesting system

How a requesting system prepares, submits and verifies XML, PDF and CMS signatures with a signer approving in the browser.

This page describes the common DSS browser ceremony for document signing by a named person. Signature formats covers generic XML/PDF/CMS, exact UTF-8 text and the selected PAdES/XAdES/JAdES bindings. The flow follows the Sweden Connect DSS profile and passes through the signer's browser. The Support service reference has the OpenAPI specification, the fixed values and example messages.

  1. The requesting system keeps the original documents and prepares the exact bytes to be signed.
  2. It sends a signed DSS request through the signer's browser to POST /sign/{connection}.
  3. Signing Server shows the signing message and an approve and cancel choice.
  4. After approval, Signing Server sends a signed SAML authentication request to the configured identity provider, and the signer authenticates again.
  5. The identity provider returns a signed and encrypted SAML response to the configured assertion consumer service.
  6. Signing Server verifies the response, consumes the signing authorization once and signs.
  7. The browser posts the signed DSS response to the requesting system's registered return URI.
  8. The requesting system verifies the response, assembles the signed documents and verifies them.

Authentication and approval are separate and both are required. A backend HTTP client cannot take the place of the person's browser.

The administrator registers the requester and its connection in the identity provider configuration:

Value Rule
Connection A name of up to 64 characters matching [A-Za-z0-9][A-Za-z0-9._-]{0,63}. It is a name, not a URL.
Requester An absolute entity_id and an RSA public key of 2048–4096 bits as Base64 DER SubjectPublicKeyInfo. The requester holds the matching private key.
Return URI The exact HTTPS URI, including path, that receives the result. Its value must equal the Audience of the request.
Allowed connections A requester may use only the connections it has been explicitly granted.
Service and IdP identities The configured sp_entity_id and idp_entity_id are used as SignService and IdentityProvider in the request.

Use Sweden Connect implementation profile 1.7 and DSS extension 1.6. The profile URI is http://id.elegnamnden.se/csig/1.1/dss-ext/profile, and SignRequestExtension has Version="1.6".

The request contains:

  1. A unique SignRequest/@RequestID of 20–96 characters matching [A-Za-z0-9][A-Za-z0-9._:-]{19,95}.
  2. SignRequestExtension with RequestTime in UTC, saml:Conditions with NotBefore, NotOnOrAfter and the single registered return Audience, the intended signer's attributes and the entity IDs.
  3. SignMessage MustShow="true" with the Base64 of the original UTF-8 message. MimeType is text by default, and text/markdown is supported. In signing_service mode DisplayEntity must equal the configured service entity ID.
  4. SignTasks with one to eight SignTaskData elements, each with a SigType, a unique SignTaskId and Base64 ToBeSignedBytes.
  5. A whole-document XML signature by the requester's registered key, made last. Use RSA PKCS#1 v1.5 with SHA-256, the empty reference URI, the enveloped-signature transform and exclusive canonicalization. Do not reformat the signed XML.
SigType ToBeSignedBytes ProcessingRules
Generic XML Canonical XML SignedInfo, AdESType omitted or None. Must be absent.
Selected XAdES XML/BES Exact canonical SignedInfo plus the complete immutable AdESObject. Required: urn:se:idombud:signing:xades:detached-b-b-sha256-rsa:v1.
Generic PDF DER CMS SignedAttrs for the prepared PDF. Must be absent.
Selected PAdES PDF/BES Exact certificate-bound DER CMS attributes; CMS signingTime is absent. Required: urn:se:idombud:signing:pades:baseline-b-sha256-rsa:v1.
CMS DER SET OF signed attributes with content type id-data and a SHA-256 messageDigest of the original. Required: urn:se:idombud:signing:cms:detached-sha256-rsa:v1.

For the PAdES certificate and B-B/B-T/B-LT/B-LTA consumer workflow, follow PAdES signatures. The request has no separate Baseline-level field. XAdES signatures describes the equivalent consumer-owned four-level XML lifecycle over the unchanged XML/BES binding; server signing inputs still reject unsigned properties. JAdES signatures describes the four-level JSON/JWS lifecycle with its explicitly enabled local root profile. In all three formats, the consumer chooses the required completed level and verifies it after assembly.

The generic task limits are 8,192 decoded bytes. Selected XAdES additionally bounds its complete object separately and still obeys the total envelope limit. JAdES has its own default-off local root profile and task collection; follow Signature formats rather than inventing a new standard SigType. Signing messages are limited to 2,048 bytes and must not be blank. Markdown accepts paragraphs, headings, emphasis, lists, quotes, line breaks and literal code. Raw HTML, links and images are rejected.

Send the request through the signer's browser as a form post to {origin}/sign/{connection} with Content-Type: application/x-www-form-urlencoded, without a charset parameter:

Field Value
Binding POST/XML/1.0
RelayState The RequestID
EidSignRequest Base64 of the signed XML
<form method="post" action="{{origin}}/sign/{{connection}}">
<input type="hidden" name="Binding" value="POST/XML/1.0">
<input type="hidden" name="RelayState" value="{{requestId}}">
<input type="hidden" name="EidSignRequest" value="{{signedXmlBase64}}">
<button type="submit">Continue to signing</button>
</form>

The encoded form can be at most 131,072 bytes, and the decoded XML at most 65,536 bytes. A response with HTTP 200 is a page in the browser flow and does not mean that a signature exists. The pages cannot be framed.

A request is valid from RequestTime for at most 180 seconds, shortened by NotOnOrAfter. The signer's browser must keep the session cookie, so serialize signing ceremonies per browser and connection.

Signing Server returns an XHTML form that posts to your registered return URI:

Field Value
Binding POST/XML/1.0
RelayState The original RequestID
EidSignResponse Base64 of the signed DSS SignResponse

Before you treat the operation as complete:

  1. Find the unexpired consumer session for the RequestID. Reject duplicates and unknown IDs. RelayState alone is not authentication.
  2. Validate the schemas and the whole envelope with the registered service envelope key, and check the profile, extension version and times against your request.
  3. Read the signed ResultMajor and ResultMinor. HTTP 200 or a valid XML signature is not success.
  4. On success, verify SignerAssertionInfo against the intended signer, the configured IdP, the assurance level and fresh authentication. Verify the document certificate against your own trust policy.
  5. Match task IDs, types and ToBeSignedBytes exactly with the stored request, and verify each signature.
  6. Assemble the XML or PDF signature, or the detached CMS with absent eContent, and verify the complete resulting document against the retained original.
  7. Mark the operation complete and consume the session once.
Observation Meaning
HTTP 400 Malformed or untrusted request, wrong content type, method or query, an unknown requester or audience, or missing, replayed or expired browser state. No DSS result is promised.
HTTP 404 No such route.
HTTP 500 Infrastructure failure. Do not assume whether a signature was made.
HTTP 503 on /sign/{connection} Resource admission, pending capacity or a dependency may be unavailable. Interpret it with the selected contract and do not infer retry safety from the status alone.

A signed result carries one of these error minors:

Minor Meaning
NotSupported Unsupported extension or version.
req-expired The request was already outside its time window.
user-cancel The signer cancelled.
user-mismatch The authenticated person is not the requested signer.
sigmessage-error The message is missing or unsupported, or the returned digest is missing or wrong.
authn-failed Authentication failed.
security-violation The request, evidence or stored state was rejected.

Not every failure produces a signed response. If the signer cancels at the identity provider without a SAML response, no result is returned and your session stays pending until its own deadline.

If the final browser post is lost, or the server restarts, treat the outcome as unknown rather than failed. Signing may already have happened. Do not replay the old request, because a duplicate is rejected and not answered from a cache. Resolve the business situation first, then start a new request with a new ceremony.