API for exporting the CoP

Export API for the rulesets in DSG containers.

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 MethodSub-elementsDescription
pkcs5saltSet the salt that will be used to encrypt the exported CoP.
passphraseSet 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 MethodSub-elementsDescription
pkcs5saltSet the salt that will be used to encrypt the exported CoP.
passphraseSet 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>"
}
}