From 8fe4b7dc411e9d5e3784b3256f1773493473c7ea Mon Sep 17 00:00:00 2001 From: AbhijeetONDC <129926794+AbhijeetONDC@users.noreply.github.com> Date: Mon, 18 Dec 2023 14:51:03 +0530 Subject: [PATCH] Update Onboarding of Participants.md --- registry/Onboarding of Participants.md | 80 ++++++++++++++++++++------ 1 file changed, 61 insertions(+), 19 deletions(-) diff --git a/registry/Onboarding of Participants.md b/registry/Onboarding of Participants.md index 6912252..8fdc680 100644 --- a/registry/Onboarding of Participants.md +++ b/registry/Onboarding of Participants.md @@ -1,4 +1,4 @@ -# Onboarding of Network Participants in Prod and PreProd +# Onboarding of Network Participants ## Supported Registrations @@ -6,18 +6,32 @@ ## 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. +1. Purchase valid domain name. This becomes part of your subscriber ID. +2. Purchase valid SSL certificate for the purchased domain. This will be used while performing Online Certificate Status Protocol (OSCP) check. +3. Get your subscriber_id whitelisted by ONDC. For staging environment, anybody can request for whitelisting through this [Google Form](https://docs.google.com/forms/d/1k5k-N2JW4azLsdkJVbWjlsW549Nz5tUatYozSmJERQk/viewform?edit_requested=true). For whitelisting in prod and pre-prod environment, please reach out to tech@ondc.org or techsupport@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`` +5. Develop and host /on_subscribe endpoint: ``https:////on_subscribe``. Please make sure that the /on_subscribe is hosted after the callback_url route. In case you want to host /on_subscribe at root level, please send your callback_url as single slash "/". 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 +7. Generate Signing Key Pair - signing_public_key and signing_private_key (Reference utilities here: https://github.com/ONDC-Official/reference-implementations/tree/main/utilities/signing_and_verification) 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 ) +9. Generate Unique Request ID (request_id). It should be unique for each 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 ) - We're using the sodium library for this, which can be found for all major languages. + +```javascript +const signMessage = async ({ signingString, privateKey }: ISignMessage) => { + await _sodium.ready; + const sodium = _sodium; + + const signedMessage = sodium.crypto_sign_detached( + signingString, + sodium.from_base64(privateKey, _sodium.base64_variants.ORIGINAL), + ); + return sodium.to_base64(signedMessage, _sodium.base64_variants.ORIGINAL); +}; +``` + 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`` +``https:///ondc-site-verification.html``. Please make sure the .html is hosted at the root level and is unaffected by callback_url. Note: Domain verification through this method is done first and then the /on_subscribe is hit by the registry. ``` @@ -32,21 +46,49 @@ ``` > *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 -``` -1. subscriber_id= YOUR SUBSCRIBER ID -2. callback_url= Relative path to on_subscribe implementation -3. signing_public_key= -4. encryption_public_key= +12. Configure developed /on_subscribe implementation to use encryption_private_key (generated in step 8) and ONDC public key (mentioned below) to decrypt the challenge_string + +```javascript +// Make sure to use aed256ecb regardless of the language +function decryptAES256ECB(key, encrypted) { + const iv = Buffer.alloc(0); // ECB doesn't use IV + const decipher = crypto.createDecipheriv('aes-256-ecb', key, iv); + let decrypted = decipher.update(encrypted, 'base64', 'utf8'); + decrypted += decipher.final('utf8'); + return decrypted; +} + +// We're using the diffieHellman algorithm to create a shared key for decrypting the challenge + const sharedKey = crypto.diffieHellman({ + privateKey: privateKey, // Encrypted Private Key + publicKey: publicKey, // ONDC Public Key +}); + +// Host the /on_subscribe endpoint +app.post('/on_subscribe', function (req, res) { + const { challenge } = req.body; // Extract the 'challenge' property from the request body + const answer = decryptAES256ECB(sharedKey, challenge); // Decrypt the challenge using AES-256-ECB + const resp = { answer: answer }; + res.status(200).json(resp); // Send a JSON response with the answer +}); +``` +14. Once your /on_subscribe is ready, create /subscribe request to the appropriate environment's registry. The payload can be found in the [swagger documentation](https://app.swaggerhub.com/apis/ONDC/ONDC-Registry-Onboarding/2.0.5) for different NP types. The following details need to be fed in the request: +``` +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 +8. unique_key_id = + +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 @@ -60,7 +102,7 @@ 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. +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. ``` { "message": {