README: Entity Secret Generation and Encryption

Getting Started

To generate an entity secret and encrypt with the entity public key, and register the entity secret ciphertext follow the steps below:

1. Choose a programming language: Select the programming language you are using for your application. We provide sample code snippets for Python and Golang.

2. Use the sample code (generate_hex_encoded_entity_secret) to generate a hex-encoded entity secret. You can also generate a 32 byte data and hex-encode it by yourselves.

Python

python python/generate_hex_encoded_entity_secret.py

Golang

go run golang/generate_hex_encoded_entity_secret.go

Node.js

node nodejs/generate_hex_encoded_entity_secret.js

3. Acquire the entity public key: Use the provided API endpoint GET /config/entity/publicKey to obtain the entity public key securely. This public key is required for the encryption process.

4. Replace the entity public key and hex-encoded entity secret in the sample code (generate_entity_secret_ciphertext), the sample code will encrypt and encode the entity secret in base64, and you will get the entity secret ciphertext accordingly.

Python

python python/generate_entity_secret_ciphertext.py

Golang

go run golang/generate_entity_secret_ciphertext.go

Node.js

node nodejs/generate_entity_secret_ciphertext.js

5. Register the entity secret ciphertext in the Configurator Page in the developer dashboard and click Register. The entity secret ciphertext only needs to be registered once, unless you need to rotate the entity secret.

6. Now you can append an entity secret ciphertext in the API request body for developer-controlled wallets. Note that the encryption and encoding of entity secret needs to be executed every time you append in an API request to prevent replay attack. There is no need to register an updated entity secret ciphertext; simply use the entity secret ciphertext as a variable in your API request and obtain the latest ciphertext generated by rerunning the sample code (generate_entity_secret_ciphertext). Here’s the sample API request for reference:

curl --location  --request POST 'https://api.circle.com/v1/w3s/developer/walletSets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [TEST_API_KEY]' \
--data '{ \
    "idempotencyKey": "b1433df1-8676-4610-b8c9-ef8b5de3c79d", \
    "name": "Entity WalletSet A", \
    "entitySecretCiphertext": "[ENTITY_SECRET_CIPHERTEXT]" \
}'

Note: Make sure to install related libraries for encryption before using the sample code. For Python sample code please first pip install pycryptodome. For Node.js sample code please first npm install node-forge

Note: Please store the hex-encoded entity secret carefully by yourself, as it is required for critical API requests and Circle does not store the information.

Note: Please refrain from directly embedding the hex-encoded entity secret within the code.