API for exporting the CoP
The CoP technology enables a CoP Administrator to create a set of rules. These rules instruct the gateway on how to process data that traverses it. Using an API, export the CoP from ESA to the local system. The CoP API exports the basic configurations from the ESAs config directory.
Using the CoP API, following directories and files can be retrieved from the config directory:
- Directories
- Resources
- Tunnels
- Services
- Log
- Files
- gateway.json
- features.json
After the required data is retrieved, the CoP API will create a CoP package. This package is encrypted with the PKCS5 standard and is Base64 encoded.
Supported Authentication Methods for CoP API
The following authentication methods can be used to establish a connection with the ESA or DSG:
- Basic authentication with the ESA or DSG user name and password.
- Client Certificate-based authentication.
- Token-based authentication.
API for Exporting the CoP Configurations
DSG offers two versions of the CoP API. The following are the two base URLs:
https://{IP address of ESA}/3.3.0.0.{build number}/1/exportGatewayConfigFile
. This is the existing version of the API.https://{IP address of ESA}}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles
. This API is introduced from version 3.3.0.0. Also, the API uses a stronger cipher and key.
This API request exports the CoP package that can only be used with DSG containers.
Exporting CoP using the Existing version
The following sections describe the API for version 1.
Base URL
https://{IP address of ESA}/3.3.0.0.{build number}/1/exportGatewayConfigFile
Method
POST
Curl request syntax
Export API- PKCS5
```
curl --location --request POST 'https://<IP address of ESA>/3.3.0.0.{build number}/1/exportGatewayConfigFile' \
--header 'Authorization: Basic <base64 encoded admin credentials>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"nodeGroup": "<node group name>",
"kek":{
"pkcs5":{
"passphrase": "<passphrase>",
"salt": "<salt>"
}}
}' -k -o <Response file name in .json format>
```
Authentication credentials
- username: Basic authentication user name
- password: Basic authentication password.
As per the requirement, Client Certificate-based authentication or Token-based authentication can also be used.
Request body elements
- nodeGroup name and version: Set the node group name and version for which the configurations should be exported.* In the request body element, the user can specify the node group name and version or only the node group name. If the node group name and version parameter is removed from the request body elements, then it will provide the active configurations.
Encryption Method
The pkcs5 encryption is used to protect the exported file. In this release, the publicKey encryption is not supported.
Encryption Method | Sub-elements | Description |
---|---|---|
pkcs5 | salt | Set the salt that will be used to encrypt the exported CoP. |
passphrase | Set the passphrase that will be used to encrypt the exported CoP. | The passphrase must be at least ten character long. The passphrase must contain at least one uppercase letter, one numeric value, and a special character. |
Exporting CoP using the new version
The following sections describe the API for the new version.
Base URL
https://{IP address of ESA}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles
Method
POST
Curl request syntax
Export API- PKCS5
```
curl --location --request POST 'https://{IP address of ESA}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles' \
--header 'Authorization: Basic <base64 encoded admin credentials>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"nodeGroup": "<node group name>",
"kek":{
"pkcs5":{
"passphrase": "<passphrase>",
"salt": "<salt>"
}}
}' -k -o <Response file name in .json format>
```
Authentication credentials
- username: Basic authentication user name
- password: Basic authentication password.
As per the requirement, Client Certificate-based authentication or Token-based authentication can also be used.
Request body elements
- nodeGroup name and version: Set the node group name and version for which the configurations should be exported.* In the request body element, the user can specify the node group name and version or only the node group name. If the node group name and version parameter is removed from the request body elements, then it will provide the active configurations.
Encryption Method
The pkcs5 encryption is used to protect the exported file. In this release, the publicKey encryption is not supported.
Encryption Method | Sub-elements | Description |
---|---|---|
pkcs5 | salt | Set the salt that will be used to encrypt the exported CoP. |
passphrase | Set the passphrase that will be used to encrypt the exported CoP. | The passphrase must be at least ten character long. The passphrase must contain at least one uppercase letter, one numeric value, and a special character. |
Scenarios
The CoP package can be exported for the following three scenarios.
Scenario 1
Exporting the active CoP configuration.
CURL request
curl --location --request POST 'https://{IP address of ESA}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles' \
--header 'Authorization: Basic YWRtaW46YWRtaW4xMjM0' \
--header 'Content-Type: text/plain' \
--header 'Cookie: SameSite=Strict' \
--data-raw '{
"kek":{
"pkcs5":{
"passphrase": "xxxxxxxxxx",
"salt": "salt"
}
}
}'
-k -o cop_demo.json
CURL response
{
"cop_version": "1.0.0.0.1",
"timestamp": 1638782764,
"cop": {
"dsg_version": "3.1.0.0.x",
"copPackage":"<Contents of encrypted CoP package in base64 format>"
}
}
Scenario 2
Exporting the CoP configuration for lob1 node group.
CURL request
curl --location --request POST 'https://{IP address of ESA}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles' \
--header 'Authorization: Basic YWRtaW46YWRtaW4xMjM0' \
--header 'Content-Type: text/plain' \
--header 'Cookie: SameSite=Strict' \
--data-raw '{
"nodeGroup": "lob1",
"kek":{
"pkcs5":{
"passphrase": "xxxxxxxxxx",
"salt": "salt"
}
}
}'
-k -o cop_demo.json
CURL response
{
"nodeGroup": "lob1",
"cop_version": "1.0.0.0.1",
"timestamp": 1638796249,
"cop": {
"dsg_version": "3.1.0.0.x",
"copPackage":"<Contents of encrypted CoP package in base64 format>"
}
}
Scenario 3
Exporting the CoP configuration for a particular configuration version of lob1 node group.
CURL request
curl --location --request POST 'https://{IP address of ESA}/3.3.0.0.{build number}/1/v1/exportGatewayConfigFiles' \
--header 'Authorization: Basic YWRtaW46YWRtaW4xMjM0' \
--header 'Content-Type: text/plain' \
--header 'Cookie: SameSite=Strict' \
--data-raw '{
"nodeGroup": "lob1:2021_11_24_03_24_36",
"kek":{
"pkcs5":{
"passphrase": "xxxxxxxxxx",
"salt": "salt"
}
}
}'
-k -o cop_demo.json
CURL response
{
"nodeGroup": "lob1",
"cop_version": "1.0.0.0.1",
"timestamp": 1638796804,
"cop": {
"dsg_version": "3.1.0.0.x",
"copPackage":"<Contents of encrypted CoP package in base64 format>"
}
}