# E-Signature Building Block Specification
Version 1.1; December 2025
***First developed by:*** \
Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio, in cooperation with GIZ, ITU, and DIAL.
***
***Authors to this version:***\
David Higgins and Mikael Linden
***Contributors:*** Charity Chirowamhangu, Antony Muriithi, Daniel Abadie, Norbert Nahayo, Rounak Nayak, Eric Ramirez, and Mary Metias
***Reviewers:***\
Yuliia Kravchenko and Smita Selot
***Editor:***\
Ali González-García
e-Signature cover
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
0.8
Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio
Updates to Version History and Release Notes implementation of Semantic Versioning.
Minor Updates to Description eSignature Lifecycle changed to e-Signature Deployment Models
Terminology aligned to GovSpecs 2.0 format and common ID terminology
Minor Typos/Gramatical Fixes Requirements Aligned to GovSpecs 2.0 (Required/Recommended)
# Release Notes
## **Version 1**
***
## **v1.1.0**
*Released: December 2025*
*Authors:* David Higgins and Mikael Linden
***
### 1. Overview
This release of the e-Signature Building Block was developed between September and December, 2025 by the **Cross-Functional ID Infrastructure Working Group**, a super-group of all the key Identity and Trust-related Building Blocks in GovStack (e-signature, identity, Wallet, Consent).
Release 1.1 of e-Signature is the result of a review of all 4 specifications to ensure their are aligned and consistent to a single Identity Universe. As a result, a shared ID Terminology reference document was created and linked.
### 2. Changes
#### **Section 1 Version History**
* Update Authors
* Add Release Notes
* Move to Semantic Versioning
#### **Section 2 Description**
* Change "eSignature Lifecycle" to "eSignature Deployment Models"
* Gramatical/ Minor Typo corrections
#### **Section 3 Terminology**
* Alignment to ID Common Terminology
* Move to GovSpecs 2.0 format of Headings and descriptors
* Addition of the term [Timestamp](/development-12/3-terminology#timestamp)
#### **Section 4 Key Digital Functionalities**
* Change references where incorrect to Identity Building Block
* Gramatical/Minor Typo corrections
***
## **v1.0.0 (was 23Q4)**
First published version
# 2 Description
This section provides context for this Building Block.
eSignature Building Block provides the necessary functionalities to bring handwritten signatures to the digital world. Handwritten signatures have served as a way to agree/witness a given document, yet, in today's digital world most documents are in digital form. The digital form varies between structured (XML, JSON) and unstructured documents (PDF, Word, Image, CSV, Spreadsheet). eSignatures can be added to digital documents similar to handwritten signatures achieving the same functionality.
Additionally, eSignatures improve user experience in managing the signing process as the same can be embedded directly in e-Services, leaving out the need to print out forms, sign on paper, scan, and upload/send.
eSignature provides a considerable advantage over handwritten signatures because of the availability for verification at any point in time. This allows for remote validation of signatures, content (content being the same as that during signing), identity, and time. This assurance allows us to trust a signed document remotely and can be used for legally binding agreements. Sample use cases include:
* Submitting applications to Government agencies (e.g. Child Care, Residence Registration, Marriage, etc.)
* Purchase and use banking services (i.e. making transfers, adding transfer limits, applying for loans)
* Purchasing telecom services (i.e. purchase SIM/eSIM, change contract, add a TV subscription)
* Purchase utility services (i.e. new contract for electricity, gas)
* Purchase insurance contract
With eSignature there is no need to print documents on paper anymore, saving a lot of paper and promoting a green lifestyle. This can also save money and can be calculated with an[ online calculator ](https://blog.dokobit.com/news/e-signature-calculator-check-out-how-much-you-could-save/)designed for the eSignature practice.
## 2.1 Current scope
* Ability to support eSignature for everyone.
* Ability to support eSignature through a specialized user device/card.
* The ability for third-party services (including other Building Blocks) to interact, sign, and verify the eSignatures in a standardized model.
### 2.1.1 Actors
* Users: people or applications (delegated by a user) who use the eSignature Building Block to give eSignatures.
* Services: third-party services that require a user eSignature to provide the service.
* Auditor: individual or organization that reviews the platform for any misuse (intentional or unintentional)
* Administrator: individual or team that configures the eSignature Building Block and is responsible for ensuring the functioning of the Building Block.
* Certification Authority: a certification authority that can issue a certificate as X509.
* Timestamp Authority: a trusted third party who can provide certified time.
## 2.2 eSignature deployment models
There are two deployment models available for the eSignature Building Block. Both mechanisms have their own unique advantages, therefore it is recommended to follow both for an inclusive approach.
### 2.2.1 One-Time Signature Approach
One-time signatures are one of the easiest ways to get large-scale adoption of eSignatures. This approach does not require any device to be owned by the end user. This approach relies on the work done by the ID Building Block to authenticate an end user.
One Time Signature
* User authenticates against the ID Building Block
* The user is redirected to the eSignatures Building Block
* A new key pair is created in the HSM (Hardware Security Module)
* An X509 Certificate is issued with the details from the ID Building Block (Name, Age, Gender, Location)
* The new key is used to timestamp and sign the document
* The X509 certificate is set to expire 1 minute from the time of creation
* The signed document is sent
* The private key is deleted from the HSM
### 2.2.2 SCD-based approach
The SCD (Signature Creation Device) is a personal device of the user. It could be a Mobile Phone, SIM card, Smart Card, Secure SD Card, USB Storage device, NFC Card, etc. The SCD device can be used to store the keys for long-term usage. This allows the user to interact with the ID Building Block once and create a key on the SCD. This key then can be used for signing any document without interacting with the ID Building block.
SCD Onboard
The binding of the private key with the user is called On-boarding. In this process, a user is authenticated and his key is created on the SCD.
* User authenticates against the ID Building Block
* The user is redirected to the eSignature page where his SCD device is detected
* The user is asked to select a valid SCD device and enter its security PIN/Biometric/One Time Password
* The eSignature Building Block interacts with the SCD (protocols are left open for implementation) to create a Key Pair
* A CSR (Certificate Signing Request) is created
* This request is sent to the eSignature Building Block
* The Building Block verified the ID Building Block token and the data in the CSR
* If they match then the CSR is converted to an X509 certificate and the same is issued back to the device
SCD Based Signature
The key created on the SCD device can be used by the user to digitally sign any of the documents.
* The third-party who needs to sign the document will be redirected to the eSignature Building Block
* The eSignature Building Block will ask for the pseudonym (eSignature handle) from the user
* The user provides the pseudonym to the eSignature Building Block
* The eSignature Building Block sends a notification to the SCD (Internal Protocol)
* The user is shown his choice to sign or not to sign
* Once the user signs the SCD will send the signature to the third-party
* The Digital Signature will then be attached to the given document in one of the supported formats as described by the eSignature Building Block
## 2.3 Current Scope
### 2.3.1 This Building Block must enable the user to
* View and provide consent to the document that is about to be signed
* Register the user's Signature Creation Device (SCD)
* Confirm the signature with a PIN code on the user's SCD
* View user's SCD-s and certificates
* Digitally sign the documents (PDF, Word, Excel, JSON, XML, Image)
* Use a personal device to store the keys safely
* Ability to sign the document where the user has no device
* Ability to sign a document without the involvement of ID Building Block
* Ability to sign a document using only the ID issued by the ID Building Block
User
* Ability to view the list of signings performed
### 2.3.2 This Building Block must enable other eServices to
* Invoke eSignatures to obtain a digital signature
* Sign the digital document in the desired eSignature format
* Allow a safe async way to obtain signatures
* A simple-to-use library to validate the eSignature
### 2.3.3 This Building Block must enable an auditor to
* Retrieve and review specific audit data
* Validate and get signatures on any audit data
* Audit cryptographic functioning and compliance for auditing and key security
### 2.3.4 This Building Block must enable the administrator to
* Configure the system without intervening with the signature process
* Administer without modification or tampering with the data or key security
## 2.4 eSignature library
eSignature Building Block will provide a helper library for the Services. The helper library could be used to integrate eSignatures faster.
* Get digital document digest to be sent to eSignature Building Block. Obtaining just the hash reduces the storage overhead and also avoids the privacy concern of sending the original document.
* Embedding received eSignature back into the document or attaching it in case of detached signatures.
* Validate digitally signed documents and the validity of the certificate.
## 2.5 eSignature formats
Supports the following signature formats:
* [XAdES - XML signatures](https://www.w3.org/TR/XAdES/)
* [PAdES - PDF signatures](https://www.iso.org/standard/67937.html)
* [CAdES - CMS Signatures](https://www.rfc-editor.org/rfc/rfc5126)
* [ASIC - Interoperable signatures](https://www.etsi.org/deliver/etsi_en/319100_319199/31916201/01.01.01_60/en_31916201v010101p.pdf)
* [JWS (RFC 7515)](https://www.rfc-editor.org/rfc/rfc7515)
## 2.6 Authentication and Security
In order for eSignatures to be secure and adhere to privacy regulations the eSignature Building Block uses the following levels of authentication,
* Authentication via ID Building Block: the service that uses eSignature will have to authenticate the user against the ID Building Block.
* Unique pseudonym: the service is redirected to a webpage on the eSignature portal where the user can enter a unique pseudonym known only to the user to start the signing process (without a pin, the signing will not be complete).
* Asking for a PIN code on the user's device: eSignature Building Block will send a request to the user's device so that the user can confirm the signing request with a PIN.
* The signature will be returned using an internal API protected by the Information Mediation Building Block.
## 2.7 Audit Trail and Compliance
eSignature Building Block must log all signing transactions to be compliant with current regulations. The minimum details to be logged are:
* User's identity without revealing personally identifiable information.
* Document digest.
* Timestamp of the signing.
# 3 Terminology
Terminology used within this specification.
We recognise there are common terms across all ID related Building Blocks (Identity, E-Signature, Consent, Wallet). We define these [here](https://identity.govstack.global/3-terminology/id-related-bb-common-terminology).
In addition the following terms are specific to the e-Signature Building Block.
### e-Signature
*(also known as eSignature, electronic signature, digital signature)*
A data unit which is used by a Signatory to indicate his or her link to a Document
### Certificate
Data that links a public key to a natural person and confirms the name of that person
### Signatory/User
A natural person or an application delegated by the user who can create a digital signature
### eSignature creation device (SCD)
Configured software and/or hardware used to create an eSignature. Two types of eSignature creation devices are supported:
* Local - Private keys are stored locally on mobile devices.
* Remote - Private keys are stored on the remote secure storage.
### Signing application, Signature requestor, Third-Party
An application that has the Document that needs the Signatory's signature
### Document (to be signed)
Data that needs to be signed by the Signatory. It can be any data file in an arbitrary format. Document to be signed is usually handled by a third party and made available to Signatory after signing.
### Onboarding
The process of identifying Signatory, issuing a Certificate, and binding it to an eSignature Creation Device.\
User identification is performed using Govstack's [Identity Building Block](https://identity.govstack.global).
### Hardware Security Module (HSM)
Hardware Security Module - a device or software that can store private keys safely.
### Signature Creation Device (SCD)
Signature Creation Device - Can be local or remote based on where the keys are stored.
### X509
A certificate format as defined in [V3](https://www.rfc-editor.org/rfc/rfc5280)
### Timestamp
Compliant to [RFC3161](https://www.rfc-editor.org/rfc/rfc3161)
### Sign
The process of using [SCD](#signature-creation-device-scd) or One Time signature APIs to encrypt the hash of the document.
### Certificate Signing Request (CSR)
Certificate Signing Request as per [RFC 2986](https://datatracker.ietf.org/doc/html/rfc2986)
### One time Signature
A private key is created upon authentication of the user and expires right after the signature. Should not be confused with OTS or related signature models.
### Revocation
All revocation of certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html). Follows the respective standards RFC 8954.
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
To facilitate the eSignature service as described in section 2, the Building Block must have specific Key Digital Functionalities.
## 4.1 Hardware Security Module
The Hardware Security Module (HSM) is an integral part of the eSignature Building Block. The HSM ensures the protection of a key with utmost safety. Without an HSM the key can potentially fall into the wrong hands and could result in huge mistrust. All keys used in our one-time signatures are created, used, and destroyed within the HSM. The HSM should be configured with FIPS 140-2 Level 3. This device will follow PKCS11 or JCE standards.
## 4.2 Signature Creation/Seal Device
The eSignature creation device (SCD) is the component where the user's private key would be stored. The SCD could be a Smart card, Mobile App, Sim card App, or equivalent. The SCD interacts with the eSignature Building Block using its own internal protocol. Every eSignature Building Block will support one or many such SCDs. Most of the SCD would be protected with a secure PIN/Biometrics.
The SCD should be qualified with at least one of the following FIPS 140-2/3 Level 3 or Annex II of [Regulation (EU) No 910/2014 (eIDAS)](https://en.wikipedia.org/wiki/EIDAS) or equivalent common criteria certification.
## 4.3 Timestamp
The time of a sign is an important part of the signature. Without a proper time of the signature, we can never trust the signature, as one can not find if the signature happened before its expiry or after expiry. Most often this functionality is provided by the timestamping server hosted by the CA. This service follows [RFC 3161](https://datatracker.ietf.org/doc/html/rfc3161)
## 4.4 One-Time Signing Service
This is one of the most important functionality of eSignature. This service is responsible for providing the One Time Signature API and interacts with the Hardware Security Module (HSM). This service validates the user against the Identity Building Block. A valid user is allowed to create a key in HSM and sign it. Every key created here will also need an X509 certificate. The certificate management module will publish this created X509 certificate.
Keys created during One Time Signature should be deleted after the signature process. Logs SHOULD be kept in a database of the details of the deletion. Logs MUST include timestamps and identify the user and affiliation that performed the transaction.
## 4.5 Signature Creation Device On-Boarding
eSignature creation device (SCD) On-Boarding is the module responsible for binding the SCD and user. The module interacts with the Identity Building Block and will validate the user's presence before issuing the Certificate. This module is responsible for talking to the SCD for all types of key management and administrative needs. This module is hosted on a server and would ensure the keeping of clear audit records and Know Your Customer/Client (KYC) records.
## 4.6 Signature Creation Device Signing
The SCD Signing is one of the vital functions of the eSignature Building Block. When a user holds its key in an SCD then this module is responsible for interacting with the SCD to sign any required document. This module works in asynchronous mode. A signature is requested on demand using the API. However, the module interacts with the SCD asynchronously. The module is responsible for connecting to SCD for all signing purposes.
## 4.7 Certificate Management
All certificates that are created within the SCD will be hosted in this module. The module lets everyone have their X509 public certificate hosted for any verification. The module should have an administrative ability to allow people to revoke the keys on demand. The module has to maintain the OCSP & CRL-based revocations. Key revocation is not available in Onetime Signatures as the certificate is short-lived.
## 4.8 Notification
This module is responsible for notifying the SCD device when a signature is needed. This helps the SCD to alert the user. The user can look through the notification and accept to sign the document. The module is also responsible for notification of a signature to the user's mobile phone/email/SCD. The notification to the user can be used as an audit record by the user. This interface abstracts the messaging with an omnichannel interface. The notification Building Block can be used to send notifications to the end user/device.
## 4.9 Public Observation Interface
This interface handles the necessary health, metrics, traceability and legal needs for the given Building Block. While there are no certain standards to this, it is recommended to follow the [OpenTelemetry](https://opentelemetry.io/) design to address some of the challenges. Issuance of signature certificates is usually backed by several legal regulations. The requirements can range from KYC details available upon Judicial intervention, Revocation and Transparency of the revoked certificate as per OCSP/CRL (Similar to [RFC 6961](https://datatracker.ietf.org/doc/html/rfc6961)/[RFC 5280](https://www.rfc-editor.org/rfc/rfc5280)) and Dispute Resolution.
## 4.10 Signature Backend
Once the signature is completed the signature backend keeps the signature until the eService server makes a request. Once the eService has received the Signature Token (SignatureId), It can request the eSignature BB to send the final signature. Once the Signature Token is validated the BB sends the signature. This happens over a backend-protected channel.
## 4.11 eService Callback
This is the callback service available in eService. Once the signature is complete the user will be redirected to the eService. This module is responsible for understanding the redirect request and the HTTP parameters that are passed during this redirection.
## 4.12 Signature Validation
This module is responsible for validating a digital signature. This is provided as a library. A format-specific validation library should be provided. The majority of the format adopted in this specification provides a clear explanation of how to validate the signature. But in a few specified formats like ASC, it may be necessary for the signature service to explicitly state the validation mechanism. It is also expected that the service provider will provide a library, application (optional), and online service(optional) to validate the signature.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document.
## 5.1 Hardware Security Module Compliance (REQUIRED)
HSM must be compliant to a minimum of FIPS 140-2 Level 3. This guarantees the protection of private keys. HSM/Key Management application shall not print any information about the end-use details. Keys should be created only within the HSM. This may apply to all other Building Blocks when dealing with cryptographic keys.
## 5.2 Audit (REQUIRED)
All audit logs shall be integrity-protected against tampering. The eSignature Building Block shall follow the data policy and audit logging requirements as laid out in the GovStack architecture.
## 5.3 Privacy (REQUIRED)
Signing using a single key can compromise the user's privacy in the long run. For example, a single key used to sign the consent of health form and agreement of the medical insurance could reveal that the consent and the agreement are from the same person. Generally available signed documents could be used to perform 360-degree profiling. This violates the Generic Architectural Privacy recommendation. Privacy-preserving techniques can be used in signature schemes, document storage, or reducing the key's lifespan to protect the user's privacy.
## 5.4 Logging
* The system shall provide traceability across services using trace ID or similar design patterns. (REQUIRED)
* The system shall provide logs to help debug the problems. (REQUIRED)
* The system shall not print sensitive information. (REQUIRED)
* Private Key
* User details
* Authentication Token
* Payment Token
* Signature of the document
* Full Certificate (Thumbprint is allowed to be printed)
* User PIN
* OTP
* In case a user/mobile app is involved, then logging shall provide traceability from the app to the server. (REQUIRED)
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
The eSignature Building Block has several functional layers within it. Some functional layers follow the existing set of protocols and custom protocols, While the other functional requirements are defined within this specification. In this section, we will provide a clear indication to state what blocks follow what kind of protocols.
## 6.1 Hardware Security Module
* In the case of the One-Time Signature, a Hardware Security Module (HSM) must be used to create cryptographic keys. (REQUIRED)
* It must be used to sign a certificate. (REQUIRED)
* Keys shall not be exported. (REQUIRED)
* MUST be protected well with best security practices. (REQUIRED)
## 6.2 Signature Creation/Seal Device
* Signature Creation Device (SCD) should have secure storage to protect private keys. (REQUIRED)
* SCD may have proprietary APIs with the eSignature Building Block. (REQUIRED)
* SCD is assumed to be with the user. (REQUIRED)
* A user's PIN is a must for the SCD. (REQUIRED)
* Keys shall not be exportable. (REQUIRED)
## 6.3 Timestamp
* For a valid signature, a timestamp server is a must. (REQUIRED)
* The timestamp server shall follow [RFC3161](https://www.ietf.org/rfc/rfc3161.txt). (REQUIRED)
## 6.4 Certifying Authority
* eSignature Building Block may be a certifying authority. (REQUIRED)
* If not, the Building Block shall have access to a certifying authority and be able to issue certificates or be a subordinate certification authority. (REQUIRED)
## 6.5 eSignature Service
* Service shall support the onboarding of the Signature Creation Device (SCD). (REQUIRED)
* Service shall support both the key functionalities of signing using SCD and One-Time Signature. (REQUIRED)
* The user shall be authenticated through the ID Building Block for the One-Time Signature. (REQUIRED)
* The user shall be allowed to perform a signature through a pseudonym without user login. (REQUIRED)
* Optionally can support payments through a payment gateway. (OPTIONAL)
* Shall support all the listed signature types. (REQUIRED)
* Shall support redirection and callback as per the specification. (REQUIRED)
## 6.6 Audit
* All user activities should be available for audit. (REQUIRED)
* May have the feature to tamper-proof the audit records. (REQUIRED)
* Auditors shall have the ability to get audit-proof of a transaction. (REQUIRED)
## 6.7 Certificate Management
* Shall provide the ability to list and revoke a certificate. (REQUIRED)
* The user shall have the ability to revoke their keys (API-based or through customer care). (REQUIRED)
* Certificates shall have any of the following statuses (REQUIRED):
* Active – The certificate is active and can be used for signing.
* Expired – certificates are expired and should be renewed.
* Suspended – certificate is suspended. The reason for suspension shall be provided together with status information.
* Revoked – certificate is revoked. The reason for revoking shall be provided together with status information.
* Users shall be able to view their certificates and corresponding statuses. (REQUIRED)
## 6.8 Notification
* Shall provide the ability to notify the user over email, SMS, app notification, or any other equivalent. (REQUIRED)
* The user shall be notified of failed and successful transactions. (REQUIRED)
## 6.9 Messaging Interface
* The Messaging interface should send relevant information to the logging sub-block to maintain the history of all messages sent from this Building Block, which are useful for audit purposes. (RECOMMENDED)
* The messaging interface should provide the necessary protocol, data format, and information and interface to interact with the Messaging Building Block for sending notifications to a specific target Signature Creation Device or user through a variety of channels (SMS/email/etc.) (RECOMMENDED)
**Note:** The keywords "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
## 6.11 Metrics
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Data Elements
### 7.1.1 eSignature operation
| Name | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| SignatureId | String | Unique Signature Token for signature operations. This can be a random String as well. |
| SignatureType | Enum | Can be ONETIME or SCD |
| SignatureFormat | Enum | Signature format that should be applied. Can be XAdES, CAdES, ASIC, JWS, PAdES |
| Hash | String | Hash to be signed in hex characters or base64 |
| HashType | Enum | Hash type - SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B |
| DisplayData | String | Text string to be shown on user’s device (SCD). Limited to 256 characters. |
| Certificate | String | X509 Certificate in PEM format |
| RequestTimestamp | Timestamp | Timestamp of the request |
| Signature | Signature | Signature in base64 format |
| SignatureTimestamp | String | rfc3161 asn.1 in base64 |
| ResponseTimestmap | Timestamp | Timestamp of the response |
| Status | Enum | Request status enum. Can be OK, ERROR |
| StatusDesc | String | Description of status |
| CallbackURL | URL | URL to call back with results |
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
### 7.1.2 eSignature operation header
| Name | Type | Description |
| ------------ | ------ | -------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | Jwt Token from Payments Building Block |
### 7.1.3 User's Device Onboarding
| Name | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | JWT Token from Payments Building Block |
| CSR | String | Certificate signing request PKCS#10 in PEM format |
| SCDType | Enum |
The SCD type that is used by user. Can be of REMOTE\_SCD\_APP\_APPLE, REMOTE\_SCD\_APP\_ANDROID, REMOTE\_SCD\_APP\_SE\_APPLE, REMOTE\_SCD\_APP\_SE\_ANDROID, REMOTE\_SCD\_SIM, REMOTE\_SCD\_ESIM,
REMOTE\_SCD\_SMARTID
|
| SCDKeyId | Number | Key id for case the SCD has multiple certificates |
| SCDRemoteId | String |
Remote identifier for the SCD communication, for REMOTE\_SCD\_APP\* devices it is push ID, for REMOTE\_SCD\_ESIM/ REMOTE\_SCD\_SIM it is msisdn
For
REMOTE\_SCD\_SMARTID it is citizen id
|
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
| CertReqTimestamp | Timestamp | Timestamp for the certificate request |
| CertId | String | Unique identifier for the certificate, SCD, Key id combo |
| Certificate | String | X509 Certificate in PEM format in ACTIVE status |
| CertRespTimestamp | Timestamp | Timestamp for the Certificate response |
| Status | Enum | Request status. Can be of of OK, ERROR |
| StatusDesc | String | Description of status |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
A Set of microservices is defined to receive requests from other GovStack-compatible Building Blocks and third-party Services with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks or third-party services. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
eSignature Building Block must expose its microservices through RESTful API interfaces as defined by [OpenAPI v3+ standards](https://swagger.io/specification/). A summary of the APIS exposed by this Building Block is summarized in the table below.
### 8.1 eSignature with one-time certificate
{% openapi src="" path="/{version}/sign/onetime" method="post" %}
{% endopenapi %}
### 8.2 eSignature with user's eSignature creation device (SCD)
#### 8.2.1 Certificate creation
{% openapi src="" path="/{version}/cert/create" method="post" %}
{% endopenapi %}
#### 8.2.2 List certificates
{% openapi src="" path="/{version}/cert/list" method="get" %}
{% endopenapi %}
#### 8.2.3 Update certificate
{% openapi src="" path="/{version}/cert/{certificateId}" method="patch" %}
{% endopenapi %}
The update API can be used to revoke the certificate. All revoked certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html).
#### 8.2.4 eSignature with user's device
{% openapi src="" path="/{version}/sign/pseudonym" method="post" %}
{% endopenapi %}
#### 8.2.5 Webservice to enter user pseudonym
{% openapi src="" path="/{version}/sign/interactivePseudonym" method="get" %}
{% endopenapi %}
#### 8.2.6 User pseudonym API
{% openapi src="" path="/{version}/token/pseodonym/{pseudonym}" method="get" %}
{% endopenapi %}
#### 8.2.7 Get signature response
{% openapi src="" path="/{version}/sign/response/{signatureId}" method="get" %}
{% endopenapi %}
#### 8.2.8 Callback service API
{% openapi src="" path="/{version}/esignature/callback" method="get" %}
{% endopenapi %}
### 8.3 Audit log
{% openapi src="" path="/{version}/audit/log" method="get" %}
{% endopenapi %}
# 9 Internal Workflows
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
### 9.1 Workflow for one-time signing
This internal workflow is used by the eSignature Building Block to provide one-time signature. In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Frontend constitutes the functionality running in the user's internet browser and backend refers to the API running on a server.
Workflow is kicked off by a third party using the eSignature client library to get a digest of document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. If required by the Building Block configuration, it will also check if the Payment token supplied by the request is valid. In the eSignature Building Block front-end, the user selects the option to use National ID to do a one-time signature. Then the user is redirected to the Identity Building Block to authenticate and user data is returned back to the eSignature Building Block back-end after completion of all standard interaction API calls. Then a Host Security Module (HSM) hardware is used to generate a temporary keypair. From that keypair, the public part is exported as a Certificate Signing Request (CSR). CSR is submitted to a Certificate Authority (CA) instance that will generate and publish a short-lived (1-minute) certificate based on the supplied CA.
After the certificate has been created the private key in the Hardware Security Module (HSM) is used to sign a document digest. After the document digest is signed, a timestamp is requested on the signature from the timestamping service. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. The signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the e-Service provider using the callback URL and signature ID. After receiving the signature ID the e-Service provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant HSM
participant ID BB
participant CA
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB frontend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt One time Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects National ID based model
e-Signature BB frontend->>ID BB: Browser redirects for user authentication
deactivate e-Signature BB frontend
activate ID BB
ID BB->>ID BB:
Note right of ID BB: User logins using National ID
ID BB->>e-Signature BB frontend: Browser redirects to callback URL with authorization code
deactivate ID BB
activate e-Signature BB frontend
e-Signature BB frontend->>e-Signature BB backend: authorization code & document hash
activate e-Signature BB backend
e-Signature BB backend->>ID BB: Multiple API exchanges
activate ID BB
ID BB-->>e-Signature BB backend: User data
deactivate ID BB
e-Signature BB backend->>HSM: Create key with user data
activate HSM
HSM-->>e-Signature BB backend: CSR
deactivate HSM
e-Signature BB backend->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB backend: Certificate
deactivate CA
e-Signature BB backend-->>HSM: Sign with key & delete
activate HSM
HSM-->>e-Signature BB backend: signature
deactivate HSM
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: api call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
### 9.2 Workflows for signing with the user's device
In case of signing in with the user's device, there are multiple workflows:
* Register the user's Signature Creation Device (SCD).
* Signing with the user's Signature Creation Device (SCD).
#### 9.2.1 Register user's Signature Creation Device (SCD)
Registering starts with the user authenticating against the ID Building Block and getting the authentication token. After the user is authenticated, a Remote SCD service is called to onboard the user. There is a request sent to the user's device to create keys. After keys are generated the public part of the keypair is sent to the eSignature Building Block as a Certificate Signing Request (CSR). CSR is submitted to a certificate authority (CA) instance that will generate and publish a certificate based on the supplied CA.
{% @mermaid/diagram content="sequenceDiagram
actor User
User->>ID BB: Authenticate with e-signature scope
activate ID BB
ID BB-->>User: Access token
User->>e-Signature BB: Provide authentication token
activate e-Signature BB
e-Signature BB->>ID BB: Invoke introspect API with Access token
ID BB-->>e-Signature BB: user details, user PSUT
deactivate ID BB
e-Signature BB->>Remote SCD Service: onboard user
activate Remote SCD Service
Remote SCD Service->>User: Accept key creation, choose PIN
User-->>Remote SCD Service: CSR
Note right of User: User accepts key creation and choose PIN with a mobile device
Remote SCD Service-->>e-Signature BB: CSR
deactivate Remote SCD Service
e-Signature BB->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB: Certificate
deactivate CA
e-Signature BB-->>User: SCD Onboarded
deactivate e-Signature BB
" %}
#### 9.2.2 Use the user's Signature Creation Device (SCD) for signing
This internal workflow is for signing with the user's Signature Creation Device (SCD). In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Front-end constitutes the functionality running in the user's internet browser and back-end refers to the API running on a server.
First, eService fetches the client-side library from the eSignature Building Block front-end. The client library is used to create a digest of the document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. In the eSignature Building Block front-end, the user selects the option to use the SCD model. The pseudonym entry page is shown and the user enters the pseudonym, which is sent to the e-Signature Building Block back-end to receive the generated pseudonym token. After receiving a pseudonym token, eSignature Building Block back-end can be invoked to create the signature. eSignature Building Block back-end will then invoke Remote SCD Service to create the signature. Remote SCD service will send a notification to the user's SCD with a notification and request to put PIN code. After the user enters the PIN code, a signature is generated and sent back to the Remote SCD Service. Remote SCD Service will then send the signature back to the eSignature Building Block back-end.
After the Signature is received, eSignature Building Block back-end will send a request to the Timestamping Authority for a timestamp on the signature to be created. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. Signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the eService provider using the callback URL and signature ID. After receiving the signature ID the eService provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant Remote SCD Service
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB backend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB backend
e-Signature BB backend-->>e-Signature BB frontend: Page to display the available eSignature models
deactivate e-Signature BB backend
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt SCD Based Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects "Use SCD to Sign" and enters pseodonym
e-Signature BB frontend->>e-Signature BB backend: API call /sign/pseudonym
activate e-Signature BB backend
e-Signature BB backend->>Remote SCD Service: document hash, SCD Remote Id
activate Remote SCD Service
Remote SCD Service->>Remote SCD Service:
Note right of Remote SCD Service: User enters Security PIN
Remote SCD Service-->>e-Signature BB backend: Signature
deactivate Remote SCD Service
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: API call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
## 10.1 Example Cross-Building Block Workflows
Some common workflows that leverage the eSignature Building Block can be found here:
## 10.2 Key Decision Log
[A historical log of key decisions regarding this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/94535681/E-Signature+Objective+Design+Consideration+-+Brainstorm)
## 10.3 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/276594796/Future+consideration)
## 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/v3ciRXSd).
# E-Signature
Developed by Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio, in cooperation with GIZ, ITU, and DIAL
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
0.8
Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio
# 2 Description
This section provides context for this Building Block.
eSignature Building Block provides the necessary functionalities to bring handwritten signatures to the digital world. Handwritten signatures have served as a way to agree/witness a given document, yet, in today's digital world most documents are in digital form. The digital form varies between structured (XML, JSON) and unstructured documents (PDF, Word, Image, CSV, Spreadsheet). eSignatures can be added to digital documents similar to handwritten signatures achieving the same functionality.
Additionally, eSignatures improve user experience in managing the signing process as the same can be embedded directly in e-Services, leaving out the need to print out forms, sign on paper, scan, and upload/send.
eSignature provides a considerable advantage over handwritten signatures because of the availability for verification at any point in time. This allows for remote validation of signatures, content (content being the same as that during signing), identity, and time. This assurance allows us to trust a signed document remotely and can be used for legally binding agreements. Sample use cases include:
* Submitting applications to Government agencies (e.g. Child Care, Residence Registration, Marriage, etc.)
* Purchase and use banking services (i.e. making transfers, adding transfer limits, applying for loans)
* Purchasing telecom services (i.e. purchase SIM/eSIM, change contract, add a TV subscription)
* Purchase utility services (i.e. new contract for electricity, gas)
* Purchase insurance contract
With eSignature there is no need to print documents on paper anymore, saving a lot of paper and promoting a green lifestyle. This can also save money and can be calculated with an[ online calculator ](https://blog.dokobit.com/news/e-signature-calculator-check-out-how-much-you-could-save/)designed for the eSignature practice.
## 2.1 Current scope
* Ability to support eSignature for everyone.
* Ability to support eSignature through a specialized user device/card.
* The ability for third-party services (including other Building Blocks) to interact, sign, and verify the eSignatures in a standardized model.
### 2.1.1 Actors
* Users: people or applications (delegated by a user) who use the eSignature Building Block to give eSignatures.
* Services: third-party services that require a user eSignature to provide the service.
* Auditor: individual or organization that reviews the platform for any misuse (intentional or unintentional)
* Administrator: individual or team that configures the eSignature Building Block and is responsible for ensuring the functioning of the Building Block.
* Certification Authority: a certification authority that can issue a certificate as X509.
* Timestamp Authority: a trusted third party who can provide certified time.
## 2.2 eSignature Lifecycle
There are two lifecycles available for the eSignature Building Block. Both mechanisms have their own unique advantages, therefore it is recommended to follow both for an inclusive approach.
### 2.2.1 One-Time Signature Approach
One-time signatures are one of the easiest ways to get large-scale adoption of eSignatures. This approach does not require any device to be owned by the end user. This approach relies on the work done by the ID Building Block to authenticate an end user.
One Time Signature
* User authenticates against the ID Building Block
* The user is redirected to the eSignatures Building Block
* A new key pair is created in the HSM (Hardware Security Module)
* An X509 Certificate is issued with the details from the ID Building Block (Name, Age, Gender, Location)
* The new key is used to timestamp and sign the document
* The X509 certificate is set to expire 1 minute from the time of creation
* The signed document is sent
* The private key is deleted from the HSM
### 2.2.2 SCD-based approach
The SCD (Signature Creation Device) is a personal device of the user. It could be a Mobile Phone, SIM card, Smart Card, Secure SD Card, USB Storage device, NFC Card, etc. The SCD device can be used to store the keys for long-term usage. This allows the user to interact with the ID Building Block once and create a key on the SCD. This key then can be used for signing any document without interacting with the ID Building block.
SCD Onboard
The binding of the private key with the user is called On-boarding. In this process, a user is authenticated and his key is created on the SCD.
* User authenticates against the ID Building Block
* The user is redirected to the eSignature page where his SCD device is detected
* The user is asked to select a valid SCD device and enter its security PIN/Biometric/One Time Password
* The eSignature Building Block interacts with the SCD (protocols are left open for implementation) to create a Key Pair
* A CSR (Certificate Signing Request) is created
* This request is sent to the eSignature Building Block
* The Building Block verified the ID Building Block token and the data in the CSR
* If they match then the CSR is converted to an X509 certificate and the same is issued back to the device
SCD Based Signature
The key created on the SCD device can be used by the user to digitally sign any of the documents.
* The third-party who needs to sign the document will be redirected to the eSignature Building Block
* The eSignature Building Block will ask for the pseudonym (eSignature handle) from the user
* The user provides the pseudonym to the eSignature Building Block
* The eSignature Building Block sends a notification to the SCD (Internal Protocol)
* The user is shown his choice to sign or not to sign
* Once the user signs the SCD will send the signature to the third-party
* The Digital Signature will then be attached to the given document in one of the supported formats as described by the eSignature Building Block
## 2.3 Current Scope
### 2.3.1 This Building Block must enable the user to
* View and provide consent to the document that is about to be signed
* Register the user's Signature Creation Device (SCD)
* Confirm the signature with a PIN code on the user's SCD
* View user's SCD-s and certificates
* Digitally sign the documents (PDF, Word, Excel, JSON, XML, Image)
* Use a personal device to store the keys safely
* Ability to sign the document where the user has no device
* Ability to sign a document without the involvement of ID Building Block
* Ability to sign a document using only the ID issued by the ID Building Block
User
* Ability to view the list of signings performed
### 2.3.2 This Building Block must enable other eServices to
* Invoke eSignatures to obtain a digital signature
* Sign the digital document in the desired eSignature format
* Allow a safe async way to obtain signatures
* A simple-to-use library to validate the eSignature
### 2.3.3 This Building Block must enable an auditor to
* Retrieve and review specific audit data
* Validate and get signatures on any audit data
* Audit cryptographic functioning and compliance for auditing and key security
### 2.3.4 This Building Block must enable the administrator to
* Configure the system without intervening with the signature process
* Administer without modification or tampering with the data or key security
## 2.4 eSignature library
eSignature Building Block will provide a helper library for the Services. The helper library could be used to integrate eSignatures faster.
* Get digital document digest to be sent to eSignature Building Block. Obtaining just the hash reduces the storage overhead and also avoids the privacy concern of sending the original document.
* Embedding received eSignature back into the document or attaching it in case of detached signatures.
* Validate digitally signed documents and the validity of the certificate.
## 2.5 eSignature formats
Supports the following signature formats:
* [XAdES - XML signatures](https://www.w3.org/TR/XAdES/)
* [PAdES - PDF signatures](https://www.iso.org/standard/67937.html)
* [CAdES - CMS Signatures](https://www.rfc-editor.org/rfc/rfc5126)
* [ASIC - Interoperable signatures](https://www.etsi.org/deliver/etsi_en/319100_319199/31916201/01.01.01_60/en_31916201v010101p.pdf)
* [JWS (RFC 7515)](https://www.rfc-editor.org/rfc/rfc7515)
## 2.6 Authentication and Security
In order for eSignatures to be secure and adhere to privacy regulations the eSignature Building Block uses the following levels of authentication,
* Authentication via ID Building Block: the service that uses eSignature will have to authenticate the user against the ID Building Block.
* Unique pseudonym: the service is redirected to a webpage on the eSignature portal where the user can enter a unique pseudonym known only to the user to start the signing process (without a pin, the signing will not be complete).
* Asking for a PIN code on the user's device: eSignature Building Block will send a request to the user's device so that the user can confirm the signing request with a PIN.
* The signature will be returned using an internal API protected by the Information Mediation Building Block.
## 2.7 Audit Trail and Compliance
eSignature Building Block must log all signing transactions to be compliant with current regulations. The minimum details to be logged are:
* User's identity without revealing personally identifiable information.
* Document digest.
* Timestamp of the signing.
# 3 Terminology
Terminology used within this specification.
| **Term** | **Description** |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| eSignature, e-Signature, electronic signature, digital signature | A data unit which is used by a Signatory to indicate his or her link to a Document |
| Certificate | Data that links a public key to a natural person and confirms the name of that person |
| Signatory/User | A natural person or an application delegated by the user who can create a digital signature |
| eSignature creation device (SCD) |
Configured software and/or hardware used to create an eSignature. Two types of eSignature creation devices are supported: \* Local - Private keys are stored locally on mobile devices. \* Remote - Private keys are stored on the remote secure storage.
|
| Signing application, Signature requestor, Third-Party | An application that has the Document that needs the Signatory's signature |
| Document (to be signed) | Data that needs to be signed by the Signatory. It can be any data file in an arbitrary format. Document to be signed is usually handled by a third party and made available to Signatory after signing. |
| Onboarding |
The process of identifying Signatory, issuing a Certificate, and binding it to an eSignature Creation Device. User identification is performed using Govstack's Identity Building Block.
|
| HSM | Hardware Security Module - a device or software that can store private keys safely. |
| SCD | Signature Creation Device - Can be local or remote based on where the keys are stored. |
| X509 | A certificate format as defined in [V3](https://www.rfc-editor.org/rfc/rfc5280) |
| Timestamp | Compliant to [RFC3161](https://www.rfc-editor.org/rfc/rfc3161) |
| Sign | The process of using SCD or One Time signature APIs to encrypt the hash of the document. |
| CSR | Certificate Signing Request as per [RFC 2986](https://datatracker.ietf.org/doc/html/rfc2986) |
| One time Signature | A private key is created upon authentication of the user and expires right after the signature. Should not be confused with OTS or related signature models. |
| Revocation | All revocation of certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html). Follows the respective standards RFC 8954. |
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
To facilitate the eSignature service as described in section 2, the Building Block must have specific Key Digital Functionalities.
## 4.1 Hardware Security Module
The Hardware Security Module (HSM) is an integral part of the eSignature Building Block. The HSM ensures the protection of a key with utmost safety. Without an HSM the key can potentially fall into the wrong hands and could result in huge mistrust. All keys used in our one-time signatures are created, used, and destroyed within the HSM. The HSM should be configured with FIPS 140-2 Level 3. This device will follow PKCS11 or JCE standards.
## 4.2 Signature Creation/Seal Device
The eSignature creation device (SCD) is the component where the user's private key would be stored. The SCD could be a Smart card, Mobile App, Sim card App, or equivalent. The SCD interacts with the eSignature Building Block using its own internal protocol. Every eSignature Building Block will support one or many such SCDs. Most of the SCD would be protected with a secure PIN/Biometrics.
The SCD should be qualified with at least one of the following FIPS 140-2/3 Level 3 or Annex II of [Regulation (EU) No 910/2014 (eIDAS)](https://en.wikipedia.org/wiki/EIDAS) or equivalent common criteria certification.
## 4.3 Timestamp
The time of a sign is an important part of the signature. Without a proper time of the signature, we can never trust the signature, as one can not find if the signature happened before its expiry or after expiry. Most often this functionality is provided by the timestamping server hosted by the CA. This service follows [RFC 3161](https://datatracker.ietf.org/doc/html/rfc3161)
## 4.4 One-Time Signing Service
This is one of the most important functionality of eSignature. This service is responsible for providing the One Time Signature API and interacts with the Hardware Security Module (HSM). This service validates the user against the Authorization Building Block. A valid user is allowed to create a key in HSM and sign it. Every key created here will also need an X509 certificate. The certificate management module will publish this created X509 certificate.
Keys created during One Time Signature should be deleted after the signature process. Logs SHOULD be kept in a database of the details of the deletion. Logs MUST include timestamps and identify the user and affiliation that performed the transaction.
## 4.5 Signature Creation Device On-Boarding
eSignature creation device (SCD) On-Boarding is the module responsible for binding the SCD and user. The module interacts with the Identity Building Block and will validate the user's presence before issuing the Certificate. This module is responsible for talking to the SCD for all types of key management and administrative needs. This module is hosted on a server and would ensure the keeping of clear audit records and Know Your Customer/Client (KYC) records.
## 4.6 Signature Creation Device Signing
The SCD Signing is one of the vital functions of the eSignature Building Block. When a user holds its key in an SCD then this module is responsible for interacting with the SCD to sign any required document. This module works in asynchronous mode. A signature is requested on demand using the API. However, the module interacts with the SCD asynchronously. The module is responsible for connecting to SCD for all signing purposes.
## 4.7 Certificate Management
All certificates that are created within the SCD will be hosted in this module. The module lets everyone have their X509 public certificate hosted for any verification. The module should have an administrative ability to allow people to revoke the keys on demand. The module has to maintain the OCSP & CRL-based revocations. Key revocation is not available in Onetime Signatures as the certificate is short-lived.
## 4.8 Notification
This module is responsible for notifying the SCD device when a signature is needed. This helps the SCD to alert the user. The user can look through the notification and accept to sign the document. The module is also responsible for notification of a signature to the user's mobile phone/email/SCD. The notification to the user can be used as an audit record by the user. This interface abstracts the messaging with an omnichannel interface. The notification Building Block can be used to send notifications to the end user/device.
## 4.9 Public Observation Interface
This interface handles the necessary health, metrics, traceability and legal needs for the given Building Block. While there are no certain standards to this, it is recommended to follow the [OpenTelemetry](https://opentelemetry.io/) design to address some of the challenges. Issuance of signature certificates is usually backed by several legal regulations. The requirements can range from KYC details available upon Judicial intervention, Revocation and Transparency of the revoked certificate as per OCSP/CRL (Similar to [RFC 6961](https://datatracker.ietf.org/doc/html/rfc6961)/[RFC 5280](https://www.rfc-editor.org/rfc/rfc5280)) and Dispute Resolution.
## 4.10 Signature Backend
Once the signature is completed the signature backend keeps the signature until the eService server makes a request. Once the eService has received the Signature Token (SignatureId), It can request the eSignature BB to send the final signature. Once the Signature Token is validated the BB sends the signature. This happens over a backend-protected channel.
## 4.11 eService Callback
This is the callback service available in eService. Once the signature is complete the user will be redirected to the eService. This module is responsible for understanding the redirect request and the HTTP parameters that are passed during this redirection.
## 4.12 Signature Validation
This module is responsible for validating a digital signature. This is provided as a library. A format-specific validation library should be provided. The majority of the format adopted in this specification provides a clear explanation of how to validate the signature. But in a few specified formats like ASC, it may be necessary for the signature service to explicitly state the validation mechanism. It is also expected that the service provider will provide a library, application (optional), and online service(optional) to validate the signature.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document.
## 5.1 Hardware Security Module Compliance (REQUIRED)
HSM must be compliant to a minimum of FIPS 140-2 Level 3. This guarantees the protection of private keys. HSM/Key Management application shall not print any information about the end-use details. Keys should be created only within the HSM. This may apply to all other Building Blocks when dealing with cryptographic keys.
## 5.2 Audit (REQUIRED)
All audit logs shall be integrity-protected against tampering. The eSignature Building Block shall follow the data policy and audit logging requirements as laid out in the GovStack architecture.
## 5.3 Privacy (REQUIRED)
Signing using a single key can compromise the user's privacy in the long run. For example, a single key used to sign the consent of health form and agreement of the medical insurance could reveal that the consent and the agreement are from the same person. Generally available signed documents could be used to perform 360-degree profiling. This violates the Generic Architectural Privacy recommendation. Privacy-preserving techniques can be used in signature schemes, document storage, or reducing the key's lifespan to protect the user's privacy.
## 5.4 Logging
* The system shall provide traceability across services using trace ID or similar design patterns. (REQUIRED)
* The system shall provide logs to help debug the problems. (REQUIRED)
* The system shall not print sensitive information. (REQUIRED)
* Private Key
* User details
* Authentication Token
* Payment Token
* Signature of the document
* Full Certificate (Thumbprint is allowed to be printed)
* User PIN
* OTP
* In case a user/mobile app is involved, then logging shall provide traceability from the app to the server. (REQUIRED)
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
The eSignature Building Block has several functional layers within it. Some functional layers follow the existing set of protocols and custom protocols, While the other functional requirements are defined within this specification. In this section, we will provide a clear indication to state what blocks follow what kind of protocols.
## 6.1 Hardware Security Module
* In the case of the One-Time Signature, a Hardware Security Module (HSM) must be used to create cryptographic keys. (REQUIRED)
* It must be used to sign a certificate. (REQUIRED)
* Keys shall not be exported. (REQUIRED)
* MUST be protected well with best security practices. (REQUIRED)
## 6.2 Signature Creation/Seal Device
* Signature Creation Device (SCD) should have secure storage to protect private keys. (REQUIRED)
* SCD may have proprietary APIs with the eSignature Building Block. (REQUIRED)
* SCD is assumed to be with the user. (REQUIRED)
* A user's PIN is a must for the SCD. (REQUIRED)
* Keys shall not be exportable. (REQUIRED)
## 6.3 Timestamp
* For a valid signature, a timestamp server is a must. (REQUIRED)
* The timestamp server shall follow [RFC3161](https://www.ietf.org/rfc/rfc3161.txt). (REQUIRED)
## 6.4 Certifying Authority
* eSignature Building Block may be a certifying authority. (REQUIRED)
* If not, the Building Block shall have access to a certifying authority and be able to issue certificates or be a subordinate certification authority. (REQUIRED)
## 6.5 eSignature Service
* Service shall support the onboarding of the Signature Creation Device (SCD). (REQUIRED)
* Service shall support both the key functionalities of signing using SCD and One-Time Signature. (REQUIRED)
* The user shall be authenticated through the ID Building Block for the One-Time Signature. (REQUIRED)
* The user shall be allowed to perform a signature through a pseudonym without user login. (REQUIRED)
* Optionally can support payments through a payment gateway. (OPTIONAL)
* Shall support all the listed signature types. (REQUIRED)
* Shall support redirection and callback as per the specification. (REQUIRED)
## 6.6 Audit
* All user activities should be available for audit. (REQUIRED)
* May have the feature to tamper-proof the audit records. (REQUIRED)
* Auditors shall have the ability to get audit-proof of a transaction. (REQUIRED)
## 6.7 Certificate Management
* Shall provide the ability to list and revoke a certificate. (REQUIRED)
* The user shall have the ability to revoke their keys (API-based or through customer care). (REQUIRED)
* Certificates shall have any of the following statuses (REQUIRED):
* Active – The certificate is active and can be used for signing.
* Expired – certificates are expired and should be renewed.
* Suspended – certificate is suspended. The reason for suspension shall be provided together with status information.
* Revoked – certificate is revoked. The reason for revoking shall be provided together with status information.
* Users shall be able to view their certificates and corresponding statuses. (REQUIRED)
## 6.8 Notification
* Shall provide the ability to notify the user over email, SMS, app notification, or any other equivalent. (REQUIRED)
* The user shall be notified of failed and successful transactions. (REQUIRED)
## 6.9 Messaging Interface
* The Messaging interface should send relevant information to the logging sub-block to maintain the history of all messages sent from this Building Block, which are useful for audit purposes. (RECOMMENDED)
* The messaging interface should provide the necessary protocol, data format, and information and interface to interact with the Messaging Building Block for sending notifications to a specific target Signature Creation Device or user through a variety of channels (SMS/email/etc.) (RECOMMENDED)
**Note:** The keywords "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
## 6.11 Metrics
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Data Elements
### 7.1.1 eSignature operation
| Name | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| SignatureId | String | Unique Signature Token for signature operations. This can be a random String as well. |
| SignatureType | Enum | Can be ONETIME or SCD |
| SignatureFormat | Enum | Signature format that should be applied. Can be XAdES, CAdES, ASIC, JWS, PAdES |
| Hash | String | Hash to be signed in hex characters or base64 |
| HashType | Enum | Hash type - SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B |
| DisplayData | String | Text string to be shown on user’s device (SCD). Limited to 256 characters. |
| Certificate | String | X509 Certificate in PEM format |
| RequestTimestamp | Timestamp | Timestamp of the request |
| Signature | Signature | Signature in base64 format |
| SignatureTimestamp | String | rfc3161 asn.1 in base64 |
| ResponseTimestmap | Timestamp | Timestamp of the response |
| Status | Enum | Request status enum. Can be OK, ERROR |
| StatusDesc | String | Description of status |
| CallbackURL | URL | URL to call back with results |
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
### 7.1.2 eSignature operation header
| Name | Type | Description |
| ------------ | ------ | -------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | Jwt Token from Payments Building Block |
### 7.1.3 User's Device Onboarding
| Name | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | JWT Token from Payments Building Block |
| CSR | String | Certificate signing request PKCS#10 in PEM format |
| SCDType | Enum |
The SCD type that is used by user. Can be of REMOTE\_SCD\_APP\_APPLE, REMOTE\_SCD\_APP\_ANDROID, REMOTE\_SCD\_APP\_SE\_APPLE, REMOTE\_SCD\_APP\_SE\_ANDROID, REMOTE\_SCD\_SIM, REMOTE\_SCD\_ESIM,
REMOTE\_SCD\_SMARTID
|
| SCDKeyId | Number | Key id for case the SCD has multiple certificates |
| SCDRemoteId | String |
Remote identifier for the SCD communication, for REMOTE\_SCD\_APP\* devices it is push ID, for REMOTE\_SCD\_ESIM/ REMOTE\_SCD\_SIM it is msisdn
For
REMOTE\_SCD\_SMARTID it is citizen id
|
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
| CertReqTimestamp | Timestamp | Timestamp for the certificate request |
| CertId | String | Unique identifier for the certificate, SCD, Key id combo |
| Certificate | String | X509 Certificate in PEM format in ACTIVE status |
| CertRespTimestamp | Timestamp | Timestamp for the Certificate response |
| Status | Enum | Request status. Can be of of OK, ERROR |
| StatusDesc | String | Description of status |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
A Set of microservices is defined to receive requests from other GovStack-compatible Building Blocks and third-party Services with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks or third-party services. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
eSignature Building Block must expose its microservices through RESTful API interfaces as defined by [OpenAPI v3+ standards](https://swagger.io/specification/). A summary of the APIS exposed by this Building Block is summarized in the table below.
### 8.1 eSignature with one-time certificate
{% openapi src="" path="/{version}/sign/onetime" method="post" %}
{% endopenapi %}
### 8.2 eSignature with user's eSignature creation device (SCD)
#### 8.2.1 Certificate creation
{% openapi src="" path="/{version}/cert/create" method="post" %}
{% endopenapi %}
#### 8.2.2 List certificates
{% openapi src="" path="/{version}/cert/list" method="get" %}
{% endopenapi %}
#### 8.2.3 Update certificate
{% openapi src="" path="/{version}/cert/{certificateId}" method="patch" %}
{% endopenapi %}
The update API can be used to revoke the certificate. All revoked certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html).
#### 8.2.4 eSignature with user's device
{% openapi src="" path="/{version}/sign/pseudonym" method="post" %}
{% endopenapi %}
#### 8.2.5 Webservice to enter user pseudonym
{% openapi src="" path="/{version}/sign/interactivePseudonym" method="get" %}
{% endopenapi %}
#### 8.2.6 User pseudonym API
{% openapi src="" path="/{version}/token/pseodonym/{pseudonym}" method="get" %}
{% endopenapi %}
#### 8.2.7 Get signature response
{% openapi src="" path="/{version}/sign/response/{signatureId}" method="get" %}
{% endopenapi %}
#### 8.2.8 Callback service API
{% openapi src="" path="/{version}/esignature/callback" method="get" %}
{% endopenapi %}
### 8.3 Audit log
{% openapi src="" path="/{version}/audit/log" method="get" %}
{% endopenapi %}
# 9 Internal Workflows
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
### 9.1 Workflow for one-time signing
This internal workflow is used by the eSignature Building Block to provide one-time signature. In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Frontend constitutes the functionality running in the user's internet browser and backend refers to the API running on a server.
Workflow is kicked off by a third party using the eSignature client library to get a digest of document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. If required by the Building Block configuration, it will also check if the Payment token supplied by the request is valid. In the eSignature Building Block front-end, the user selects the option to use National ID to do a one-time signature. Then the user is redirected to the Identity Building Block to authenticate and user data is returned back to the eSignature Building Block back-end after completion of all standard interaction API calls. Then a Host Security Module (HSM) hardware is used to generate a temporary keypair. From that keypair, the public part is exported as a Certificate Signing Request (CSR). CSR is submitted to a Certificate Authority (CA) instance that will generate and publish a short-lived (1-minute) certificate based on the supplied CA.
After the certificate has been created the private key in the Hardware Security Module (HSM) is used to sign a document digest. After the document digest is signed, a timestamp is requested on the signature from the timestamping service. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. The signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the e-Service provider using the callback URL and signature ID. After receiving the signature ID the e-Service provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant HSM
participant ID BB
participant CA
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB frontend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt One time Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects National ID based model
e-Signature BB frontend->>ID BB: Browser redirects for user authentication
deactivate e-Signature BB frontend
activate ID BB
ID BB->>ID BB:
Note right of ID BB: User logins using National ID
ID BB->>e-Signature BB frontend: Browser redirects to callback URL with authorization code
deactivate ID BB
activate e-Signature BB frontend
e-Signature BB frontend->>e-Signature BB backend: authorization code & document hash
activate e-Signature BB backend
e-Signature BB backend->>ID BB: Multiple API exchanges
activate ID BB
ID BB-->>e-Signature BB backend: User data
deactivate ID BB
e-Signature BB backend->>HSM: Create key with user data
activate HSM
HSM-->>e-Signature BB backend: CSR
deactivate HSM
e-Signature BB backend->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB backend: Certificate
deactivate CA
e-Signature BB backend-->>HSM: Sign with key & delete
activate HSM
HSM-->>e-Signature BB backend: signature
deactivate HSM
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: api call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
### 9.2 Workflows for signing with the user's device
In case of signing in with the user's device, there are multiple workflows:
* Register the user's Signature Creation Device (SCD).
* Signing with the user's Signature Creation Device (SCD).
#### 9.2.1 Register user's Signature Creation Device (SCD)
Registering starts with the user authenticating against the ID Building Block and getting the authentication token. After the user is authenticated, a Remote SCD service is called to onboard the user. There is a request sent to the user's device to create keys. After keys are generated the public part of the keypair is sent to the eSignature Building Block as a Certificate Signing Request (CSR). CSR is submitted to a certificate authority (CA) instance that will generate and publish a certificate based on the supplied CA.
{% @mermaid/diagram content="sequenceDiagram
actor User
User->>ID BB: Authenticate with e-signature scope
activate ID BB
ID BB-->>User: Access token
User->>e-Signature BB: Provide authentication token
activate e-Signature BB
e-Signature BB->>ID BB: Invoke introspect API with Access token
ID BB-->>e-Signature BB: user details, user PSUT
deactivate ID BB
e-Signature BB->>Remote SCD Service: onboard user
activate Remote SCD Service
Remote SCD Service->>User: Accept key creation, choose PIN
User-->>Remote SCD Service: CSR
Note right of User: User accepts key creation and choose PIN with a mobile device
Remote SCD Service-->>e-Signature BB: CSR
deactivate Remote SCD Service
e-Signature BB->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB: Certificate
deactivate CA
e-Signature BB-->>User: SCD Onboarded
deactivate e-Signature BB
" %}
#### 9.2.2 Use the user's Signature Creation Device (SCD) for signing
This internal workflow is for signing with the user's Signature Creation Device (SCD). In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Front-end constitutes the functionality running in the user's internet browser and back-end refers to the API running on a server.
First, eService fetches the client-side library from the eSignature Building Block front-end. The client library is used to create a digest of the document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. In the eSignature Building Block front-end, the user selects the option to use the SCD model. The pseudonym entry page is shown and the user enters the pseudonym, which is sent to the e-Signature Building Block back-end to receive the generated pseudonym token. After receiving a pseudonym token, eSignature Building Block back-end can be invoked to create the signature. eSignature Building Block back-end will then invoke Remote SCD Service to create the signature. Remote SCD service will send a notification to the user's SCD with a notification and request to put PIN code. After the user enters the PIN code, a signature is generated and sent back to the Remote SCD Service. Remote SCD Service will then send the signature back to the eSignature Building Block back-end.
After the Signature is received, eSignature Building Block back-end will send a request to the Timestamping Authority for a timestamp on the signature to be created. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. Signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the eService provider using the callback URL and signature ID. After receiving the signature ID the eService provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant Remote SCD Service
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB backend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB backend
e-Signature BB backend-->>e-Signature BB frontend: Page to display the available eSignature models
deactivate e-Signature BB backend
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt SCD Based Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects "Use SCD to Sign" and enters pseodonym
e-Signature BB frontend->>e-Signature BB backend: API call /sign/pseudonym
activate e-Signature BB backend
e-Signature BB backend->>Remote SCD Service: document hash, SCD Remote Id
activate Remote SCD Service
Remote SCD Service->>Remote SCD Service:
Note right of Remote SCD Service: User enters Security PIN
Remote SCD Service-->>e-Signature BB backend: Signature
deactivate Remote SCD Service
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: API call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
## 10.1 Example Cross-Building Block Workflows
Some common workflows that leverage the eSignature Building Block can be found here:
## 10.2 Key Decision Log
[A historical log of key decisions regarding this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/94535681/E-Signature+Objective+Design+Consideration+-+Brainstorm)
## 10.3 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/276594796/Future+consideration)
## 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/v3ciRXSd).
# E-Signature Building Block Specification
Version 1.1; December 2025
***First developed by:*** \
Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio, in cooperation with GIZ, ITU, and DIAL.
***
***Authors to this version:***\
David Higgins and Mikael Linden
***Contributors:*** Charity Chirowamhangu, Antony Muriithi, Daniel Abadie, Norbert Nahayo, Rounak Nayak, Eric Ramirez, and Mary Metias
***Reviewers:***\
Yuliia Kravchenko and Smita Selot
***Editor:***\
Ali González-García
e-Signature cover
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
0.8
Sasikumar Ganesan, Jurgen Niinre, Dr. P. S. Ramkumar, Kassy Kadio
Updates to Version History and Release Notes implementation of Semantic Versioning.
Minor Updates to Description eSignature Lifecycle changed to e-Signature Deployment Models
Terminology aligned to GovSpecs 2.0 format and common ID terminology
Minor Typos/Gramatical Fixes Requirements Aligned to GovSpecs 2.0 (Required/Recommended)
# Release Notes
## **Version 1**
***
## **v1.1.0**
*Released: December 2025*
*Authors:* David Higgins and Mikael Linden
***
### 1. Overview
This release of the e-Signature Building Block was developed between September and December, 2025 by the **Cross-Functional ID Infrastructure Working Group**, a super-group of all the key Identity and Trust-related Building Blocks in GovStack (e-signature, identity, Wallet, Consent).
Release 1.1 of e-Signature is the result of a review of all 4 specifications to ensure their are aligned and consistent to a single Identity Universe. As a result, a shared ID Terminology reference document was created and linked.
### 2. Changes
#### **Section 1 Version History**
* Update Authors
* Add Release Notes
* Move to Semantic Versioning
#### **Section 2 Description**
* Change "eSignature Lifecycle" to "eSignature Deployment Models"
* Gramatical/ Minor Typo corrections
#### **Section 3 Terminology**
* Alignment to ID Common Terminology
* Move to GovSpecs 2.0 format of Headings and descriptors
* Addition of the term [Timestamp](/3-terminology#timestamp)
#### **Section 4 Key Digital Functionalities**
* Change references where incorrect to Identity Building Block
* Gramatical/Minor Typo corrections
***
## **v1.0.0 (was 23Q4)**
First published version
# 2 Description
This section provides context for this Building Block.
eSignature Building Block provides the necessary functionalities to bring handwritten signatures to the digital world. Handwritten signatures have served as a way to agree/witness a given document, yet, in today's digital world most documents are in digital form. The digital form varies between structured (XML, JSON) and unstructured documents (PDF, Word, Image, CSV, Spreadsheet). eSignatures can be added to digital documents similar to handwritten signatures achieving the same functionality.
Additionally, eSignatures improve user experience in managing the signing process as the same can be embedded directly in e-Services, leaving out the need to print out forms, sign on paper, scan, and upload/send.
eSignature provides a considerable advantage over handwritten signatures because of the availability for verification at any point in time. This allows for remote validation of signatures, content (content being the same as that during signing), identity, and time. This assurance allows us to trust a signed document remotely and can be used for legally binding agreements. Sample use cases include:
* Submitting applications to Government agencies (e.g. Child Care, Residence Registration, Marriage, etc.)
* Purchase and use banking services (i.e. making transfers, adding transfer limits, applying for loans)
* Purchasing telecom services (i.e. purchase SIM/eSIM, change contract, add a TV subscription)
* Purchase utility services (i.e. new contract for electricity, gas)
* Purchase insurance contract
With eSignature there is no need to print documents on paper anymore, saving a lot of paper and promoting a green lifestyle. This can also save money and can be calculated with an[ online calculator ](https://blog.dokobit.com/news/e-signature-calculator-check-out-how-much-you-could-save/)designed for the eSignature practice.
## 2.1 Current scope
* Ability to support eSignature for everyone.
* Ability to support eSignature through a specialized user device/card.
* The ability for third-party services (including other Building Blocks) to interact, sign, and verify the eSignatures in a standardized model.
### 2.1.1 Actors
* Users: people or applications (delegated by a user) who use the eSignature Building Block to give eSignatures.
* Services: third-party services that require a user eSignature to provide the service.
* Auditor: individual or organization that reviews the platform for any misuse (intentional or unintentional)
* Administrator: individual or team that configures the eSignature Building Block and is responsible for ensuring the functioning of the Building Block.
* Certification Authority: a certification authority that can issue a certificate as X509.
* Timestamp Authority: a trusted third party who can provide certified time.
## 2.2 eSignature deployment models
There are two deployment models available for the eSignature Building Block. Both mechanisms have their own unique advantages, therefore it is recommended to follow both for an inclusive approach.
### 2.2.1 One-Time Signature Approach
One-time signatures are one of the easiest ways to get large-scale adoption of eSignatures. This approach does not require any device to be owned by the end user. This approach relies on the work done by the ID Building Block to authenticate an end user.
One Time Signature
* User authenticates against the ID Building Block
* The user is redirected to the eSignatures Building Block
* A new key pair is created in the HSM (Hardware Security Module)
* An X509 Certificate is issued with the details from the ID Building Block (Name, Age, Gender, Location)
* The new key is used to timestamp and sign the document
* The X509 certificate is set to expire 1 minute from the time of creation
* The signed document is sent
* The private key is deleted from the HSM
### 2.2.2 SCD-based approach
The SCD (Signature Creation Device) is a personal device of the user. It could be a Mobile Phone, SIM card, Smart Card, Secure SD Card, USB Storage device, NFC Card, etc. The SCD device can be used to store the keys for long-term usage. This allows the user to interact with the ID Building Block once and create a key on the SCD. This key then can be used for signing any document without interacting with the ID Building block.
SCD Onboard
The binding of the private key with the user is called On-boarding. In this process, a user is authenticated and his key is created on the SCD.
* User authenticates against the ID Building Block
* The user is redirected to the eSignature page where his SCD device is detected
* The user is asked to select a valid SCD device and enter its security PIN/Biometric/One Time Password
* The eSignature Building Block interacts with the SCD (protocols are left open for implementation) to create a Key Pair
* A CSR (Certificate Signing Request) is created
* This request is sent to the eSignature Building Block
* The Building Block verified the ID Building Block token and the data in the CSR
* If they match then the CSR is converted to an X509 certificate and the same is issued back to the device
SCD Based Signature
The key created on the SCD device can be used by the user to digitally sign any of the documents.
* The third-party who needs to sign the document will be redirected to the eSignature Building Block
* The eSignature Building Block will ask for the pseudonym (eSignature handle) from the user
* The user provides the pseudonym to the eSignature Building Block
* The eSignature Building Block sends a notification to the SCD (Internal Protocol)
* The user is shown his choice to sign or not to sign
* Once the user signs the SCD will send the signature to the third-party
* The Digital Signature will then be attached to the given document in one of the supported formats as described by the eSignature Building Block
## 2.3 Current Scope
### 2.3.1 This Building Block must enable the user to
* View and provide consent to the document that is about to be signed
* Register the user's Signature Creation Device (SCD)
* Confirm the signature with a PIN code on the user's SCD
* View user's SCD-s and certificates
* Digitally sign the documents (PDF, Word, Excel, JSON, XML, Image)
* Use a personal device to store the keys safely
* Ability to sign the document where the user has no device
* Ability to sign a document without the involvement of ID Building Block
* Ability to sign a document using only the ID issued by the ID Building Block
User
* Ability to view the list of signings performed
### 2.3.2 This Building Block must enable other eServices to
* Invoke eSignatures to obtain a digital signature
* Sign the digital document in the desired eSignature format
* Allow a safe async way to obtain signatures
* A simple-to-use library to validate the eSignature
### 2.3.3 This Building Block must enable an auditor to
* Retrieve and review specific audit data
* Validate and get signatures on any audit data
* Audit cryptographic functioning and compliance for auditing and key security
### 2.3.4 This Building Block must enable the administrator to
* Configure the system without intervening with the signature process
* Administer without modification or tampering with the data or key security
## 2.4 eSignature library
eSignature Building Block will provide a helper library for the Services. The helper library could be used to integrate eSignatures faster.
* Get digital document digest to be sent to eSignature Building Block. Obtaining just the hash reduces the storage overhead and also avoids the privacy concern of sending the original document.
* Embedding received eSignature back into the document or attaching it in case of detached signatures.
* Validate digitally signed documents and the validity of the certificate.
## 2.5 eSignature formats
Supports the following signature formats:
* [XAdES - XML signatures](https://www.w3.org/TR/XAdES/)
* [PAdES - PDF signatures](https://www.iso.org/standard/67937.html)
* [CAdES - CMS Signatures](https://www.rfc-editor.org/rfc/rfc5126)
* [ASIC - Interoperable signatures](https://www.etsi.org/deliver/etsi_en/319100_319199/31916201/01.01.01_60/en_31916201v010101p.pdf)
* [JWS (RFC 7515)](https://www.rfc-editor.org/rfc/rfc7515)
## 2.6 Authentication and Security
In order for eSignatures to be secure and adhere to privacy regulations the eSignature Building Block uses the following levels of authentication,
* Authentication via ID Building Block: the service that uses eSignature will have to authenticate the user against the ID Building Block.
* Unique pseudonym: the service is redirected to a webpage on the eSignature portal where the user can enter a unique pseudonym known only to the user to start the signing process (without a pin, the signing will not be complete).
* Asking for a PIN code on the user's device: eSignature Building Block will send a request to the user's device so that the user can confirm the signing request with a PIN.
* The signature will be returned using an internal API protected by the Information Mediation Building Block.
## 2.7 Audit Trail and Compliance
eSignature Building Block must log all signing transactions to be compliant with current regulations. The minimum details to be logged are:
* User's identity without revealing personally identifiable information.
* Document digest.
* Timestamp of the signing.
# 3 Terminology
Terminology used within this specification.
We recognise there are common terms across all ID related Building Blocks (Identity, E-Signature, Consent, Wallet). We define these [here](https://identity.govstack.global/3-terminology/id-related-bb-common-terminology).
In addition the following terms are specific to the e-Signature Building Block.
### e-Signature
*(also known as eSignature, electronic signature, digital signature)*
A data unit which is used by a Signatory to indicate his or her link to a Document
### Certificate
Data that links a public key to a natural person and confirms the name of that person
### Signatory/User
A natural person or an application delegated by the user who can create a digital signature
### eSignature creation device (SCD)
Configured software and/or hardware used to create an eSignature. Two types of eSignature creation devices are supported:
* Local - Private keys are stored locally on mobile devices.
* Remote - Private keys are stored on the remote secure storage.
### Signing application, Signature requestor, Third-Party
An application that has the Document that needs the Signatory's signature
### Document (to be signed)
Data that needs to be signed by the Signatory. It can be any data file in an arbitrary format. Document to be signed is usually handled by a third party and made available to Signatory after signing.
### Onboarding
The process of identifying Signatory, issuing a Certificate, and binding it to an eSignature Creation Device.\
User identification is performed using Govstack's [Identity Building Block](https://identity.govstack.global).
### Hardware Security Module (HSM)
Hardware Security Module - a device or software that can store private keys safely.
### Signature Creation Device (SCD)
Signature Creation Device - Can be local or remote based on where the keys are stored.
### X509
A certificate format as defined in [V3](https://www.rfc-editor.org/rfc/rfc5280)
### Timestamp
Compliant to [RFC3161](https://www.rfc-editor.org/rfc/rfc3161)
### Sign
The process of using [SCD](#signature-creation-device-scd) or One Time signature APIs to encrypt the hash of the document.
### Certificate Signing Request (CSR)
Certificate Signing Request as per [RFC 2986](https://datatracker.ietf.org/doc/html/rfc2986)
### One time Signature
A private key is created upon authentication of the user and expires right after the signature. Should not be confused with OTS or related signature models.
### Revocation
All revocation of certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html). Follows the respective standards RFC 8954.
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
To facilitate the eSignature service as described in section 2, the Building Block must have specific Key Digital Functionalities.
## 4.1 Hardware Security Module
The Hardware Security Module (HSM) is an integral part of the eSignature Building Block. The HSM ensures the protection of a key with utmost safety. Without an HSM the key can potentially fall into the wrong hands and could result in huge mistrust. All keys used in our one-time signatures are created, used, and destroyed within the HSM. The HSM should be configured with FIPS 140-2 Level 3. This device will follow PKCS11 or JCE standards.
## 4.2 Signature Creation/Seal Device
The eSignature creation device (SCD) is the component where the user's private key would be stored. The SCD could be a Smart card, Mobile App, Sim card App, or equivalent. The SCD interacts with the eSignature Building Block using its own internal protocol. Every eSignature Building Block will support one or many such SCDs. Most of the SCD would be protected with a secure PIN/Biometrics.
The SCD should be qualified with at least one of the following FIPS 140-2/3 Level 3 or Annex II of [Regulation (EU) No 910/2014 (eIDAS)](https://en.wikipedia.org/wiki/EIDAS) or equivalent common criteria certification.
## 4.3 Timestamp
The time of a sign is an important part of the signature. Without a proper time of the signature, we can never trust the signature, as one can not find if the signature happened before its expiry or after expiry. Most often this functionality is provided by the timestamping server hosted by the CA. This service follows [RFC 3161](https://datatracker.ietf.org/doc/html/rfc3161)
## 4.4 One-Time Signing Service
This is one of the most important functionality of eSignature. This service is responsible for providing the One Time Signature API and interacts with the Hardware Security Module (HSM). This service validates the user against the Identity Building Block. A valid user is allowed to create a key in HSM and sign it. Every key created here will also need an X509 certificate. The certificate management module will publish this created X509 certificate.
Keys created during One Time Signature should be deleted after the signature process. Logs SHOULD be kept in a database of the details of the deletion. Logs MUST include timestamps and identify the user and affiliation that performed the transaction.
## 4.5 Signature Creation Device On-Boarding
eSignature creation device (SCD) On-Boarding is the module responsible for binding the SCD and user. The module interacts with the Identity Building Block and will validate the user's presence before issuing the Certificate. This module is responsible for talking to the SCD for all types of key management and administrative needs. This module is hosted on a server and would ensure the keeping of clear audit records and Know Your Customer/Client (KYC) records.
## 4.6 Signature Creation Device Signing
The SCD Signing is one of the vital functions of the eSignature Building Block. When a user holds its key in an SCD then this module is responsible for interacting with the SCD to sign any required document. This module works in asynchronous mode. A signature is requested on demand using the API. However, the module interacts with the SCD asynchronously. The module is responsible for connecting to SCD for all signing purposes.
## 4.7 Certificate Management
All certificates that are created within the SCD will be hosted in this module. The module lets everyone have their X509 public certificate hosted for any verification. The module should have an administrative ability to allow people to revoke the keys on demand. The module has to maintain the OCSP & CRL-based revocations. Key revocation is not available in Onetime Signatures as the certificate is short-lived.
## 4.8 Notification
This module is responsible for notifying the SCD device when a signature is needed. This helps the SCD to alert the user. The user can look through the notification and accept to sign the document. The module is also responsible for notification of a signature to the user's mobile phone/email/SCD. The notification to the user can be used as an audit record by the user. This interface abstracts the messaging with an omnichannel interface. The notification Building Block can be used to send notifications to the end user/device.
## 4.9 Public Observation Interface
This interface handles the necessary health, metrics, traceability and legal needs for the given Building Block. While there are no certain standards to this, it is recommended to follow the [OpenTelemetry](https://opentelemetry.io/) design to address some of the challenges. Issuance of signature certificates is usually backed by several legal regulations. The requirements can range from KYC details available upon Judicial intervention, Revocation and Transparency of the revoked certificate as per OCSP/CRL (Similar to [RFC 6961](https://datatracker.ietf.org/doc/html/rfc6961)/[RFC 5280](https://www.rfc-editor.org/rfc/rfc5280)) and Dispute Resolution.
## 4.10 Signature Backend
Once the signature is completed the signature backend keeps the signature until the eService server makes a request. Once the eService has received the Signature Token (SignatureId), It can request the eSignature BB to send the final signature. Once the Signature Token is validated the BB sends the signature. This happens over a backend-protected channel.
## 4.11 eService Callback
This is the callback service available in eService. Once the signature is complete the user will be redirected to the eService. This module is responsible for understanding the redirect request and the HTTP parameters that are passed during this redirection.
## 4.12 Signature Validation
This module is responsible for validating a digital signature. This is provided as a library. A format-specific validation library should be provided. The majority of the format adopted in this specification provides a clear explanation of how to validate the signature. But in a few specified formats like ASC, it may be necessary for the signature service to explicitly state the validation mechanism. It is also expected that the service provider will provide a library, application (optional), and online service(optional) to validate the signature.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document.
## 5.1 Hardware Security Module Compliance (REQUIRED)
HSM must be compliant to a minimum of FIPS 140-2 Level 3. This guarantees the protection of private keys. HSM/Key Management application shall not print any information about the end-use details. Keys should be created only within the HSM. This may apply to all other Building Blocks when dealing with cryptographic keys.
## 5.2 Audit (REQUIRED)
All audit logs shall be integrity-protected against tampering. The eSignature Building Block shall follow the data policy and audit logging requirements as laid out in the GovStack architecture.
## 5.3 Privacy (REQUIRED)
Signing using a single key can compromise the user's privacy in the long run. For example, a single key used to sign the consent of health form and agreement of the medical insurance could reveal that the consent and the agreement are from the same person. Generally available signed documents could be used to perform 360-degree profiling. This violates the Generic Architectural Privacy recommendation. Privacy-preserving techniques can be used in signature schemes, document storage, or reducing the key's lifespan to protect the user's privacy.
## 5.4 Logging
* The system shall provide traceability across services using trace ID or similar design patterns. (REQUIRED)
* The system shall provide logs to help debug the problems. (REQUIRED)
* The system shall not print sensitive information. (REQUIRED)
* Private Key
* User details
* Authentication Token
* Payment Token
* Signature of the document
* Full Certificate (Thumbprint is allowed to be printed)
* User PIN
* OTP
* In case a user/mobile app is involved, then logging shall provide traceability from the app to the server. (REQUIRED)
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
The eSignature Building Block has several functional layers within it. Some functional layers follow the existing set of protocols and custom protocols, While the other functional requirements are defined within this specification. In this section, we will provide a clear indication to state what blocks follow what kind of protocols.
## 6.1 Hardware Security Module
* In the case of the One-Time Signature, a Hardware Security Module (HSM) must be used to create cryptographic keys. (REQUIRED)
* It must be used to sign a certificate. (REQUIRED)
* Keys shall not be exported. (REQUIRED)
* MUST be protected well with best security practices. (REQUIRED)
## 6.2 Signature Creation/Seal Device
* Signature Creation Device (SCD) should have secure storage to protect private keys. (REQUIRED)
* SCD may have proprietary APIs with the eSignature Building Block. (REQUIRED)
* SCD is assumed to be with the user. (REQUIRED)
* A user's PIN is a must for the SCD. (REQUIRED)
* Keys shall not be exportable. (REQUIRED)
## 6.3 Timestamp
* For a valid signature, a timestamp server is a must. (REQUIRED)
* The timestamp server shall follow [RFC3161](https://www.ietf.org/rfc/rfc3161.txt). (REQUIRED)
## 6.4 Certifying Authority
* eSignature Building Block may be a certifying authority. (REQUIRED)
* If not, the Building Block shall have access to a certifying authority and be able to issue certificates or be a subordinate certification authority. (REQUIRED)
## 6.5 eSignature Service
* Service shall support the onboarding of the Signature Creation Device (SCD). (REQUIRED)
* Service shall support both the key functionalities of signing using SCD and One-Time Signature. (REQUIRED)
* The user shall be authenticated through the ID Building Block for the One-Time Signature. (REQUIRED)
* The user shall be allowed to perform a signature through a pseudonym without user login. (REQUIRED)
* Optionally can support payments through a payment gateway. (OPTIONAL)
* Shall support all the listed signature types. (REQUIRED)
* Shall support redirection and callback as per the specification. (REQUIRED)
## 6.6 Audit
* All user activities should be available for audit. (REQUIRED)
* May have the feature to tamper-proof the audit records. (REQUIRED)
* Auditors shall have the ability to get audit-proof of a transaction. (REQUIRED)
## 6.7 Certificate Management
* Shall provide the ability to list and revoke a certificate. (REQUIRED)
* The user shall have the ability to revoke their keys (API-based or through customer care). (REQUIRED)
* Certificates shall have any of the following statuses (REQUIRED):
* Active – The certificate is active and can be used for signing.
* Expired – certificates are expired and should be renewed.
* Suspended – certificate is suspended. The reason for suspension shall be provided together with status information.
* Revoked – certificate is revoked. The reason for revoking shall be provided together with status information.
* Users shall be able to view their certificates and corresponding statuses. (REQUIRED)
## 6.8 Notification
* Shall provide the ability to notify the user over email, SMS, app notification, or any other equivalent. (REQUIRED)
* The user shall be notified of failed and successful transactions. (REQUIRED)
## 6.9 Messaging Interface
* The Messaging interface should send relevant information to the logging sub-block to maintain the history of all messages sent from this Building Block, which are useful for audit purposes. (RECOMMENDED)
* The messaging interface should provide the necessary protocol, data format, and information and interface to interact with the Messaging Building Block for sending notifications to a specific target Signature Creation Device or user through a variety of channels (SMS/email/etc.) (RECOMMENDED)
**Note:** The keywords "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
## 6.11 Metrics
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Data Elements
### 7.1.1 eSignature operation
| Name | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| SignatureId | String | Unique Signature Token for signature operations. This can be a random String as well. |
| SignatureType | Enum | Can be ONETIME or SCD |
| SignatureFormat | Enum | Signature format that should be applied. Can be XAdES, CAdES, ASIC, JWS, PAdES |
| Hash | String | Hash to be signed in hex characters or base64 |
| HashType | Enum | Hash type - SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B |
| DisplayData | String | Text string to be shown on user’s device (SCD). Limited to 256 characters. |
| Certificate | String | X509 Certificate in PEM format |
| RequestTimestamp | Timestamp | Timestamp of the request |
| Signature | Signature | Signature in base64 format |
| SignatureTimestamp | String | rfc3161 asn.1 in base64 |
| ResponseTimestmap | Timestamp | Timestamp of the response |
| Status | Enum | Request status enum. Can be OK, ERROR |
| StatusDesc | String | Description of status |
| CallbackURL | URL | URL to call back with results |
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
### 7.1.2 eSignature operation header
| Name | Type | Description |
| ------------ | ------ | -------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | Jwt Token from Payments Building Block |
### 7.1.3 User's Device Onboarding
| Name | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AuthToken | String | JWT Token from ID Building Block |
| PaymentToken | String | JWT Token from Payments Building Block |
| CSR | String | Certificate signing request PKCS#10 in PEM format |
| SCDType | Enum |
The SCD type that is used by user. Can be of REMOTE\_SCD\_APP\_APPLE, REMOTE\_SCD\_APP\_ANDROID, REMOTE\_SCD\_APP\_SE\_APPLE, REMOTE\_SCD\_APP\_SE\_ANDROID, REMOTE\_SCD\_SIM, REMOTE\_SCD\_ESIM,
REMOTE\_SCD\_SMARTID
|
| SCDKeyId | Number | Key id for case the SCD has multiple certificates |
| SCDRemoteId | String |
Remote identifier for the SCD communication, for REMOTE\_SCD\_APP\* devices it is push ID, for REMOTE\_SCD\_ESIM/ REMOTE\_SCD\_SIM it is msisdn
For
REMOTE\_SCD\_SMARTID it is citizen id
|
| Pseudonym | String | Unique pseudonym for the user that is bound to the specific SCD/Key id combo. We can call this as Key Handle |
| CertReqTimestamp | Timestamp | Timestamp for the certificate request |
| CertId | String | Unique identifier for the certificate, SCD, Key id combo |
| Certificate | String | X509 Certificate in PEM format in ACTIVE status |
| CertRespTimestamp | Timestamp | Timestamp for the Certificate response |
| Status | Enum | Request status. Can be of of OK, ERROR |
| StatusDesc | String | Description of status |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
A Set of microservices is defined to receive requests from other GovStack-compatible Building Blocks and third-party Services with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks or third-party services. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
eSignature Building Block must expose its microservices through RESTful API interfaces as defined by [OpenAPI v3+ standards](https://swagger.io/specification/). A summary of the APIS exposed by this Building Block is summarized in the table below.
### 8.1 eSignature with one-time certificate
{% openapi src="" path="/{version}/sign/onetime" method="post" %}
{% endopenapi %}
### 8.2 eSignature with user's eSignature creation device (SCD)
#### 8.2.1 Certificate creation
{% openapi src="" path="/{version}/cert/create" method="post" %}
{% endopenapi %}
#### 8.2.2 List certificates
{% openapi src="" path="/{version}/cert/list" method="get" %}
{% endopenapi %}
#### 8.2.3 Update certificate
{% openapi src="" path="/{version}/cert/{certificateId}" method="patch" %}
{% endopenapi %}
The update API can be used to revoke the certificate. All revoked certificates will be available over [OCSP](https://www.rfc-editor.org/rfc/rfc8954.html).
#### 8.2.4 eSignature with user's device
{% openapi src="" path="/{version}/sign/pseudonym" method="post" %}
{% endopenapi %}
#### 8.2.5 Webservice to enter user pseudonym
{% openapi src="" path="/{version}/sign/interactivePseudonym" method="get" %}
{% endopenapi %}
#### 8.2.6 User pseudonym API
{% openapi src="" path="/{version}/token/pseodonym/{pseudonym}" method="get" %}
{% endopenapi %}
#### 8.2.7 Get signature response
{% openapi src="" path="/{version}/sign/response/{signatureId}" method="get" %}
{% endopenapi %}
#### 8.2.8 Callback service API
{% openapi src="" path="/{version}/esignature/callback" method="get" %}
{% endopenapi %}
### 8.3 Audit log
{% openapi src="" path="/{version}/audit/log" method="get" %}
{% endopenapi %}
# 9 Internal Workflows
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
### 9.1 Workflow for one-time signing
This internal workflow is used by the eSignature Building Block to provide one-time signature. In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Frontend constitutes the functionality running in the user's internet browser and backend refers to the API running on a server.
Workflow is kicked off by a third party using the eSignature client library to get a digest of document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. If required by the Building Block configuration, it will also check if the Payment token supplied by the request is valid. In the eSignature Building Block front-end, the user selects the option to use National ID to do a one-time signature. Then the user is redirected to the Identity Building Block to authenticate and user data is returned back to the eSignature Building Block back-end after completion of all standard interaction API calls. Then a Host Security Module (HSM) hardware is used to generate a temporary keypair. From that keypair, the public part is exported as a Certificate Signing Request (CSR). CSR is submitted to a Certificate Authority (CA) instance that will generate and publish a short-lived (1-minute) certificate based on the supplied CA.
After the certificate has been created the private key in the Hardware Security Module (HSM) is used to sign a document digest. After the document digest is signed, a timestamp is requested on the signature from the timestamping service. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. The signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the e-Service provider using the callback URL and signature ID. After receiving the signature ID the e-Service provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant HSM
participant ID BB
participant CA
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB frontend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt One time Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects National ID based model
e-Signature BB frontend->>ID BB: Browser redirects for user authentication
deactivate e-Signature BB frontend
activate ID BB
ID BB->>ID BB:
Note right of ID BB: User logins using National ID
ID BB->>e-Signature BB frontend: Browser redirects to callback URL with authorization code
deactivate ID BB
activate e-Signature BB frontend
e-Signature BB frontend->>e-Signature BB backend: authorization code & document hash
activate e-Signature BB backend
e-Signature BB backend->>ID BB: Multiple API exchanges
activate ID BB
ID BB-->>e-Signature BB backend: User data
deactivate ID BB
e-Signature BB backend->>HSM: Create key with user data
activate HSM
HSM-->>e-Signature BB backend: CSR
deactivate HSM
e-Signature BB backend->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB backend: Certificate
deactivate CA
e-Signature BB backend-->>HSM: Sign with key & delete
activate HSM
HSM-->>e-Signature BB backend: signature
deactivate HSM
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: api call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
### 9.2 Workflows for signing with the user's device
In case of signing in with the user's device, there are multiple workflows:
* Register the user's Signature Creation Device (SCD).
* Signing with the user's Signature Creation Device (SCD).
#### 9.2.1 Register user's Signature Creation Device (SCD)
Registering starts with the user authenticating against the ID Building Block and getting the authentication token. After the user is authenticated, a Remote SCD service is called to onboard the user. There is a request sent to the user's device to create keys. After keys are generated the public part of the keypair is sent to the eSignature Building Block as a Certificate Signing Request (CSR). CSR is submitted to a certificate authority (CA) instance that will generate and publish a certificate based on the supplied CA.
{% @mermaid/diagram content="sequenceDiagram
actor User
User->>ID BB: Authenticate with e-signature scope
activate ID BB
ID BB-->>User: Access token
User->>e-Signature BB: Provide authentication token
activate e-Signature BB
e-Signature BB->>ID BB: Invoke introspect API with Access token
ID BB-->>e-Signature BB: user details, user PSUT
deactivate ID BB
e-Signature BB->>Remote SCD Service: onboard user
activate Remote SCD Service
Remote SCD Service->>User: Accept key creation, choose PIN
User-->>Remote SCD Service: CSR
Note right of User: User accepts key creation and choose PIN with a mobile device
Remote SCD Service-->>e-Signature BB: CSR
deactivate Remote SCD Service
e-Signature BB->>CA: Create certificate with CSR & publish
activate CA
CA-->>e-Signature BB: Certificate
deactivate CA
e-Signature BB-->>User: SCD Onboarded
deactivate e-Signature BB
" %}
#### 9.2.2 Use the user's Signature Creation Device (SCD) for signing
This internal workflow is for signing with the user's Signature Creation Device (SCD). In order to make the sequence diagram easier to follow the eSignature Building Block is divided into front-end and back-end parts. Front-end constitutes the functionality running in the user's internet browser and back-end refers to the API running on a server.
First, eService fetches the client-side library from the eSignature Building Block front-end. The client library is used to create a digest of the document to be signed. Using the digest (hash) the redirection request is made towards the eSignature Building Block front-end. In the eSignature Building Block front-end, the user selects the option to use the SCD model. The pseudonym entry page is shown and the user enters the pseudonym, which is sent to the e-Signature Building Block back-end to receive the generated pseudonym token. After receiving a pseudonym token, eSignature Building Block back-end can be invoked to create the signature. eSignature Building Block back-end will then invoke Remote SCD Service to create the signature. Remote SCD service will send a notification to the user's SCD with a notification and request to put PIN code. After the user enters the PIN code, a signature is generated and sent back to the Remote SCD Service. Remote SCD Service will then send the signature back to the eSignature Building Block back-end.
After the Signature is received, eSignature Building Block back-end will send a request to the Timestamping Authority for a timestamp on the signature to be created. After the timestamp is generated and received on a signature, the results are saved into a database, and a signature ID is generated to reference the signature data. Signature ID is then returned to the eSignature front-end, and the user's flow is redirected back to the eService provider using the callback URL and signature ID. After receiving the signature ID the eService provider can then receive the signature from the eSignature Building Block back-end. As an option, the eSignature Building Block back-end can verify the requests coming from the correct IP. After finally receiving the signature, eService can merge it with the original document to get a signed version of it using the client-side library received from the eSignature Building Block front-end.
{% @mermaid/diagram content="sequenceDiagram
participant e-Service
participant e-Signature BB frontend
participant e-Signature BB backend
participant Remote SCD Service
participant TSA
activate e-Service
Note right of e-Service: Get document hash with client side library
e-Service->>e-Signature BB backend: Browser redirects to /sign/interactive passing document hash
deactivate e-Service
activate e-Signature BB backend
e-Signature BB backend-->>e-Signature BB frontend: Page to display the available eSignature models
deactivate e-Signature BB backend
activate e-Signature BB frontend
rect rgb(230, 245, 255)
alt SCD Based Signature Model
e-Signature BB frontend->>e-Signature BB frontend:
Note right of e-Signature BB frontend: User selects "Use SCD to Sign" and enters pseodonym
e-Signature BB frontend->>e-Signature BB backend: API call /sign/pseudonym
activate e-Signature BB backend
e-Signature BB backend->>Remote SCD Service: document hash, SCD Remote Id
activate Remote SCD Service
Remote SCD Service->>Remote SCD Service:
Note right of Remote SCD Service: User enters Security PIN
Remote SCD Service-->>e-Signature BB backend: Signature
deactivate Remote SCD Service
end
end
e-Signature BB backend->>TSA: Get timestamp for signature
activate TSA
TSA-->>e-Signature BB backend: Timestamp rfc3161
deactivate TSA
e-Signature BB backend-->>e-Signature BB frontend: Signature Id
deactivate e-Signature BB backend
e-Signature BB frontend->>e-Service: Browser redirects to callback URL with Signature Id
deactivate e-Signature BB frontend
activate e-Service
e-Service->>e-Signature BB backend: API call /sign/response
activate e-Signature BB backend
e-Signature BB backend-->>e-Service: signature\×tamp
deactivate e-Signature BB backend
Note right of e-Service: Merge signature using client side library
deactivate e-Service" %}
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
## 10.1 Example Cross-Building Block Workflows
Some common workflows that leverage the eSignature Building Block can be found here:
## 10.2 Key Decision Log
[A historical log of key decisions regarding this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/94535681/E-Signature+Objective+Design+Consideration+-+Brainstorm)
## 10.3 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block.](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/276594796/Future+consideration)
## 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/v3ciRXSd).
