Skip to main content
European CommissionEBSI European Blockchain
Get Help

1. Setup your wallet

Role: New Entity

This step is performed by the New Entity that wants to become a trusted issuer in the EBSI ecosystem.

This guide presents the steps to set up your wallet in the EBSI CLI. The wallet will contain your cryptographic keys and DID (Decentralized Identifier) that will be used throughout the onboarding process.

Prerequisites​

Before starting, ensure you have:

  1. Node.js v22 installed on your system
  2. EBSI CLI installed (npx @cef-ebsi/cli)
  3. Access to EBSI environment (test, pilot, or production)
  4. Secure storage for your private keys

Supported Cryptographic Algorithms​

The EBSI CLI supports four cryptographic algorithms for key generation and management:

Available Algorithms​

  • ES256K: Elliptic Curve Digital Signature Algorithm using secp256k1 curve
  • ES256: Elliptic Curve Digital Signature Algorithm using P-256 curve
  • RS256: RSA Signature Algorithm with SHA-256
  • EdDSA: Edwards Curve Digital Signature Algorithm

EBSI Usage​

For EBSI, the main algorithms used are:

  • ES256K: Used to sign blockchain transactions and manage DID documents
  • ES256: Used to sign verifiable credentials and presentations
Algorithm Selection

While the CLI supports all four algorithms, ES256K and ES256 are the recommended algorithms for EBSI operations. The other algorithms (RS256 and EdDSA) are available for compatibility with other systems or specific use cases.

Start the CLI​

Launch the EBSI CLI from the terminal (not inside node):

npx @cef-ebsi/cli

Set your environment​

Choose the appropriate EBSI environment:

# For testing
env test

# For pilot environment
env pilot

# For production (when available)
env production

Generate ES256K key pair​

The ES256K key pair is used for blockchain operations and DID document management:

using user ES256K

This command will generate a new ES256K key pair and display the generated information:

{
  "address": "0xCCD583C21e6ce6Cd6d9f3516bbe99C119Aec9601",
  "did": "did:ebsi:z21fbZvDnJ3rytfGiSArPn3R",
  "didVersion": 1,
  "keys": {
    "ES256K": {
      "id": "lNWEE34CUEWaY81d2k5zwDQBIHe_z5VuI4lStbcWIfs",
      "isHardwareWallet": false,
      "kid": "did:ebsi:z21fbZvDnJ3rytfGiSArPn3R#lNWEE34CUEWaY81d2k5zwDQBIHe_z5VuI4lStbcWIfs",
      "privateKeyHex": "0x5713072d71975014b60936506fc88798069ce18d9c807f906a9ea3a5e893c368",
      "privateKeyJwk": {
        "crv": "secp256k1",
        "d": "VxMHLXGXUBS2CTZQb8iHmAac4Y2cgH-Qap6jpeiTw2g",
        "kty": "EC",
        "x": "czpyz-_qrdsgDIZ0jZbvcCNHZAM6ndoUv0Vh7MJqiv8",
        "y": "Rge9lSHpAtqvPBCBZGjZtpe7J7ceyX0wWGraaE5pMu8"
      },
      "publicKeyHex": "0x04733a72cfefeaaddb200c86748d96ef70234764033a9dda14bf4561ecc26a8aff4607bd9521e902daaf3c10816468d9b697bb27b71ec97d30586ada684e6932ef",
      "publicKeyJwk": {
        "crv": "secp256k1",
        "kty": "EC",
        "x": "czpyz-_qrdsgDIZ0jZbvcCNHZAM6ndoUv0Vh7MJqiv8",
        "y": "Rge9lSHpAtqvPBCBZGjZtpe7J7ceyX0wWGraaE5pMu8"
      },
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEczpyz+/qrdsgDIZ0jZbvcCNHZAM6ndoU\nv0Vh7MJqiv9GB72VIekC2q88EIFkaNm2l7sntx7JfTBYatpoTmky7w==\n-----END PUBLIC KEY-----\n"
    }
  }
}

Generate ES256 key pair​

The ES256 key pair is used for signing verifiable credentials and presentations:

using user ES256

This will add the ES256 key pair to your existing wallet:

{
  "address": "0xCCD583C21e6ce6Cd6d9f3516bbe99C119Aec9601",
  "did": "did:ebsi:z21fbZvDnJ3rytfGiSArPn3R",
  "didVersion": 1,
  "keys": {
    "ES256K": {
      // ... ES256K key details
    },
    "ES256": {
      "id": "FFc6nPFdCe1LnTmuFT_Z2XtSC4gX-yEjaES_1St1ONg",
      "isHardwareWallet": false,
      "kid": "did:ebsi:z21fbZvDnJ3rytfGiSArPn3R#FFc6nPFdCe1LnTmuFT_Z2XtSC4gX-yEjaES_1St1ONg",
      "privateKeyHex": "0x9dd836617a729b2f0394d5684cac92689e396c8b2b61a5679318789c314da00a",
      "privateKeyJwk": {
        "kty": "EC",
        "x": "u1sCG8N3fkFPQFuiPFfj-_P4s15i1k3kI4EpN51tjjc",
        "y": "OetqeBvZTwsnLXgjw_567EZdR4js1xOzQd2xWjM1ujg",
        "crv": "P-256",
        "d": "ndg2YXpymy8DlNVoTKySaJ45bIsrYaVnkxh4nDFNoAo"
      },
      "publicKeyHex": "0x04bb5b021bc3777e414f405ba23c57e3fbf3f8b35e62d64de4238129379d6d8e3739eb6a781bd94f0b272d7823c3fe7aec465d4788ecd713b341ddb15a3335ba38",
      "publicKeyJwk": {
        "kty": "EC",
        "x": "u1sCG8N3fkFPQFuiPFfj-_P4s15i1k3kI4EpN51tjjc",
        "y": "OetqeBvZTwsnLXgjw_567EZdR4js1xOzQd2xWjM1ujg",
        "crv": "P-256"
      },
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEu1sCG8N3fkFPQFuiPFfj+/P4s15i\n1k3kI4EpN51tjjc562p4G9lPCycteCPD/nrsRl1HiOzXE7NB3bFaMzW6OA==\n-----END PUBLIC KEY-----\n"
    }
  }
}

Save your private keys securely​

Critical Security Step

IMPORTANT: Save your private keys and DID in a secure location immediately after generation. These are required for all future operations and cannot be recovered if lost.

Your private keys and DID are displayed in the output above. You need to save both:

  1. Your DID: did:ebsi:z21fbZvDnJ3rytfGiSArPn3R (use view user.did to get your actual DID)
  2. Your private keys: The storage format depends on the algorithm used

For ES256K and ES256 algorithms​

You have two options for saving private keys:

Copy the value in privateKeyHex from the generated output:

  • ES256K privateKeyHex: 0x5713072d71975014b60936506fc88798069ce18d9c807f906a9ea3a5e893c368
  • ES256 privateKeyHex: 0x9dd836617a729b2f0394d5684cac92689e396c8b2b61a5679318789c314da00a

The privateKeyHex format is recommended because it's shorter and easier to handle.

Option 2: Save privateKeyJwk (Alternative)​

Alternatively, you can save the privateKeyJwk object:

  • ES256K privateKeyJwk: The complete JWK object from the output
  • ES256 privateKeyJwk: The complete JWK object from the output

For RS256 and EdDSA algorithms​

These algorithms only support privateKeyJwk format:

  • RS256 privateKeyJwk: The complete JWK object from the output
  • EdDSA privateKeyJwk: The complete JWK object from the output
Storage Format

RS256 and EdDSA algorithms do not provide privateKeyHex values. You must save the privateKeyJwk object for these algorithms.

Security Requirements​

Make sure to:

  1. Save your DID and private key values (JWK or hex string) securely
  2. Store them in encrypted storage or a hardware security module
  3. Never share private keys with anyone
  4. Keep backups in multiple secure locations

Loading Your User in the Future​

The method to load your user credentials depends on the algorithm used:

For ES256K and ES256 algorithms​

You have two options:

# For ES256K
using user ES256K did1 <ES256K_PRIVATE_KEY_HEX> <DID>

# For ES256
using user ES256 did1 <ES256_PRIVATE_KEY_HEX> <DID>

Example:

using user ES256K did1 0x5713072d71975014b60936506fc88798069ce18d9c807f906a9ea3a5e893c368 did:ebsi:z21fbZvDnJ3rytfGiSArPn3R
Method 2: Using privateKeyJwk​

The CLI tool does not accept commands split across multiple lines, so you need to:

  1. Remove all newlines from the JWK to have everything in a single line
  2. Paste the single-line JWK in the command
# For ES256K
using user ES256K did1 <ES256K_PRIVATE_KEY_JWK> <DID>

# For ES256
using user ES256 did1 <ES256_PRIVATE_KEY_JWK> <DID>

Example:

using user ES256K did1 {"crv":"secp256k1","d":"VxMHLXGXUBS2CTZQb8iHmAac4Y2cgH-Qap6jpeiTw2g","kty":"EC","x":"czpyz-_qrdsgDIZ0jZbvcCNHZAM6ndoUv0Vh7MJqiv8","y":"Rge9lSHpAtqvPBCBZGjZtpe7J7ceyX0wWGraaE5pMu8"} did:ebsi:z21fbZvDnJ3rytfGiSArPn3R

For RS256 and EdDSA algorithms​

These algorithms only support privateKeyJwk format:

# For RS256
using user RS256 did1 <RS256_PRIVATE_KEY_JWK> <DID>

# For EdDSA
using user EdDSA did1 <EdDSA_PRIVATE_KEY_JWK> <DID>

Important: The JWK must be in a single line (remove all newlines before pasting).

Recommendation

For ES256K and ES256, use the privateKeyHex method as it's shorter and less prone to formatting errors when copying and pasting.

You can view your current wallet information at any time:

# View your DID
view user.did

# View your wallet details
view user

Verify your setup​

Confirm that your wallet is properly configured:

# Check your DID
view user.did
# Output: did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw

# Check your environment
env
# Output: pilot (or your selected environment)

# Verify both key pairs are loaded
view user.keys.ES256K.id
view user.keys.ES256.id
Congratulations!

You have successfully set up your wallet with both ES256K and ES256 key pairs. Your DID is now ready for the onboarding process.

Next Step: Contact a Trusted Issuer or Support Office to obtain a "Verifiable Authorisation To Onboard" credential (Step 2).

Key Information for Next Steps​

Before proceeding to Step 2, you'll need to share the following information with your Trusted Issuer or Support Office:

  • Your DID: did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw (use view user.did to get your actual DID)
  • Your use case: What type of trusted issuer you want to become (Root TAO, TAO, or TI)

The Trusted Issuer or Support Office will use this information to issue the appropriate onboarding credential for you.