Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Onboarding of Participants.md #57

Closed
wants to merge 1 commit into from
Closed

Update Onboarding of Participants.md #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 61 additions & 19 deletions registry/Onboarding of Participants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,37 @@
# 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)

## 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 [email protected].
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://<YourDomain>/<YourCallBackURL>/on_subscribe``
5. Develop and host /on_subscribe endpoint: ``https://<YourDomain>/<YourCallBackURL>/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://<subscriber_id>/ondc-site-verification.html``
``https://<subscriber_id>/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.
```
<!--Contents of ondc-site-verification.html. -->
<!--Please replace SIGNED_UNIQUE_REQ_ID with an actual value-->
Expand All @@ -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= <value of sign_public_key generated in step 7>
4. encryption_public_key= <value of enc_dec_public_key generated in step 8>
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 = <value of sign_public_key generated in step 7>
4. encryption_public_key = <value of enc_dec_public_key generated in step 8>
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= <generate a unique number for tracking key pairs>
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 = <generate a unique number for tracking key pairs>

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
Expand All @@ -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": {
Expand Down