diff --git a/registry/Onboarding of Participants.md b/registry/Onboarding of Participants.md index 6912252..a426764 100644 --- a/registry/Onboarding of Participants.md +++ b/registry/Onboarding of Participants.md @@ -1,23 +1,52 @@ -# Onboarding of Network Participants in Prod and PreProd +# Onboarding of Network Participants ## Supported Registrations -![image](https://user-images.githubusercontent.com/107539333/190342634-ad4ff9a6-b1e6-4ba7-b55a-6d25d6b4b5f9.png) +1. ops_no : 1 - Buyer App Registration +2. ops_no : 2 - Seller App Registration +3. ops_no : 4 - Buyer & Seller App Registration + +> Note: ops_no 3 & 5 have been depricated as feature of Seller On Record (SOR) in Registry is obsolete. ## Prerequisites -1. Purchase valid domain name. This becomes part of your subscriber ID. subscriber_id -2. Purchase valid SSL certificate for the purchase domain. This will be used while performing Online Certificate Status Protocol check. -3. Get your subscriber_id whitelist/approved by ONDC. To do that please reach out to tech@ondc.org. -4. Configure your system with domain name and SSL. All communication with ONDC Network should happen through this domain. -5. Develop and host /on_subscribe : `` https:////on_subscribe`` -6. Refer for Request Body and Response ``https://app.swaggerhub.com/apis-docs/ONDC/ONDC-Registry-Onboarding/2.0.5#/ONDC%20Network%20Participant%20Onboarding/post_subscriber_url_on_subscribe `` -7. Generate Signing Key Pair - signing_public_key and signing_private_key -8. Generate Encryption Key Pair - encryption_public_key and encryption_private_key (Reference utilities here: https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/signing_and_verification) -9. Generate Unique Request ID (request_id). It should be unique for a Network Participant. It can be in any format. For example - it can be UUID or a simple number or alphanumeric format. -10. Generate SIGNED_UNIQUE_REQ_ID => ( Sign request_id using signing_private_key generated in step 7 ) -11. Create ``ondc-site-verification.html`` and place it at subscriber_id by adding SIGNED_UNIQUE_REQ_ID generated in step 10. Registry shall check existence of ondc-site-verification.html at -``https:///ondc-site-verification.html`` +1. Network Participant (NP) shall have a valid domain (FQDN/DNS) name. This becomes part of your subscriber ID (subscriber_id). + + ``` + eg: prod.ondcapp.com + ``` + +2. NP shall have a valid SSL certificate for your domain. This will be used while performing Online Certificate Status Protocol (OCSP) validation. +3. Get your subscriber_id whitelisted/approved by ONDC. To do that + + 1. For Staging: Fill out the [subscriber id whitelisting form](https://docs.google.com/forms/d/1k5k-N2JW4azLsdkJVbWjlsW549Nz5tUatYozSmJERQk/viewform?edit_requested=true). + 2. For Preprod: please reach out to tech@ondc.org post successful demo signoff from ONDC Ops team + 3. For Prod : please reach out to tech@ondc.org post tech and ops clearance. + +4. Configure your system with domain name and SSL. All communication with ONDC Network should happen through this domain. + +## Steps + +> Steps 4 to 7 can be done using the utility [here](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/on_subscibe-service). Every Participant shall perform Steps 1 and 2 to generate keys as below. +1. Generate Signing Key Pair (ed25519 Algorithm) - signing_public_key and signing_private_key; (base64 encoded) +> Refer utility below in step 2 +2. Generate Encryption Key Pair (X25519 Algorithm) - encryption_public_key (ASN.1 Der format-> base64 encoded) and encryption_private_key (base64 encoded). Use the utilities provided below to generate signing and encryption key pairs: + - [Java](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/ondc-crypto-utility-master) + - [Python](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/signing_and_verification) + - [GoLang](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/signing_and_verification/golang) + Note: + [Libsodium library](https://libsodium.gitbook.io/doc/bindings_for_other_languages) can be utilised to generate the key pairs. + For NodeJS: Inbuilt Crypto library should be used instead of Libsodium library. The generated encryption public key is already encoded in the ASN.1 DER format. + - You can refer to the documentation for information on the format and generation of keys [here](./key-format-generation.md). +3. Generate Unique Request ID (request_id). It should be unique for a network participant. It can be in any format. For example - it can be UUID or a simple number or alphanumeric format. +4. Generate SIGNED_UNIQUE_REQ_ID => Sign request_id using signing_private_key generated in step 1 (signed using ed25519 algorithm without hashing). + + The [on_subscribe utility](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/on_subscibe-service) has methods implemented to sign the message (request_id). + +5. Create `ondc-site-verification.html` and place it at subscriber_id by adding SIGNED_UNIQUE_REQ_ID generated in step 4. Registry shall check existence of ondc-site-verification.html at + `https:///ondc-site-verification.html` + + ``` @@ -30,38 +59,74 @@ ``` -> *Note: Please use the illustrated html as-is and only replace `SIGNED_UNIQUE_REQ_ID` with your correspnding generated signature, specifically use single quotes `'` to hold the information* -12. Configure developed /on_subscribe implementation to use enc_dec_private_key (generated in step 8) and ONDC public key to decrypt the challenge_string -13. Create /subscribe request as follows +6. Configure developed /on_subscribe implementation. + Create encryption shared key using: encryption private key (generated in step 2) and ONDC public key to decrypt the challenge_string (received in the on_susbcribe call) using AES algorithm. + + ``` + ONDC public key (prod) = "MCowBQYDK2VuAyEAvVEyZY91O2yV8w8/CAwVDAnqIZDJJUPdLUUKwLo3K0M=" + ONDC public key (pre-prod) = "MCowBQYDK2VuAyEAa9Wbpvd9SsrpOZFcynyt/TO3x0Yrqyys4NUGIvyxX2Q=" + ONDC public key (staging) = "MCowBQYDK2VuAyEAduMuZgmtpjdCuxv+Nc49K0cB6tL/Dj3HZetvVN7ZekM=" + ``` + +7. Host /on_subscribe endpoint : + + 1. `https:////on_subscribe ` + The (Node.JS/Python) [utility](https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/on_subscibe-service) can be used to implement the /on_subscribe endpoint. + +8. Refer [swaggerhub document](https://app.swaggerhub.com/apis-docs/ONDC/ONDC-Registry-Onboarding/2.0.5#/ONDC%20Network%20Participant%20Onboarding/post_subscriber_url_on_subscribe) for request body and response of /subscribe API. +9. Create /subscribe request as follows: + ``` -1. subscriber_id= YOUR SUBSCRIBER ID -2. callback_url= Relative path to on_subscribe implementation -3. signing_public_key= -4. encryption_public_key= -5. ONDC public key (prod) = "MCowBQYDK2VuAyEAvVEyZY91O2yV8w8/CAwVDAnqIZDJJUPdLUUKwLo3K0M=" -6. ONDC public key (pre-prod) = "MCowBQYDK2VuAyEAa9Wbpvd9SsrpOZFcynyt/TO3x0Yrqyys4NUGIvyxX2Q=" -7. ONDC public key (staging) = "MCowBQYDK2VuAyEAduMuZgmtpjdCuxv+Nc49K0cB6tL/Dj3HZetvVN7ZekM=" -8. unique_key_id= -9. For other fields, please refer below swaggerhub link and examples mentioned under heading as ops_no_1, ops_no_2, ops_no_3, ops_no_4 and ops_no_5 +1.subscriber_id= YOUR SUBSCRIBER ID (abc.ondcapp.com) +2.callback_url= Relative path to on_subscribe implementation +3.subscriber_url = Relative path to the subscriber_id +4.signing_public_key= +5.encryption_public_key= +6.unique_key_id= +7.For other fields, please refer below swaggerhub link and examples mentioned under heading as ops_no_1, ops_no_2, ops_no_3, ops_no_4 and ops_no_5 https://app.swaggerhub.com/apis-docs/ONDC/ONDC-Registry-Onboarding/2.0.5 - ``` -## Steps -1. Send created request to URL for /subscribe is as below +10. Send created request to URL for /subscribe as below + ``` # For Staging Onboarding https://staging.registry.ondc.org/subscribe # For PreProd Onboarding https://preprod.registry.ondc.org/ondc/subscribe - + # For Prod Onboarding https://prod.registry.ondc.org/subscribe + ``` -2. Check if you have received success response . In case if you do not receive a success, then please go through section of listing of possible errors. And if still issue persists, please contact our support desk. Details are mentioned in step 4 below. -``` + +11. The call is received by the respective registry and following operations are performed: + +> 1. /subscribe payload schema is verified +> 2. OCSP Check: SSL Certificate is verified +> 3. Domain Verification: ondc-site-verification.html is verified; + > - should be hosted on `https:///ondc-site-verification.html` + > - request_id should be signed using the signing private key (without hashing) +> 4. /on_susbcribe is called by the registry with a challenge string hosted on the callback_url +> `https:////on_subscribe` +> ```json +> { +> "subscriber_id": "abc.com", +> "challenge": "encrypted_challenge_string" +> } +> ``` +> 5. The challenge string should be decrypted using the shared key (generated in step 6) and answer should be provided as a sync response. +> ```json +> { +> "answer": "decrypted_challange_string" +> } +> ``` + +12. Verify whether you have received a successful response. If a success response is not received, refer to the section listing possible errors. If the issue persists, kindly reach out to our support desk using the details provided in step 14 below. + +```json { "message": { "ack": { @@ -76,10 +141,36 @@ https://prod.registry.ondc.org/subscribe } } ``` -3. Check your record in registry lookup
- 3.1 /vlookup + +13. Check your record in registry lookup + +> 1. /lookup + +``` +# For Staging +https://staging.registry.ondc.org/lookup + +# For Pre-prod +https://preprod.registry.ondc.org/ondc/lookup + +# For PROD +https://prod.registry.ondc.org/lookup ``` -# For Staging + +``` + curl --location --request POST 'https://preprod.registry.ondc.org/ondc/lookup' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + + "country": "IND", + "domain":"ONDC:RET10" + + }' +``` +>2. /vlookup + +``` +# For Staging https://staging.registry.ondc.org/vlookup # For Pre-prod @@ -89,7 +180,7 @@ https://preprod.registry.ondc.org/ondc/vlookup https://prod.registry.ondc.org/vlookup ``` -``` +``` curl --location --request GET 'https://preprod.registry.ondc.org/ondc/vlookup' \ --header 'Content-Type: application/json' \ --data-raw '{ @@ -113,32 +204,8 @@ https://prod.registry.ondc.org/vlookup - type: enums are "buyerApp", "sellerApp", "gateway" ``` -
- 3.2 /lookup - -``` -# For Staging -https://staging.registry.ondc.org/lookup - -# For Pre-prod -https://preprod.registry.ondc.org/ondc/lookup -# For PROD -https://prod.registry.ondc.org/lookup -``` - -``` - curl --location --request POST 'https://preprod.registry.ondc.org/ondc/lookup' \ - --header 'Content-Type: application/json' \ - --data-raw '{ +14. In case you are not able to find your record in lookup and vlookup, please report to techsupport@ondc.org - "country": "IND", - "domain":"ONDC:RET10" - - }' -``` - -4. In case if you are not able to find your record in lookup and vlookup, please report to . - onboard.support@egov-protean.info ``` Please mention below details in email: # Name : XXXXXXX @@ -149,9 +216,12 @@ https://prod.registry.ondc.org/lookup # Issue or clarification at which step # : Prerequisites or Steps ? # Issue / Clarification required : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` + ## Listing of possible errors + ### Subscriber ID not whitelisted by ONDC -``` + +```json { "message": { "ack": { @@ -166,10 +236,14 @@ https://prod.registry.ondc.org/lookup } } ``` -Resolution -Please connect with ONDC officials - Supriyo and Neeraj and get your subscriber ID whitelisted + +Resolution: + +Please connect with ONDC (tech@ondc.org) and get your subscriber ID whitelisted + ### Timestamp is invalid -``` + +```json { "message": { "ack": { @@ -186,10 +260,14 @@ Please connect with ONDC officials - Supriyo and Neeraj and get your subscriber } ``` -Resolution -Need to put timestamp within stipulated timegap defined by ONDC. + +Resolution: + +Need to put timestamp within the stipulated timegap defined by ONDC. + ### Domain Verification Failed -``` + +```json { "message": { "ack": { @@ -206,10 +284,14 @@ Need to put timestamp within stipulated timegap defined by ONDC. } ``` - Resolution -The signature generated with signed public and private key and request id should be put into ondc-site-verification.html + +Resolution: + +The signature generated with signing private key and request id should be put into ondc-site-verification.html (signed using ed25519 algorithm without hashing) + ### Subscriber ID already exists -``` + +```json { "message": { "ack": { @@ -224,11 +306,14 @@ The signature generated with signed public and private key and request id should } } ``` -Resolution -if subscriber id already registered with ONDC then this error will be thrown. - + +Resolution: + +If the subscriber ID is already registered with ONDC, this error will be thrown. + ### OCSP Failed -``` + +```json { "message": { "ack": { @@ -243,10 +328,14 @@ if subscriber id already registered with ONDC then this error will be thrown. } } ``` -Resolution -Need to get a valid SSL certificate for the domain purchased. + +Resolution: + +Need to get a valid SSL certificate for the purchased domain. + #### Encryption Verification Failed -``` + +```json { "message": { "ack": { @@ -261,10 +350,14 @@ Need to get a valid SSL certificate for the domain purchased. } } ``` -Resolution -Need to register Encrypted private key and ondc public key and need to consume the challenge given by subscribe API and give the decrypted value back to subscribe API + +Resolution: + +Utilize the encrypted private key and ONDC public key, then process the challenge received in the on_subscribe callback. Respond synchronously by providing the decrypted value. + ### Incorrect Network participant details provided -``` + +```json { "message": { "ack": { @@ -279,14 +372,16 @@ Need to register Encrypted private key and ondc public key and need to consume t } } ``` -Resolution -- Incorrect type mentioned in JSON. E.g. for Option 1 where NP is registering and type is set sellerApp then the above error will be shown. The value should be according to option set here. -- for option 3 instead of MSN set to true, it has been put as false and vice versa for non msn the flag is set true. +Resolution: + +Incorrect JSON Type Specification: For example, in Option 1, if the Network Participant is registering and the type is set to sellerApp, the aforementioned error will occur. The value should align with the specified options. +Option 3 Flag Misalignment: Instead of setting MSN to true, it has been incorrectly set as false, and vice versa for non-MSN cases where the flag is inaccurately set to true. ### Network participant's ondc-site-verification.html's encrypted signature verification failed -``` + +```json { "message": { "ack": { @@ -301,8 +396,10 @@ Resolution } } ``` -Resolution -- Use Plain Request_ID: Network Participant should use plain request_id while generating signature, without applying any hashing on the request_id -- Ensure Consistent Request_ID: Network Participant should use the same request_id in request body which they used while generating the signature. The request_id used during signature generation must match the one used during verification to ensure successful validation -- Ensure signing public key: Network Participant should send the same signing public key in the request body, who's corresnponding signing private key was used for signing. + +Resolution: + +Utilize Plain Request_ID: Network Participants are advised to use the request_id as is, without applying any hashing, when generating the signature. +Maintain Consistent Request_ID: Network Participants should ensure the request_id in the request body matches the one used during signature generation to guarantee successful validation. +Verify Signing Public Key: Network Participants should include the same signing public key in the request body that corresponds to the signing private key used during the signing process. diff --git a/registry/key-format-generation.md b/registry/key-format-generation.md new file mode 100644 index 0000000..94db96d --- /dev/null +++ b/registry/key-format-generation.md @@ -0,0 +1,97 @@ +# Ed25519 and X25519 Key Format and Generation +​ +## Introduction +​ + Cryptographic keys are essential for securing data and communications. In this document, we will explore the generation and format of Ed25519 signing keys and X25519 encryption keys. These keys are critical for data integrity, verification, authentication and secure communication. +​ +### Ed25519 Signing Keys +​ + Ed25519 is an elliptic curve digital signature algorithm. It uses EdDSA (Edwards-curve Digital Signature Algorithm) for secure signing. The key format for Ed25519 signing keys consists of a raw 32 byte private key and a public key pair. +​ +#### Public Key Format +​ + The `public key` in `Ed25519` is a 32-byte value. It is represented as a sequence of bytes and can be encoded using base64 or other encoding schemes. The code should handle the public key as a binary raw key base64 encoded. +​ +#### Private Key Format +​ + The `private key` in `Ed25519` is also a 32-byte binary raw key. It must be kept secret and should never be shared with others. The private key is used for signing data. +​ +#### Ed25519 Key Generation +​ + The key generation process for Ed25519 signing keys typically involves the following steps: +​ + `Random Key Pair Generation`: A cryptographically secure random number generator is used to generate a random key pair consisting of a public key and a private key. +​ + `Export Keys`: The generated keys are often kept in their raw binary format for storage or sharing. The public key can be shared, while the private key must be securely stored. +​ + Refer [rfc8032](https://datatracker.ietf.org/doc/html/rfc8032) +​ + ```mermaid + + sequenceDiagram + participant RandomGen as Random Number Generator + participant KeyPairGen as Key Pair Generator + participant ExportKeys as Export Keys + + RandomGen->>KeyPairGen: Generate random key pair + KeyPairGen-->>ExportKeys: Receive generated keys + ExportKeys-->>ExportKeys: Store keys in raw binary format + ``` +​ +#### Key Usage: + The public key is used by others to verify digital signatures. + The private key is used to sign data. + In ONDC use case each request sent and received needs to be signed and verified respectively. + For signing the private key stored at NPs end shall be used, whereas for verifying NPs signature the NPs keys are fetched from the registry using lookup & vlookup APIs. + The public key is verified before storing in the registry during the subscription process. +​ +### X25519 Encryption Keys + X25519 is an elliptic curve Diffie-Hellman key exchange algorithm used for secure key exchange. The key format for X25519 encryption keys includes a public key and a private key. +#### Public Key Format + The public key in X25519 is a 32-byte value. It is typically encoded in ASN.1 DER format, which is a standardized encoding format. The code should handle the public key as an ASN.1 DER-encoded key. +#### Private Key Format + The private key in X25519 is also a 32-byte binary value, represented as a binary raw key. It should be kept confidential and not shared with others. +#### X25519 Key Generation + The key generation process for X25519 encryption keys typically involves the following steps: +​ + `Random Key Pair Generation`: A cryptographically secure random number generator is used to generate a random key pair consisting of a public key and a private key. +​ + `Export Keys`: The generated private key is typically kept in its raw binary format, while the public key is encoded in ASN.1 DER format for storage or sharing. +​ + Refer [rfc7748](https://datatracker.ietf.org/doc/html/rfc7748) + ```mermaid + sequenceDiagram + participant RandomGen as Random Number Generator + participant KeyPairGen as Key Pair Generator + participant ExportKeys as Export Keys + + RandomGen->>KeyPairGen: Generate random key pair + KeyPairGen-->>ExportKeys: Receive generated keys + ExportKeys-->>ExportKeys: Keep private key as raw binary + ExportKeys-->>ExportKeys: Encode public key in ASN.1 DER format + + ``` +#### Key Usage: +​ + The public key is used in key exchange protocols to derive a shared secret. In ONDC use cases the public key is stored in the registry post the subscription process, Counter NP can query the registry and get your public key and use it to create a shared secret. + The private key is used in key exchange protocols to derive a shared secret. In ONDC use cases the private key is to be kept secure by each NP at their end, Counter NPs public key can be queried by the registry and used to create a shared secret. +​ + In ONDC use case these shared keys shall be utilised for symmetric encryption of field/payload in specific use case during P2P communication between 2 NPs. +​ + The public encryption key for any NP can be fetched from the registry using lookup & vlookup APIs. NPs can use counter NPs public key and their private key to form the shared key. +​ + The public key is verified before storing in the registry during the subscription process. +### Best Practices +To ensure the security of Ed25519 and X25519 keys: +​ +Keep private keys secure and protect them from unauthorized access. +Use strong random number generators during key pair generation. +### Conclusion +Ed25519 and X25519 keys are fundamental for data security, authentication, and secure communication. The key generation processes are similar, involving random key pair generation and key encoding. It is important to use the appropriate encoding format in your application for each key type as specified. +​ +For specific code in your chosen programming language, please refer to the documentation of relevant cryptographic libraries and frameworks that support Ed25519 and X25519. +​ +​ +​ + + \ No newline at end of file diff --git a/registry/signing-verification.md b/registry/signing-verification.md new file mode 100644 index 0000000..7cf707e --- /dev/null +++ b/registry/signing-verification.md @@ -0,0 +1,123 @@ +# ONDC Network Signing & Verifying +​ +When communicating over HTTP using Beckn APIs, the subscribers need to authenticate themselves to perform transactions with other subscribers on the network. Due to the commercial nature of the transactions, every request/callback pair is considered to be a "contract" between two parties. Therefore, it is imperative that all requests and callbacks are digitally signed by the sender and subsequently verified by the receiver. +​ +Furthermore, it is also desirable to ensure that the message was not altered or tampered with during transit. +​ +The protocol has provided 2 header values based from where the request originated or forwarded by. +​ +* `Authorization`: When the request is originated from a NP the request sends a header with “Authorization” key and value as explained below. +* `X-Gateway-Authorization`: When the request is forwarded from BG the request sends a header with “X-Gateway-Authorization” key and value as explained below. +​ + ```mermaid + sequenceDiagram + participant NP1 as NP1 (Originator of the request) + participant BG as BG (Gateway) + participant NP2 as NP2 (Receiver of the request) + + NP1 ->> BG: Create request body & Authorization Header value + BG -->> BG: Verify Authorization header + BG -->> NP2: Create X-Gateway-Authorization Header value + BG -->> NP2: Make requests to all corresponding NPs (e.g., NP2) + NP2 -->> NP2: Verify X-Gateway-Authorization & Authorization headers + + participant NP1 as NP1 (Originator of the request) + participant NP2 as NP2 (Receiver of the request) + + + + ``` +​ +​ +​ +### Authorization Header + Let the below be the request body in this example : + ```json + {"context":{"domain":"nic2004:60212","country":"IND","city":"Kochi","action":"search","core_version":"0.9.1","bap_id":"bap.stayhalo.in","bap_uri":"https://8f9f-49-207-209-131.ngrok.io/protocol/","transaction_id":"e6d9f908-1d26-4ff3-a6d1-3af3d3721054","message_id":"a2fe6d52-9fe4-4d1a-9d0b-dccb8b48522d","timestamp":"2022-01-04T09:17:55.971Z","ttl":"P1M"},"message":{"intent":{"fulfillment":{"start":{"location":{"gps":"10.108768, 76.347517"}},"end":{"location":{"gps":"10.102997, 76.353480"}}}}}} + ``` +Let NP’s keys be : +``` +signing_public_key = awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk= +signing_private_key = lP3sHA+9gileOkXYJXh4Jg8tK0gEEMbf9yCPnFpbldhrAY+NErqL9WD+Vav7TE5tyVXGXBle9ONZi2W7o144eQ== +​ +``` +The NP performs the following steps to create the Authorization header +1. Generate the `digest` of the request body using the `BLAKE-512` hashing function + ``` + b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw== + ``` +2. Generate the created field. The `created` field expresses when the signature was created. The value MUST be a Unix timestamp integer value. A signature with a `created` timestamp value that is in the past MUST be processed. + ``` + (created): 1641287875 + ``` +3. Generate the expires field. The `expires` field expresses when the signature ceases to be valid. The value MUST be a Unix timestamp integer value. A signature with an `expires` timestamp value that is in the future MUST be processed. + ``` + (expires): 1641291475 + ``` +4. Concatenate the three values, i.e the `created`, `expires` and `digest` in the format as shown below. The below string is the signing string which the BAP is going to use to sign the request + ``` + (created): 1641287875\n(expires):1641291475\ndigest:BLAKE-512=b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw== + ``` +5. The NP will then sign this string using its registered signing private key via the Ed25519 Signature Scheme +6. Finally the NP will generate a base64 encoded string of the signature and insert it into the signature parameter of the Authorization header + ``` + cjbhP0PFyrlSCNszJM1F/YmHDVAWsZqJUPzojnE/7TJU3fJ/rmIlgaUHEr5E0/2PIyf0tpSnWtT6cyNNlpmoAQ== + ``` +7. Finally the Authorization header will look like this. (Let's assume subscriber_id = example-bap.com, unique_key_id = bap1234) + ``` + Signature + keyId="example-bap.com|bap1234|ed25519",algorithm="ed25519",created="1641287875",expires="1641291475",headers=" (created)(expires)digest",signature="cjbhP0PFyrlSCNszJM1F/YmHDVAWsZqJUPzojnE/7TJU3fJ/rmIlgaUHEr5E0/2PIyf0tpSnWtT6cyNNlpmoAQ==" + ``` + 8. Finally the NP includes the authorization header in the request and calls the receiver's API +​ +### X-Gateway-Authorization Header: + This works similarly to the authorization process, but with a Gateway as the Network Participant (NP). Here, the Gateway uses its private key for signing, along with the corresponding subscriber_id and unique key id. +​ +### Verify Signature + `NP1 → Originator of the request + NP2 → Receiver of the request` +​ + 1. NP2 gets keyId from the Authorization or X-Gateway-Authorization header + ``` + example-bap.com|bap1234|ed25519 + ``` + 2. NP splits the keyId string into subscriber ID, Unique Key ID and algorithm using the delimiter "|". + 3. The keyId uses the format {subscriber id}|{unique_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm parameter in the Authorization header, then the NP should return an unauthorised error via NACK. + 4. The keyId also contains a unique_key_id which is used when the NP1 has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple types of subscribers + 5. The NP2 will now look up the registry for the public key of the subscriber by sending the subscriber_id and the unique_key_id via the lookup API or by retrieving a cached copy of the subscriber's public key matching the subscriber_id and unique_key_id. It will receive the public key of the NP1 : + + ``` + awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk= + ``` + + + + 6. If no valid key is found, the NP2 must return a NACK response with Unauthorised response code. +​ +### Request Journeys Patterns: + #### Request via gateway: + +​ + ``` + NP1 → Originator of the request to Gateway + BG → Gateway + NP2 → Receiver of the request + ``` + 1. NP1 would create the request body and creates a Authorization Header value + 2. NP1 would make request to the BG + 3. BG on receiving the request verifies the Authorization header + 4. BG creates a X-Gateway-Authorization Header value + 5. BG will make multiple requests to all corresponding NP’s lets say NP2 is one + 6. NP2 on receiving the request form the BG verifies the X-Gateway-Authorization & Authorization headers on receiving the request +​ +​ + #### Peer to Peer Request + NP1 → Originator of the request + NP2 → Receiver of the request + + 1. NP1 would create the request body and creates a Authorization Header value + 2. NP1 would make request to the NP2 + 3. NP2 on receiving the request form the NP1 verifies the Authorization headers on receiving the request +​ +​ +​ \ No newline at end of file