ReBIT

It summarizes the changes in the FAQ page as per the discussion with the AA ecosystem community.
You can send the suggestions/queries regarding FAQs by mailing us on aa-api@rebit.org.in

Feb 23, 2021

Summary

1. What are minimal set of claims to be included in JWS header section?

Change Description: Added a new question to define minimal set of claims for JWS header section.

Answer: To generate the signature (or perform the encryption), following claims must be included by the signing entity in the JWS header section. The receiving entity must use these fields to correctly identify the certificate for verifying the signature (or decrypt the data).

Claim Mandatory Description
alg Yes The algorithm that will be used for signing the JWS.
kid Yes An identifier of the public key for validating the signature
b64 Yes - only for detached JWS A boolean value which indicates that when value is false, the payload is not base64 encoded. This claim is required only for detached JWS as payload is not b64 encoded.

2. What is a Detached JWS Signature?

Change Description: Changed the example of the detached JWS as per newly added claims for JWS header section.

Answer: Detached JWS Signature is a variation of JWS that allows to sign content (body) of HTTP request or response without its modification. The HTTP header “x-jws signature” is added, which contains data allowing to check whether the message has been changed on the way from the sender to the recipient.

Algorithm for generating the Detached JWS is as follows:

Example of the Detached JWS string:

eyJiNjQiOmZhbHNlLCJraWQiOiIxNDIxMTc0ODUiLCJhbGciOiJSUzI1NiJ9..QG1fUKa8kQ9H-rxEekbE4ytlj39aMpRe1ZF7eod1vHpUxZwYKB_4_WAzsavCUHnP0wQd0z2jHUP0UzbYnDLEMUq9v_mlqj31wnKRPsc6GRDBl--HIp6h0y75t9ZYt0EWdC8aRQ22Gt8Xuk_JW-iK5p9M__P9SqZVJh90LZvxVbK99ETE7EVfaORaUAhz9PBTgdF79zd_hl3INHjd3D1u7qRS0U36XMam9LQ6Zxo_Rw7-09lmDp84nEa2x78U_t4nI0dpNK4_izoTqFgEdcCGgCRjye8sjE-pgCmfKd5dZuz6pse8DdfvCai2rHolhB6C7rhd0wNexqrPAllq1IRMwg

Note: For decoding the Detached JWS string: https://jwt.io/

Validation of HTTP message with Detached JWS is as follows:

Change Description:

Answer: It is a string of compact serialized JWS containing header, payload, and signature (in order) and joined with a dot (“.”):
Header: The Header describes the digital signature or message authentication code (MAC) applied to the Payload and optionally additional properties of the JWS.

{

"alg": "RS256",
"kid": "142117485"
"b64": false
}

Payload: The payload consists of Consent data in JSON format.
For Example:

{
"consentStart": "2019-05-28T11:38:20.380+0000",
"consentExpiry": "2020-05-28T11:38:20.381+0000",
"consentMode": "VIEW",
"fetchType": "ONETIME",
"consentTypes": [
	"PROFILE",
	"SUMMARY",
	"TRANSACTIONS"
	],
"fiTypes": [
	"DEPOSIT",
	"TERM-DEPOSIT"
	],
"DataConsumer": {
	"id": "AA-identifier",
	"type": "AA"
},
"DataProvider": {
	"id": "BARB0KIMXXX",
	"type": "FIP"
	},

"Customer": {
"id": "customer-identifier@aa-handle"
},
"Accounts": [
{
	"fiType": "DEPOSIT",
	"fipId": "BARB0KIMXXX",
	"accType": "SAVINGS",
	"linkRefNumber": "UBI485964579",
	"maskedAccNumber": "UBI85217881279"
	},
{
	"fiType": "DEPOSIT",
	"fipId": "BARB0KIMXXX",
	"accType": "SAVINGS",
	"linkRefNumber": "UBI4859645",
	"maskedAccNumber": "UBI852178812"
	}
],
"Purpose": {
	"code": "101",
	"refUri": "https://api.rebit.org.in/aa/purpose/101.xml",
	"text": "Wealth management service",
	"Category": {
	"type": "purposeCategoryType"
	}
},
"FIDataRange": {
	"from": "2019-05-28T11:38:20.383+0000",
	"to": "2020-05-28T11:38:20.381+0000"
	},

"DataLife": {
	"unit": "MONTH",
	"value": 4
	},

"Frequency": {
	"unit": "HOUR",
	"value": 4
	},
"DataFilter": [
	{
	"type": "TRANSACTIONAMOUNT",
	"operator": ">",
	"value": "20000"
	}
]
}

Signature: The signature is computed in the manner defined for the algorithm being used (and declared in the Header) from ASCII (BASE64URL (UTF8(JWS Protected Header)) || ‘.’ || BASE64URL (JWS Payload)).

QG1fUKa8kQ9H-rxEekbE4ytlj39aMpRe1ZF7eod1vHpUxZwYKB_4_WAzsavCUHnP0wQd0z2jHUP0UzbYnDLEMUq9v_mlqj31wnKRPsc6GRDBl--HIp6h0y75t9ZYt0EWdC8aRQ22Gt8Xuk_JW-iK5p9M__P9SqZVJh90LZvxVbK99ETE7EVfaORaUAhz9PBTgdF79zd_hl3INHjd3D1u7qRS0U36XMam9LQ6Zxo_Rw7-09lmDp84nEa2x78U_t4nI0dpNK4_izoTqFgEdcCGgCRjye8sjE-pgCmfKd5dZuz6pse8DdfvCai2rHolhB6C7rhd0wNexqrPAllq1IRMwg

Signed Consent Example:

signedConsent:  
	type: string   
	description:Signature of the ConsentDetail of the Consent Artefact. The signature is in the JWS Compact Serialization format, which is compact, URL-safe representation of a JWS. See ConsentDetail model for consent format.  
	example:
		eyJraWQiOiIxNDIxMTc0ODUiLCJhbGciOiJSUzI1NiJ9.ewogICJjb25zZW50U3RhcnQiOiAiMjAxOS0wNS0yOFQxMTozODoyMC4zODArMDAwMCIsCiAgImNvbnNlbnRFeHBpcnkiOiAiMjAyMC0wNS0yOFQxMTozODoyMC4zODErMDAwMCIsCiAgImNvbnNlbnRNb2RlIjogIlZJRVciLAogICJmZXRjaFR5cGUiOiAiT05FVElNRSIsCiAgImNvbnNlbnRUeXBlcyI6IFsKICAgICJQUk9GSUxFIiwKICAgICJTVU1NQVJZIiwKICAgICJUUkFOU0FDVElPTlMiCiAgICBdLAogICJmaVR5cGVzIjogWwogICAgIkRFUE9TSVQiLAogICAgIlRFUk0tREVQT1NJVCIKICAgIF0sCiAgIkRhdGFDb25zdW1lciI6IHsKICAgICJpZCI6ICJBQS1pZGVudGlmaWVyIiwKICAgICJ0eXBlIjogIkFBIgogIH0sCiAgIkRhdGFQcm92aWRlciI6IHsKICAgICJpZCI6ICJCQVJCMEtJTVhYWCIsCiAgICAidHlwZSI6ICJGSVAiCiAgICB9LAogIAogICJDdXN0b21lciI6IHsKICAiaWQiOiAiY3VzdG9tZXItaWRlbnRpZmllckBhYS1oYW5kbGUiCiAgfSwKICAiQWNjb3VudHMiOiBbCiAgewogICAgImZpVHlwZSI6ICJERVBPU0lUIiwKICAgICJmaXBJZCI6ICJCQVJCMEtJTVhYWCIsCiAgICAiYWNjVHlwZSI6ICJTQVZJTkdTIiwKICAgICJsaW5rUmVmTnVtYmVyIjogIlVCSTQ4NTk2NDU3OSIsCiAgICAibWFza2VkQWNjTnVtYmVyIjogIlVCSTg1MjE3ODgxMjc5IgogICAgfSwKICB7CiAgICAiZmlUeXBlIjogIkRFUE9TSVQiLAogICAgImZpcElkIjogIkJBUkIwS0lNWFhYIiwKICAgICJhY2NUeXBlIjogIlNBVklOR1MiLAogICAgImxpbmtSZWZOdW1iZXIiOiAiVUJJNDg1OTY0NSIsCiAgICAibWFza2VkQWNjTnVtYmVyIjogIlVCSTg1MjE3ODgxMiIKICAgIH0KICBdLAogICJQdXJwb3NlIjogewogICAgImNvZGUiOiAiMTAxIiwKICAgICJyZWZVcmkiOiAiaHR0cHM6Ly9hcGkucmViaXQub3JnLmluL2FhL3B1cnBvc2UvMTAxLnhtbCIsCiAgICAidGV4dCI6ICJXZWFsdGggbWFuYWdlbWVudCBzZXJ2aWNlIiwKICAgICJDYXRlZ29yeSI6IHsKICAgICJ0eXBlIjogInB1cnBvc2VDYXRlZ29yeVR5cGUiCiAgICB9CiAgfSwKICAiRklEYXRhUmFuZ2UiOiB7CiAgICAiZnJvbSI6ICIyMDE5LTA1LTI4VDExOjM4OjIwLjM4MyswMDAwIiwKICAgICJ0byI6ICIyMDIwLTA1LTI4VDExOjM4OjIwLjM4MSswMDAwIgogICAgfSwKICAKICAiRGF0YUxpZmUiOiB7CiAgICAidW5pdCI6ICJNT05USCIsCiAgICAidmFsdWUiOiA0CiAgICB9LAogIAogICJGcmVxdWVuY3kiOiB7CiAgICAidW5pdCI6ICJIT1VSIiwKICAgICJ2YWx1ZSI6IDQKICAgIH0sCiAgIkRhdGFGaWx0ZXIiOiBbCiAgICB7CiAgICAidHlwZSI6ICJUUkFOU0FDVElPTkFNT1VOVCIsCiAgICAib3BlcmF0b3IiOiAiPiIsCiAgICAidmFsdWUiOiAiMjAwMDAiCiAgICB9CiAgXQogIH0.RDrwMlwjU9AeASBJdpAm_-Ss2-3Bd3rIC66RE_HMuSWf1gUIX4QYsbCp_2csGmR_PkbCF4K2nNF4WOkq_F5j-CMklMevqSx2ySs9V26aFoeq9cnn1KTZGrwUKvXb9EIhoAY4U1OgfgxuxqPGR7aPQjc4uvdELBsuREVBbM53Cb1iVKdItMU1KyxMGQZlcOmAOLO4w4ru7bT02KAMQKwDtbWrlAEfoWhZWnYUlY-LiMFI_vYXllQAMtp0D5mPWI5hoYm4r7aRQORCYdDs_qxE_M2ZxoTrdcZHaJuMT37moInHjwc-zzwyo8qpy-Zz649T3Uxx4N3UGc_562XmJGpHXg

For example: Signing and verifying the signedConsent in consent

In the AA ecosystem, Consents are signed artefacts authorizing a FIU to request for data with an FIP.

Consent must be transmitted with every FI Request to the Account Aggregator by FIU. Hence it is important for an AA to generate a consent artefact with signature that can be verified by the FIP before honoring the request.

Since the consents are embedded within the FI Request, it is recommended to use JWS compact serialization (i.e., a JWS with embedded content) and embed the JWS itself in the FI Request.

Since the JWS already has the consent embedded, there is no need to include the plain text consent artefact.

The entity verifying the consent artefact signature can extract the consent artefact JWS and simply verify it using any standard json JWS processing libraries.

Once signature is verified, the requester can extract the base64 encoded content payload from the JWS and convert to object if required for further processing and validation.

The body of a typical consent response looks like this:

{
  "ver": "1.0",
  "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
  "consentId": "XXXX-XXXX-XXXX-XXXX",
  "status": "ACTIVE",
  "createTimestamp": "2018-12-06T11:39:57.153Z",
  "signedConsent": "eyJraWQiOiIxNDIxMTc0ODUiLCJhbGciOiJSUzI1NiJ9.ewogICJjb25zZW50U3RhcnQiOiAiMjAxOS0wNS0yOFQxMTozODoyMC4zODArMDAwMCIsCiAgImNvbnNlbnRFeHBpcnkiOiAiMjAyMC0wNS0yOFQxMTozODoyMC4zODErMDAwMCIsCiAgImNvbnNlbnRNb2RlIjogIlZJRVciLAogICJmZXRjaFR5cGUiOiAiT05FVElNRSIsCiAgImNvbnNlbnRUeXBlcyI6IFsKICAgICJQUk9GSUxFIiwKICAgICJTVU1NQVJZIiwKICAgICJUUkFOU0FDVElPTlMiCiAgICBdLAogICJmaVR5cGVzIjogWwogICAgIkRFUE9TSVQiLAogICAgIlRFUk0tREVQT1NJVCIKICAgIF0sCiAgIkRhdGFDb25zdW1lciI6IHsKICAgICJpZCI6ICJBQS1pZGVudGlmaWVyIiwKICAgICJ0eXBlIjogIkFBIgogIH0sCiAgIkRhdGFQcm92aWRlciI6IHsKICAgICJpZCI6ICJCQVJCMEtJTVhYWCIsCiAgICAidHlwZSI6ICJGSVAiCiAgICB9LAogIAogICJDdXN0b21lciI6IHsKICAiaWQiOiAiY3VzdG9tZXItaWRlbnRpZmllckBhYS1oYW5kbGUiCiAgfSwKICAiQWNjb3VudHMiOiBbCiAgewogICAgImZpVHlwZSI6ICJERVBPU0lUIiwKICAgICJmaXBJZCI6ICJCQVJCMEtJTVhYWCIsCiAgICAiYWNjVHlwZSI6ICJTQVZJTkdTIiwKICAgICJsaW5rUmVmTnVtYmVyIjogIlVCSTQ4NTk2NDU3OSIsCiAgICAibWFza2VkQWNjTnVtYmVyIjogIlVCSTg1MjE3ODgxMjc5IgogICAgfSwKICB7CiAgICAiZmlUeXBlIjogIkRFUE9TSVQiLAogICAgImZpcElkIjogIkJBUkIwS0lNWFhYIiwKICAgICJhY2NUeXBlIjogIlNBVklOR1MiLAogICAgImxpbmtSZWZOdW1iZXIiOiAiVUJJNDg1OTY0NSIsCiAgICAibWFza2VkQWNjTnVtYmVyIjogIlVCSTg1MjE3ODgxMiIKICAgIH0KICBdLAogICJQdXJwb3NlIjogewogICAgImNvZGUiOiAiMTAxIiwKICAgICJyZWZVcmkiOiAiaHR0cHM6Ly9hcGkucmViaXQub3JnLmluL2FhL3B1cnBvc2UvMTAxLnhtbCIsCiAgICAidGV4dCI6ICJXZWFsdGggbWFuYWdlbWVudCBzZXJ2aWNlIiwKICAgICJDYXRlZ29yeSI6IHsKICAgICJ0eXBlIjogInB1cnBvc2VDYXRlZ29yeVR5cGUiCiAgICB9CiAgfSwKICAiRklEYXRhUmFuZ2UiOiB7CiAgICAiZnJvbSI6ICIyMDE5LTA1LTI4VDExOjM4OjIwLjM4MyswMDAwIiwKICAgICJ0byI6ICIyMDIwLTA1LTI4VDExOjM4OjIwLjM4MSswMDAwIgogICAgfSwKICAKICAiRGF0YUxpZmUiOiB7CiAgICAidW5pdCI6ICJNT05USCIsCiAgICAidmFsdWUiOiA0CiAgICB9LAogIAogICJGcmVxdWVuY3kiOiB7CiAgICAidW5pdCI6ICJIT1VSIiwKICAgICJ2YWx1ZSI6IDQKICAgIH0sCiAgIkRhdGFGaWx0ZXIiOiBbCiAgICB7CiAgICAidHlwZSI6ICJUUkFOU0FDVElPTkFNT1VOVCIsCiAgICAib3BlcmF0b3IiOiAiPiIsCiAgICAidmFsdWUiOiAiMjAwMDAiCiAgICB9CiAgXQogIH0.RDrwMlwjU9AeASBJdpAm_-Ss2-3Bd3rIC66RE_HMuSWf1gUIX4QYsbCp_2csGmR_PkbCF4K2nNF4WOkq_F5j-CMklMevqSx2ySs9V26aFoeq9cnn1KTZGrwUKvXb9EIhoAY4U1OgfgxuxqPGR7aPQjc4uvdELBsuREVBbM53Cb1iVKdItMU1KyxMGQZlcOmAOLO4w4ru7bT02KAMQKwDtbWrlAEfoWhZWnYUlY-LiMFI_vYXllQAMtp0D5mPWI5hoYm4r7aRQORCYdDs_qxE_M2ZxoTrdcZHaJuMT37moInHjwc-zzwyo8qpy-Zz649T3Uxx4N3UGc_562XmJGpHXg",
  "consentUse": {
    "logUri": "loguri string",
    "count": 1,
    "lastUseDateTime": "2018-12-06T11:39:57.153Z"
  }
}

Once extracted, the consent content of the JWS looks like this (formatted for readability):

{
  "consentStart": "2019-05-28T11:38:20.380+0000",
  "consentExpiry": "2020-05-28T11:38:20.381+0000",
  "consentMode": "VIEW",
  "fetchType": "ONETIME",
  "consentTypes": [
    "PROFILE",
    "SUMMARY",
    "TRANSACTIONS"
  ],
  "fiTypes": [
    "DEPOSIT",
    "TERM-DEPOSIT"
  ],
  "DataConsumer": {
    "id": "AA-identifier",
    "type": "AA"
  },
  "DataProvider": {
    "id": "BARB0KIMXXX",
    "type": "FIP"
  },
  "Customer": {
    "id": "customer-identifier@aa-handle"
  },
  "Accounts": [
    {
      "fiType": "DEPOSIT",
      "fipId": "BARB0KIMXXX",
      "accType": "SAVINGS",
      "linkRefNumber": "UBI485964579",
      "maskedAccNumber": "UBI85217881279"
    },
    {
      "fiType": "DEPOSIT",
      "fipId": "BARB0KIMXXX",
      "accType": "SAVINGS",
      "linkRefNumber": "UBI4859645",
      "maskedAccNumber": "UBI852178812"
    }
  ],
  "Purpose": {
    "code": "101",
    "refUri": "https://api.rebit.org.in/aa/purpose/101.xml",
    "text": "Wealth management service",
    "Category": {
      "type": "purposeCategoryType"
    }
  },
  "FIDataRange": {
    "from": "2019-05-28T11:38:20.383+0000",
    "to": "2020-05-28T11:38:20.381+0000"
  },
  "DataLife": {
    "unit": "MONTH",
    "value": 4
  },
  "Frequency": {
    "unit": "HOUR",
    "value": 4
  },
  "DataFilter": [
    {
      "type": "TRANSACTIONAMOUNT",
      "operator": ">",
      "value": "20000"
    }
  ]
}

The entity verifying the consent artefact signature can extract the consent artefact JWS and simply verify it using any standard json JWS processing libraries.

Once signature is verified, the requester can extract the base64 encoded content payload from the JWS and convert to object if required for further processing and validation.

4. Give an example to generate JWS Signature

Change Description: Updated examples as per payload with newly added claims in JWS header section

Answer: We use Json Web Signature (JWS) method to sign the content, as described in RFC7515 [ https://tools.ietf.org/html/rfc7515 ]. JWS contains 3 sections, i.e. header, payload (content), and signature. All sections are base64url encoded. JWS is typically transmitted in JSON Serialization format, which represents base64url encoded strings as a continuous string, with each string separated by a dot. As per the ReBIT specifications, the content is already being sent in the http body of the message. Hence, including content in the JWS will be duplication of data and inefficient. Another option would be to send the JWS itself as the body of the http message. However, it obfuscates the message and renders debugging quite difficult. The JWS specification also provides a method to produce signature without the content. This is described in Appendix F of RFC7515. This method is called ‘Detached Content’ signature method. In this method, the generated JWS signature does not contain the payload part. only the header and signature are returned.

A typical Detached Content signature looks like this:

eyJiNjQiOmZhbHNlLCJraWQiOiIxNDIxMTc0ODUiLCJhbGciOiJSUzI1NiJ9..QG1fUKa8kQ9H-rxEekbE4ytlj39aMpRe1ZF7eod1vHpUxZwYKB_4_WAzsavCUHnP0wQd0z2jHUP0UzbYnDLEMUq9v_mlqj31wnKRPsc6GRDBl--HIp6h0y75t9ZYt0EWdC8aRQ22Gt8Xuk_JW-iK5p9M__P9SqZVJh90LZvxVbK99ETE7EVfaORaUAhz9PBTgdF79zd_hl3INHjd3D1u7qRS0U36XMam9LQ6Zxo_Rw7-09lmDp84nEa2x78U_t4nI0dpNK4_izoTqFgEdcCGgCRjye8sjE-pgCmfKd5dZuz6pse8DdfvCai2rHolhB6C7rhd0wNexqrPAllq1IRMwg

Note: The two ‘dots’ in the signature shows that the content which is usually attached between these two dots is absent.

Examples can be seen in section 4.5 of RFC7520 here: https://tools.ietf.org/html/rfc7520#page-24

In the method explained below, Detached Content signature is used. Sending API Request content in the http body and signature in http header.

In this method, the content can be sent as plain text in the body of the http message, and the signature can be sent separately in customized http header (x-jws-signature) of the same http request/response.

This method has several advantages:

In this method, following steps are performed:

On the receiving side:

A typical HTTP request using this method should look like the following:

As we can see this method is much simpler and has significant performance advantages, so it is recommended to use this method for all API request/responses.

For Example:

Sending API Request content in the http body, send signature in http header:

In this method, the content can be sent as plain text in the body of the http message, and the signature can be sent separately in customized http header of the same http request/response.

This method has several advantages:

In this method, following steps are performed:

A typical HTTP request using this method should look like the following:

POST /FI/request HTTP/1.1
Host: aaapi.aa.in
Content-Type: application/json
Content-Length: 643
aa_api_key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0b3B0YWwuY29tIiwiZXhwIjoxNDI2NDIwODAwLCJodHRwOi8vdG9wdGFsLmNvbS9qd3RfY2xhaW1zL2lzX2FkbWluIjp0cnVlLCJjb21wYW55IjoiVG9wdGFsIiwiYXdlc29tZSI6dHJ1ZX0.yRQYnWzskCZUxPwaQupWkiUzKELZ49eM7oWxAQK_ZXw"
x-jws-signature: eyJiNjQiOmZhbHNlLCJraWQiOiIxNDIxMTc0ODUiLCJhbGciOiJSUzI1NiJ9..QG1fUKa8kQ9H-rxEekbE4ytlj39aMpRe1ZF7eod1vHpUxZwYKB_4_WAzsavCUHnP0wQd0z2jHUP0UzbYnDLEMUq9v_mlqj31wnKRPsc6GRDBl--HIp6h0y75t9ZYt0EWdC8aRQ22Gt8Xuk_JW-iK5p9M__P9SqZVJh90LZvxVbK99ETE7EVfaORaUAhz9PBTgdF79zd_hl3INHjd3D1u7qRS0U36XMam9LQ6Zxo_Rw7-09lmDp84nEa2x78U_t4nI0dpNK4_izoTqFgEdcCGgCRjye8sjE-pgCmfKd5dZuz6pse8DdfvCai2rHolhB6C7rhd0wNexqrPAllq1IRMwg
{
  "ver": "1.0",
  "timestamp": "2018-06-09T09:58:50.505Z",
  "txnid": "c4a1450c-d08a-45b4-a475-0468bd10e380",
  "Consent": {
    "id": "654024c8-29c8-11e8-8868-0289437bf331",
    "digitalSignature": "Digital signature of the consentDetail section in the consent Artefact"
  },
  "FIDataRange": {
    "from": "2018-11-27T06:26:29.761Z",
    "to": "2018-12-27T06:26:29.761Z"
  },
  "KeyMaterial": {
    "cryptoAlg": "ECDHE",
    "curve": "Curve25519",
    "params": "string",
    "DHPublicKey": {
      "expiry": "2019-06-01T09:58:50.505Z",
      "Parameters": "string",
      "KeyValue": "string"
    },
    "Nonce": 0
  }
}

As we can see this method is much simpler and has significant performance advantages, so it is recommended to use this method for all API request/responses.