mufassall

Cheat sheet · Business processes

Electronic digital signature

14 min · Intermediate · mufassall.dtwin.uz/en/l/digital-signature/

← Open the lesson

The problem

A seller signs a contract with a key that never leaves a hardware token, the buyer signs it too, and the signatures must still be provable years after the certificates expire. What is hashed, what the signature covers, how a server checks it, and why a trusted timestamp matters.

What you learn

  • What exactly gets signed: the file hash inside the signed attributes
  • What a CMS (PKCS#7) signature carries, detached or attached
  • Four server checks: math, chain, validity, revocation via OCSP
  • Why a trusted timestamp keeps an old signature valid after the certificate expires
Final scene

Diagram as code

The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.

Mermaid: flowchart

flowchart LR
  n_signer(("Seller"))
  n_app(["Signing app"])
  n_api["Document server"]
  n_docs[("Document store")]
  n_token[("Key token")]
  n_ca>"CA (OCSP)"]
  n_tsa>"Timestamp TSA"]
  n_partner(["Buyer app"])
  n_signer --> n_app
  n_app --> n_api
  n_app --> n_token
  n_token -.-> n_app
  n_api --> n_docs
  n_api --> n_ca
  n_api --> n_tsa
  n_partner --> n_api

Mermaid: request sequence

sequenceDiagram
  participant n_app as Signing app
  participant n_api as Document server
  participant n_token as Key token
  participant n_docs as Document store
  actor n_thief as Thief
  participant n_ca as CA (OCSP)
  participant n_tsa as Timestamp TSA
  participant n_partner as Buyer app
  Note over n_app,n_api: The app hashes the exact bytes of the contract
  n_app->>n_api: GET /contracts/ct_2041/file HTTP/1.1
  n_api-->>n_app: HTTP/1.1 200 OK
  Note over n_app,n_token: The private key signs inside the token and never leaves it
  n_app->>n_token: app -#62; token: C_Sign over PKCS#35;11
  n_token-->>n_app: token: signature, 64 bytes
  Note over n_app,n_api: The signature travels as a CMS package
  n_app->>n_api: POST /contracts/ct_2041/signatures HTTP/1.1
  n_api-->>n_app: HTTP/1.1 202 Accepted
  Note over n_api,n_docs: The server checks the signature in four steps
  n_api->>n_docs: verify ct_2041 signer #35;0
  Note over n_thief,n_api: A revoked certificate still passes
  n_thief->>n_api: verify ct_2077 signer #35;0
  Note over n_api,n_ca: Ask the CA: is this certificate still good?
  n_api->>n_ca: POST /ocsp HTTP/1.1
  n_ca-->>n_api: HTTP/1.1 200 OK
  Note over n_api,n_ca: Two years later the signature cannot be proven
  n_api->>n_ca: 2028-05-10 re-verify ct_2041 signer #35;0
  Note over n_api,n_tsa: A trusted timestamp fixes the signing time
  n_api->>n_tsa: POST /tsa HTTP/1.1
  n_tsa-->>n_api: HTTP/1.1 200 OK
  Note over n_api,n_docs: Store the evidence with the signature
  n_api->>n_docs: 2028-05-10 re-verify ct_2041 signer #35;0
  Note over n_partner,n_api: The buyer signs the same contract
  n_partner->>n_api: POST /contracts/ct_2041/signatures HTTP/1.1
  n_api-->>n_partner: HTTP/1.1 200 OK

D2

direction: right

n_signer: "Seller" {
  shape: person
}
n_app: "Signing app" {
  shape: rectangle
}
n_api: "Document server" {
  shape: rectangle
}
n_docs: "Document store" {
  shape: cylinder
}
n_token: "Key token" {
  shape: stored_data
}
n_ca: "CA (OCSP)" {
  shape: cloud
}
n_tsa: "Timestamp TSA" {
  shape: cloud
}
n_partner: "Buyer app" {
  shape: rectangle
}

n_signer -> n_app
n_app -> n_api
n_app -> n_token
n_token -> n_app {
  style.stroke-dash: 3
}
n_api -> n_docs
n_api -> n_ca
n_api -> n_tsa
n_partner -> n_api

PlantUML: request sequence

@startuml
participant "Signing app" as n_app
participant "Document server" as n_api
database "Key token" as n_token
database "Document store" as n_docs
actor "Thief" as n_thief
boundary "CA (OCSP)" as n_ca
boundary "Timestamp TSA" as n_tsa
participant "Buyer app" as n_partner
note over n_app, n_api : The app hashes the exact bytes of the contract
n_app -> n_api : GET /contracts/ct_2041/file HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_app, n_token : The private key signs inside the token and never leaves it
n_app -> n_token : app -> token: C_Sign over PKCS#11
n_token --> n_app : token: signature, 64 bytes
note over n_app, n_api : The signature travels as a CMS package
n_app -> n_api : POST /contracts/ct_2041/signatures HTTP/1.1
n_api --> n_app : HTTP/1.1 202 Accepted
note over n_api, n_docs : The server checks the signature in four steps
n_api -> n_docs : verify ct_2041 signer #0
note over n_thief, n_api : A revoked certificate still passes
n_thief -> n_api : verify ct_2077 signer #0
note over n_api, n_ca : Ask the CA: is this certificate still good?
n_api -> n_ca : POST /ocsp HTTP/1.1
n_ca --> n_api : HTTP/1.1 200 OK
note over n_api, n_ca : Two years later the signature cannot be proven
n_api -> n_ca : 2028-05-10 re-verify ct_2041 signer #0
note over n_api, n_tsa : A trusted timestamp fixes the signing time
n_api -> n_tsa : POST /tsa HTTP/1.1
n_tsa --> n_api : HTTP/1.1 200 OK
note over n_api, n_docs : Store the evidence with the signature
n_api -> n_docs : 2028-05-10 re-verify ct_2041 signer #0
note over n_partner, n_api : The buyer signs the same contract
n_partner -> n_api : POST /contracts/ct_2041/signatures HTTP/1.1
n_api --> n_partner : HTTP/1.1 200 OK
@enduml

PlantUML: components

@startuml
left to right direction
actor "Seller" as n_signer
agent "Signing app" as n_app
component "Document server" as n_api
database "Document store" as n_docs
storage "Key token" as n_token
cloud "CA (OCSP)" as n_ca
cloud "Timestamp TSA" as n_tsa
agent "Buyer app" as n_partner
n_signer --> n_app
n_app --> n_api
n_app --> n_token
n_token ..> n_app
n_api --> n_docs
n_api --> n_ca
n_api --> n_tsa
n_partner --> n_api
@enduml

Recap

Five rules for digital signatures on business documents.

1) Sign a hash of the exact bytes, inside signed attributes. 2) The private key stays on the token; only the signature leaves it. 3) Verify the hash, the math, the chain, the dates and revocation (OCSP or CRL). 4) signingTime is a claim: get a TSA timestamp over the signature value. 5) Store the chain and the OCSP answer with the signature, so it stays provable after the certificate expires.

Numbers: at the start and at the end

MetricStartEnd
Signature intake p9535 ms260 ms
Accepted, cert revoked0/day0/day
Old signatures unprovable00

Steps

  1. Case The app hashes the exact bytes of the contract

    The seller opens contract ct_2041 in the signing app.

  2. Case The private key signs inside the token and never leaves it

    The app does not sign the file hash directly.

  3. Case The signature travels as a CMS package

    The app wraps the signature into CMS (also called PKCS#7) SignedData: algorithms, the signer's certificate with its issuer, and a signerInfo with the signed attributes and the signature value.

  4. Fix The server checks the signature in four steps

    The server hashes its copy of the file and compares it with messageDigest.

  5. Problem A revoked certificate still passes

    The thief uses the stolen token, enters the PIN that was written on a sticky note, and signs a contract for a large delivery.

  6. Fix Ask the CA: is this certificate still good?

    Before accepting a signature, the server sends an OCSP request to the responder named in the certificate.

  7. Problem Two years later the signature cannot be proven

    Contracts must stay provable for years, for audits and courts.

  8. Fix A trusted timestamp fixes the signing time

    Right after signing, the server sends the hash of the signature value to a timestamp authority (RFC 3161).

  9. Fix Store the evidence with the signature

    At signing time the server also stores the certificate chain and the OCSP answer it got right after the timestamp.

  10. Case The buyer signs the same contract

    The buyer opens the contract, the app hashes the same PDF and gets the same messageDigest.

  11. Recap Recap

    Five rules for digital signatures on business documents.

Terms

Electronic digital signature
A private-key signature over a document's hash. Anyone can check it with the public key from the certificate.
CMS (PKCS#7)
The format that packs a signature, certificates and signed attributes, with the document inside (attached) or apart (detached).
OCSP
Asking the certificate authority whether a certificate is good, revoked or unknown right now. The online alternative to a CRL.
Trusted timestamp
A timestamp authority (TSA) signs the hash of a signature value with its own time, so the signing time stays provable after the certificate expires.