Public Key Infrastructure (PKI) Implementation

Public Key Infrastructure (PKI) Explained

Public Key Infrastructure, or PKI, is a system that uses digital certificates to verify and authenticate the identity of users, devices, and services on the internet or private networks. It's a crucial technology for ensuring secure communication and data protection.

What is PKI?

PKI is a set of roles, policies, procedures, and systems needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption. It provides a way to establish trust in online interactions. Ledger Enterprise is implementing PKI in its infrastructure so that a number of its critical READ or GET endpoints can share information securely.

Key Components

Digital Certificates

Digital certificates are electronic documents that bind a public key with an issuer identity over a given validity period.

Public and Private Keys

PKI uses asymmetric cryptography, which involves a pair of keys:

• Public Key: Shared openly and used to encrypt data or verify digital signatures.

• Private Key: Kept secret and used to decrypt data encrypted with the corresponding public key or to create digital signatures.

Certificate Authority (CA)

A CA is a trusted entity that issues digital certificates. It verifies the identity of the entity requesting the certificate and signs the certificate with its own private key, creating a chain of trust.

How PKI Works at Ledger Enterprise - Getting the Root CA

The process typically involves the following steps:

1. Certificate Request: Sign into the Ledger Vault as an administrator. In the settings section of the Vault, there will be a button that allows the administrator to reveal the Root Certificate Authority (Root CA) of the HSM.

2. Reveal the Certificate: The administrator will click this button and be taken through a flow that allows them to download the Root CA and save the User ID of the workspace. An example of the Root Certificate can be seen below. The file format will be either .der or .pem.

3. Compute the SHA-256: Once the certificate is saved, the administrator will need to use it to compute the SHA-256 from the certificate. This will then be used for verification.

   1. To compute the SHA-256 on a Ubuntu or Mac, in the terminal, navigate to the directory the file is saved in and use the command $ sha256sum root.der. The output should be a 63 character aplpha-numeric string.

4. Certificate Verification: Once revealed, the administrator will then verify the SHA-256 as well as the User ID of the workspace on their Personal Security Device (PSD). If the information matches the previously saved information, it is safe and can be used for future verification.

5. Using the Certificate: When receiving address information from Ledger, the client will then be able to use this Root CA to verify the signed information that is sent from the relevant GET requests. This is further explained in the following section.

Example certificate

Certificate:
   Data:
       Version: 3 (0x2)
       Serial Number:
           1a:01:27:77:75:01:4b:d9:da:4a:c6:2e
       Signature Algorithm: ecdsa-with-SHA256
       Issuer: CN = Ledger Root
       Validity
           Not Before: Mar 12 09:18:32 2025 GMT
           Not After : Mar 11 09:18:32 2030 GMT
       Subject: CN = Ledger Root
       Subject Public Key Info:
           Public Key Algorithm: id-ecPublicKey
               Public-Key: (256 bit)
               pub:
                   04:72:51:7b:b4:7a:16:bf:5f:f6:64:86:ed:d5:7a:
                   10:a6:c6:8e:b5:4d:bb:b7:7b:b4:fc:a3:89:f1:22:
                   6e:5e:ad:bb:6e:fa:0c:32:eb:4d:8a:c0:26:1a:6d:
                   9f:a9:66:67:fe:b0:8c:3f:c5:bf:db:76:fe:cd:42:
                   2c:4e:18:73:af
               ASN1 OID: secp256k1
       X509v3 extensions:
           X509v3 Authority Key Identifier:
               keyid:B9:8A:5D:B1:AD:4F:8F:FE:FB:AB:5E:47:76:9C:5A:22:D0:6C:DD:0A

           X509v3 Basic Constraints: critical
               CA:TRUE, pathlen:2
           X509v3 Key Usage: critical
               Certificate Sign
           X509v3 Subject Key Identifier:
               B9:8A:5D:B1:AD:4F:8F:FE:FB:AB:5E:47:76:9C:5A:22:D0:6C:DD:0A
   Signature Algorithm: ecdsa-with-SHA256
       30:44:02:20:47:83:1b:75:c3:8a:f8:3a:d8:e3:c5:87:29:6b:
       3a:ee:62:f7:d8:4f:ac:ee:e4:59:46:7d:09:08:29:33:1c:e8:
       02:20:0a:9f:a5:01:4f:e6:93:76:59:92:7c:1b:d4:48:00:db:
       c5:31:b6:7f:e2:03:f2:3c:4d:67:30:6d:70:aa:b8:53

Using the Root CA

Now that the Root CA has been verified on the PSD and downloaded, we need to use it to verify the certificate chain so that we can trust the information we receive. Do this with the following steps:

1. Retrieve Certificate Chain: Using your API Operator, we will have a certificate chain endpoint that allows you to verify incoming information.

   1. The certificate chain will be retrieved by an API endpoint - GET /pki/certificate-chain

   2. The first certificate is signed by the RootCA. The second certificate is signed by the first certificate and so on, creating a chain of trust.

   3. This is workspace specific, so if your organisation has more than one workspace, this will need to be implemented on a per workspace level.

2. Verify the Certificate Chain: Using the SHA-256 and the User ID from previous steps, locally verify that the certificate chain. The chain of trust will then be secured as follows:

   1. PSD is trusted thanks to end to end authentication with the HSM

   2. This means that the Root CA that has been verified with the PSD can be trusted.

   3. This means that the calculated SHA-256 can be trusted.

   4. Which means that the Certificate Chain can be trusted down to the leaf.

   5. Using this, API data can be trusted.

3. READ or GET information: Each time you request information requiring HSM data, it will be signed by the JWS of the leaf certificate of the chain you retrieved above.

4. Use information: This information has now been verified and you can use it in the ways you see fit.

Impacted Endpoints

We are introducing two new endpoints that will allow clients to GET address based data in a secure manner. They will look very similar to previous endpoints that were used to retrieve addresses, but will now be updated to include PKI specific data.

Endpoint 1 - Get an address at a specific index:

• This would allow a client to get a specific address of a UTXO based account.

• By default, you will get Receive address here and not change address. As both could be useful for audit purposes, we will also add a query parameter: ?address_type=receive|change.

• NB: The response will only be the JWT token, but below we provide an example of the details that will be masked by the JWT token.

GET /accounts/{account_id}/addresses/{index}?address_type=receive|change
{
"data":
{
"address": "string",
"derivation_path": "84'/0'/2'/1/23",
"blockchain_name": "bitcoin",
},
"jwt_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZGRyZXNzIjoic3RyaW5nIiwiZGVyaXZhdGlvbl9wYXRoIjoiODQnLzAnLzInLzEvMjMiLCJibG9ja2NoYWluX25hbWUiOiJiaXRjb2luIiwiaWF0IjoxNzQxNzc1Mzg1fQ.yAL3znC6XI8GQZPTPkVZa7Kjap6s6w9HKYCI5yRIx23dnnZIg7siMtdksEC-wHyjMK2fQRxXdc6Wow3LKMxIHw"
}

Endpoint 2 - Get an address for non-UTXO based account:

• Here, using a specific index does not make sense when retrieving account address, so the endpoint and response would look as follows:

• NB: The response will only be the JWT token, but below we provide an example of the details that will be masked by the JWT token.

GET /accounts/{account_id}/address
{
"data":
{
"address": "string",
"derivation_path": "44'/60'/7'/0/0",
"blockchain_name": "ethereum",
},
"jwt_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZGRyZXNzIjoic3RyaW5nIiwiZGVyaXZhdGlvbl9wYXRoIjoiODQnLzAnLzInLzEvMjMiLCJibG9ja2NoYWluX25hbWUiOiJiaXRjb2luIiwiaWF0IjoxNzQxNzc1Mzg1fQ.yAL3znC6XI8GQZPTPkVZa7Kjap6s6w9HKYCI5yRIx23dnnZIg7siMtdksEC-wHyjMK2fQRxXdc6Wow3LKMxIHw"
}