Entity Secret Generation and Encryption

This repository demonstrates Entity Secret generation and encryption for the Circle Wallets API.

The process involves two steps:

1. Generation (one-time): Generate a cryptographically secure 32-byte entity secret and encode it as a 64-character hex string.

2. Encryption (per API request): Encrypt the 32-byte entity secret using RSA-OAEP (with SHA-256 for both the OAEP hash and MGF1), then base64-encode the resulting ciphertext for API requests.

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, Golang and Node.js. For other languages, you will have to adapt the code accordingly.

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, first run pip install pycryptodome. For Node.js sample code, first run 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.