From f1ede3b7de69c1acbfef66f75a79048f1d23de50 Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Mon, 1 Dec 2025 03:41:48 +0000 Subject: [PATCH 1/6] feat(PF-172): update README --- README.md | 83 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 4766a0b..3e00bb4 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,69 @@ -# README: Entity Secret Generation and Encryption +# Entity Secret Generation and Encryption + +The Entity Secret is a 32-byte private key designed to secure your developer-controlled wallets. It acts as your secret password, your personalized cryptographic stamp, known only to you. ## 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. +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 -```bash -python python/generate_hex_encoded_entity_secret.py -``` - -Golang -```bash -go run golang/generate_hex_encoded_entity_secret.go -``` + **Python** + ```bash + python python/generate_hex_encoded_entity_secret.py + ``` -Node.js -```bash -node nodejs/generate_hex_encoded_entity_secret.js -``` + **Golang** + ```bash + go run golang/generate_hex_encoded_entity_secret.go + ``` + **Node.js** + ```bash + 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 -```bash -python python/generate_entity_secret_ciphertext.py -``` + **Python** + ```bash + python python/generate_entity_secret_ciphertext.py + ``` -Golang -```bash -go run golang/generate_entity_secret_ciphertext.go -``` + **Golang** + ```bash + go run golang/generate_entity_secret_ciphertext.go + ``` -Node.js -```bash -node nodejs/generate_entity_secret_ciphertext.js -``` + **Node.js** + ```bash + node nodejs/generate_entity_secret_ciphertext.js + ``` 5. Register the **entity secret ciphertext** in the Configurator Page in the [developer dashboard](https://console.circle.com/wallets/dev/configurator) 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: +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: -```bash -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]" \ -}' -``` + ```bash + 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**: 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. From 618e7b23a041899b820b936c938907212b07b86b Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Mon, 1 Dec 2025 06:29:00 +0000 Subject: [PATCH 2/6] update entity secret description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e00bb4..e7ed1f3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Entity Secret Generation and Encryption -The Entity Secret is a 32-byte private key designed to secure your developer-controlled wallets. It acts as your secret password, your personalized cryptographic stamp, known only to you. +The Entity Secret is a base64-encoded ciphertext of the 32-byte entity secret, encrypted using RSA-OAEP with SHA-256 as the hash function and MGF1 with SHA-256 as the mask generation function. ## Getting Started From be57183b8bbbe0cab3c1bd0e972b810e339749f3 Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Mon, 1 Dec 2025 06:30:39 +0000 Subject: [PATCH 3/6] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e7ed1f3..6f3a004 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The Entity Secret is a base64-encoded ciphertext of the 32-byte entity secret, e 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. +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. From cf3ed613bf97e6b21a1bd4afaff475ed44abc9a0 Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Mon, 1 Dec 2025 07:10:37 +0000 Subject: [PATCH 4/6] revise introduction --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6f3a004..9efcd51 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Entity Secret Generation and Encryption -The Entity Secret is a base64-encoded ciphertext of the 32-byte entity secret, encrypted using RSA-OAEP with SHA-256 as the hash function and MGF1 with SHA-256 as the mask generation function. +This repository demonstrates Entity Secret generation and encryption for Circle's W3S 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 for secure storage + 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 From 0e59ee9c4247f7dd098a58a9ec35a9f770022166 Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Mon, 1 Dec 2025 07:18:11 +0000 Subject: [PATCH 5/6] revise introduction --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9efcd51..6d22533 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,10 @@ This repository demonstrates Entity Secret generation and encryption for Circle's W3S 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 for secure storage - 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 + + 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 From 4e8bae0120ebaba526e764bbe375f7b3eece0d57 Mon Sep 17 00:00:00 2001 From: Chen Hui Jing Date: Thu, 4 Dec 2025 01:34:31 +0000 Subject: [PATCH 6/6] replace use of w3s --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6d22533..15a2562 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Entity Secret Generation and Encryption -This repository demonstrates Entity Secret generation and encryption for Circle's W3S API. +This repository demonstrates Entity Secret generation and encryption for the Circle Wallets API. The process involves two steps: