Design Principles

When conceptualizing and designing the interface for social protection delivery, the implementing agency should consider the design principles outlined below:

Reference: OpenID Connect and G2P Connect

Transport Layer

The API specification is flexible to support JSON entities via HTTPS, pub/sub-event-based communications, and file exchanges. API specifications default to JSON entities over HTTPS. Countries can use pub/sub-event-based messaging or HTTPS, SFTP, or other file exchange protocols.

Message Signing

Using HTTPS APIs to connect social protection services to other IT systems like CRVS, foundational ID systems, financial systems, and registries requires authentication. The sender and receiver must digitally sign and verify all requests and responses for safe communication. Preventing message tampering during transit.

API requirements require the sender to sign the message and generate an HMAC signature value. The API request's custom header (x-HMAC) will contain this signature. x-HMAC header format:

x-HMAC: HMAC-SHA256 Credential=key, SignedHeaders=host;date;content-type, Signature=value.

Here's what each part of the x-HMAC header means:

Credential: The HMAC signature's shared secret key is Credential.
SignedHeaders: A comma-separated set of HMAC signature headers (host, date, content-type).
Signature: Sender-generated HMAC signature.

Message signing protects trusted API messages by following this API definition. Encrypted payloads also safeguard message privacy.

Message Structure

Field Name	Description
Signature	Signature of {header}+{message} body verified using sender's signing public key, element holding signature to prove non-reliability of payload (header & message) between sender & receiver.
Header	Request/ response's common header to track messages between sender & receiver for traceability and to track message delivery at the transport layer Message routing: Header information can route messages. Header information can include the recipient's name or the message's service. Key lookup: Header information can be used to find the relevant message encryption or decryption key. The header information is used to identify the recipient or service and look up the key in a key store. Encryption: The header might encrypt the message before sending it to safeguard the communication. Attributes of header information: Version: The version format should use semantic versioning, which means dividing each version identifier into three parts: MAJOR, MINOR, and PATCH. These parts are then combined using the format 'MAJOR.MINOR.PATCH'. Message ID: Unique message id to communicate between sender and receiver systems to deliver the message over any transport layer i.e https, pub/sub, sftp, etc. Message Timestamp: Time of message generation in RFC3339 format. Sender ID: The ID of the sender system registered with the receiving system. Receiver ID: The targeted system to which the request to send Action: Action to be performed. Total Count: Total count of requests present in the message. Is Encrypted: If is_encrypted is true then the receiving system will expect the message part of the request in encrypted format. Also, the receiving system will expect the encryption_algorithm parameter. Encryption Algorithms: The encryption algorithm is used to encrypt the message part of the request. Async: The "async" header specifies that the API anticipates an asynchronous response. If this header is set to "true," the API will handle the request asynchronously. Otherwise, if set to "false" or not included, the sender will expect a response within the same request, which is the default behaviour. The callback endpoint Encryption algorithm is used to encrypt the message part of the request.
Message	Message to hold transaction request/response details.

Field Name

Description

Signature

Signature of {header}+{message} body verified using sender's signing public key, element holding signature to prove non-reliability of payload (header & message) between sender & receiver.

Header

Request/ response's common header to track messages between sender & receiver for traceability and to track message delivery at the transport layer

Message routing: Header information can route messages. Header information can include the recipient's name or the message's service.

Key lookup: Header information can be used to find the relevant message encryption or decryption key. The header information is used to identify the recipient or service and look up the key in a key store.

Encryption: The header might encrypt the message before sending it to safeguard the communication.

Attributes of header information:

Version: The version format should use semantic versioning, which means dividing each version identifier into three parts: MAJOR, MINOR, and PATCH. These parts are then combined using the format 'MAJOR.MINOR.PATCH'.

Message ID: Unique message id to communicate between sender and receiver systems to deliver the message over any transport layer i.e https, pub/sub, sftp, etc.

Message Timestamp: Time of message generation in RFC3339 format.

Sender ID: The ID of the sender system registered with the receiving system.

Receiver ID: The targeted system to which the request to send

Action: Action to be performed.

Total Count: Total count of requests present in the message.

Is Encrypted: If is_encrypted is true then the receiving system will expect the message part of the request in encrypted format. Also, the receiving system will expect the encryption_algorithm parameter.

Encryption Algorithms: The encryption algorithm is used to encrypt the message part of the request.

Async: The "async" header specifies that the API anticipates an asynchronous response. If this header is set to "true," the API will handle the request asynchronously. Otherwise, if set to "false" or not included, the sender will expect a response within the same request, which is the default behaviour.

The callback endpoint Encryption algorithm is used to encrypt the message part of the request.

Message

Message to hold transaction request/response details.

The following example explains a sample of message payload that includes signature, headers, and message attributes.

{
    "signature": "Signature:  namespace=\"dci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
    "headers": {
        "version": "1.0.0",
        "message_id": "123456789020211216223812",
        "message_ts": "2022-12-04T18:01:07+00:00",
        "sender_id": "10089",
        "receiver_id": "crvs",
        "action": "search",
        "total_count": 10,
        "is_encrypted": true,
        "encryption_algorithm": "DH-2048",
        "async": true,
        "callbackendpoint": https://{server_url}/on-search
    },
    message: {
     // Message attributes
    }
}

The gateway will only use the header information to route API messages through a centralized gateway infrastructure. The message payload will be encrypted with the receiver applications' cryptographic key.

Communication Protocol

APIs will support synchronous and asynchronous communication.
In asynchronous communication, the receiver server sends a callback API call (on-action) to the sender server in the same session as an immediate acknowledgement (ACK). NACK and ERR will be returned if the exchange ends and the message cannot be parsed.
Senders must implement /on_xxxx endpoints for all async /xxxx service endpoints to receive callbacks.

Asynchronous communication is preferred since it does not interfere with the receiving server's API request in the same session.

Identifiers

APIs will contain identifiers such as:

message_id or request_id: scope of message_id in the header is to track payload delivery between sender and receiver.
transaction_id: scope of transaction_id in message is to uniquely correlate business request(s).
reference_id: scope of the reference_id in the message domain entity is to correlate individual business requests.
correlation_id: In the case of async callbacks, the correlation_id in the response message will contain the message_id of the original request that comes from the sender.

Payload Encryption

To ensure the security and integrity of the payload, JWE tokens must be used, according to API specifications. The JSON web encryption RFC7516 standard is used for the payload encryption.

The JWE token will contain the following parts:

Encrypted Header: JWE Header- This is a Base64Url-encoded JSON object that contains the parameters describing the cryptographic operations applied to the JWE Protected Header and the JWE Encrypted Key. This section is made of alg, enc, and kid.
data: This part contains the encrypted data.
Encrypted key: The base64-url encoded encrypted key
Auth tag: This is a Base64Url-encoded value that provides evidence of the integrity and authenticity of the ciphertext, Initialization Vector, and Additional Authenticated Data
Initialization Vector (IV): This is a Base64Url-encoded random bit string to be used as the Initialization Vector (IV) when encrypting the plaintext to produce the ciphertext. The size of the IV depends on the encryption algorithm used.

Asynch/ Synch-Based Processing

It has been decided to provide both asynchronous and synchronous options to give the freedom to the developer and implementing team to decide which of the two suits the context best.

Govstack reference (Architecture and Nonfunctional Requirements)

API Specifications are available here.

Last updated 3 months ago