Register Your Entity Secret

In this guide you will learn how to generate, encrypt, and register an Entity Secret. You can use standard libraries for generating and encrypting the Entity Secret, or SDK methods to simplify your development journey. Likewise, for registering an Entity Secret Ciphertext, you can use an SDK method or the Circle Console.

1. Create a Developer Account and acquire an API key in the Console.
2. Install the applicable server-side SDK for your language - needed for 1a, 2a, 3a below.

The Entity Secret is a randomly generated 32-byte key designed to enhance security in developer-controlled wallets. After being generated, the hex-encoded Entity Secret key is encrypted into ciphertext for greater data safety. Later on, to create a wallet or to perform a transaction, you must append the Entity Secret ciphertext to the API request arguments. The ciphertext must be re-encrypted (rotated) whenever an API requires it.

There are two ways to generate an Entity Secret: using the SDK, or using standard libraries or CLI tools. Once generated the Entity Secret will consist of a 32-byte hex string value similar to: 7ae43b03d7e48795cbf39ddad2f58dc8e186eb3d2dab3a5ec5bb3b33946639a4.

You can use the SDK methods below to generate an Entity Secret.

import { generateEntitySecret } from '@circle-fin/developer-controlled-wallets'

// This will print out a new entity secret and sample code to register the entity secret
generateEntitySecret()

The above code generates an Entity Secret and displays it on your terminal screen. Make sure to save your Entity Secret since you will use it in the following steps.

You can also use standard libraries or CLI tools to generate the Entity Secret. Below are a few examples.

openssl rand -hex 32

The Entity Secret is displayed on your terminal screen. Make sure to save your Entity Secret since you will use it in the following steps.

Similarly, you can encrypt the Entity Secret in two ways to generate the Entity Secret Ciphertext: using the SDK, or manually using standard libraries.

You can use the SDK methods below to generate the Entity Secret Ciphertext.

import { generateEntitySecretCiphertext } from '@circle-fin/developer-controlled-wallets'

async function main() {
  await generateEntitySecretCiphertext({
    apiKey: '<your-api-key>',
    entitySecret: '<entity-secret>',
  })
}

main()[OR]

import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets'

const developerSDK = initiateDeveloperControlledWalletsClient({
  apiKey: '<your-api-key>',
  entitySecret: '<entity-secret>',
})

const entitySecretCiphertext =
  await developerSDK.generateEntitySecretCiphertext()
console.log(entitySecretCiphertext)

Similarly, you can create the Entity Secret Ciphertext using standard libraries or CLI tools. To that end, you must first retrieve your Entity Secret's public key. The public key plays a crucial role in generating the Entity Secret Ciphertext in the upcoming step. To obtain the required public key, initiate a request to the Get public key for entity API endpoint. Remember, this endpoint can be accessed by providing your valid API key for authentication.

// Import and configure the developer-controlled wallet SDK
const {
  initiateDeveloperControlledWalletsClient,
} = require('@circle-fin/developer-controlled-wallets')
const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
  apiKey: '<API_KEY>',
  entitySecret: '<ENTITY_SECRET>', // Make sure to enter the entity secret from the step above.
})

const response = await circleDeveloperSdk.getPublicKey({})

{
  "data": {
    "publicKey": "-----BEGIN RSA PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAsL4dzMMQX8pYbiyj0g5H\nFGwdygAA2xDm2VquY8Sk0xlOC0yKr+rqUrqnZCj09vLuXbg1BreO/BP4F4GEIHgR\nBNT+o5Q8k0OqxLXmcm5sz6CPlsFCom+MiOj6s7RD0SXg91WF8MrN88GyN53xkemA\nOYU1AlIt4dVIrFyGY8aQ57sbWHyIjim+do1kBX+svIA/FLHG/sycoGiPU1E+Kydf\nlEDga4iR2DSbW6Zte9cGDg9Ivw/seNd0TLzJz6oC9XgSK5Et6/ZpOmqJgvISQ6rT\nK15DJ8EzIOzZZuEVOefgy1S7rLdSH7DexuR4W7T+KpP/f8Px0bxd4N6MT5V5kBYa\ngYHHIvqlJvXe5EzwidIWk1rg1X+YJt2M48h3Pr9HeECcmrnEYOgp32m/9lJ8vKp9\nhNh0rEKww/ULd1HqCEm/I0QGuji13XcGxVo5+7KCb/C76CNdW3pdRMn6fwFh4WVu\nu99iRc9OZhlkphysWm44hs1ZPpMCAkKttWjhnLZwIatN27x2JUqoCEUOho19iT+F\nwlPFA7E0Ju9Rqm68AkCXxHsJsAuGT8m6FLQZLHv4JyO/QEVzD7vY08A2I5dz1mVt\ngVam1/05Axju6poRomx/DUxiR0QH1+0Kg15+2A0fRkBggTTn7kvGsgz0cqk9cTm0\nEITpIVGcSGrVNRrmSye2OW0CAwEAAQ==\n-----END RSA PUBLIC KEY-----\n"
  }
}

Once you have the public key, you will use RSA to encrypt your Entity Secret and generate its ciphertext. Immediately after, you will transform this encrypted data into a Base64 format. The output ciphertext will be exactly 684 characters long.

const forge = require('node-forge')

const entitySecret = forge.util.hexToBytes('YOUR_ENTITY_SECRET')
const publicKey = forge.pki.publicKeyFromPem('YOUR_PUBLIC_KEY')
const encryptedData = publicKey.encrypt(entitySecret, 'RSA-OAEP', {
  md: forge.md.sha256.create(),
  mgf1: {
    md: forge.md.sha256.create(),
  },
})

console.log(forge.util.encode64(encryptedData))

Finally, you can register your Entity Secret in two ways: using the SDK, or using the Circle Console.

You can use the SDK methods below to register your Entity Secret.

import { registerEntitySecretCiphertext } from '@circle-fin/developer-controlled-wallets'

registerEntitySecretCiphertext({
  apiKey: '',
  entitySecret: '',
  recoveryFileDownloadPath: '',
})

Now that the Entity Secret has been registered, make sure to read and follow some Final Considerations.

You can also register the Entity Secret Ciphertext within the Circle Console. You need to register the ciphertext in the console only once by following the steps below.

1. Access the Configurator Page in the Circle Console.
2. Enter the Entity Secret Ciphertext generated in the previous step.
3. Click Register to complete the Entity Secret Ciphertext registration.

Circle's APIs Requiring Entity Secret Ciphertext enforces a different Entity Secret Ciphertext for each API request. One-time use of Entity Secret Ciphertext tokens ensures that even if an attacker captures the ciphertext from a previous communication, they cannot exploit it in subsequent interactions.

To create a different Entity Secret Ciphertext token, repeat step 2. Encrypt the Entity Secret. As long as the Entity Secret Ciphertext comes from the same registered Entity Secret, it will be valid for subsequent API requests.

You have successfully registered your entity secret! Jump into the next guide, where you will learn how to:

1. Create your first developer-controlled wallet
2. Rotate and Reset Entity Secret: Check out how you can rotate and reset your Entity Secret.