How to Create Multiple Credentials with beame-sdk

February 26th, 2017 Development Notes

Understanding the Network’s Credential Hierarchy

How to Create Multiple Credentials with beame-sdk


The credentialing system allows you to create an infinite number of cryptographic identities (publicly trusted TLS certificates), divide them into logical subgroups and delegate the authorization process downstream. These credentials can be used for building trust between different system components, such as servers, mobile devices, IoT devices, and end-users. These logical subdivisions allow the creation of an application-specific virtual private encrypted network, irrespective of how systems are connected. They grant the correct permissions to the appropriate user.

General Principles and Definitions

The network graph can grow infinitely both in depth and in width. Let’s consider the following diagram, (Figure 1: Understanding Credential Structure).

Figure 1: Understanding the Credential HierarchyFigure 1- Understanding the Credential Hierarchy - Figure 1- Understanding the Credential Hierarchy

Each one of the nodes in the diagram represents a Cryptographic Identity (beame-crypto-ID, or Crypto-ID). A Crypto-ID is comprised of a fully qualified domain name (FQDN), a publicly trusted TLS certificate (signed by the CA and authorized by its parent), a matching private key, blockchain ledger, and a proxy service. provides the authorization for the creation of L0 with a token during the initial provisioning process. Only can create L0 class credentials. All the remaining nodes in the aforementioned diagram are created by their parents.

This means that L1A.L0 and L1B.L0 are created by using the L0 class credential. The creation of the authorization for creation of credentials such as L1A.L0 and L1B.L0 require the possession of the private key used to create the L0 credential. The private key is always generated by the target device. can never generate or see private cryptographic material.

The process of credential creation can happen in two ways.

  1. Use of the L0 Crypto-ID as a client TLS certificate. In this case, the new credential will be created on the same machine where L0 is present.  This obviously makes transfer of creds in a secure manner to another device problematic, because the private key for the newly created cred, is generated on the same machine which has the private key for parent.
  2. To address the need of generating the keys on the target device, there an option to form an authorization token, signed by the parent node and sending that token to beame, along with a signed statement (public key signed with a private key), which is similar to a CSR.  The outline of the process is as follows:
    1. Generate a private key, and derive a public key
    2. Generate a certificate request
    3. Add the authToken to the http header as “X-BeameAuthToken”



         “signedData”: “{

           “created_at”: 1486486311,

           “valid_till”: 1486486611,

           “data”: “{\”fqdn\”:\”\”}”

         }”,  // PLEASE NOTE THAT signedData MUST be a string*

         “signedBy”: “”,

         “signature”: “base64 encoded SHA256RSA signature of signedData”



       “name”: null,

       “email”: null,

       “type”: “RequestWithFqdn”



* Developer Note: The reason why signedData must be sent as a string is because it’s not possible to sign data structures reliably. But you can try, in ideally in Python  or another language that guarantees dictionary keys order.


How is this done in practice:

  1. beame-sdk offers two commands to receive new credentials:

beame.js creds getCreds  [–fqdn fqdn || –regToken token]

beame.js creds getRegToken [–fqdn fqdn] [–name name] [–email email] [–userId userId] [–ttl ttl]

When calling this function with the fqdn it will search for the local credential, and then create an regToken, and submit the request to beame and save the newly received creds into the BeameStore.


To create additional credentials, first create token (getRegToken) on the machine that already has creds  and then call getCreds on the target machine.  The newly created credentials, are going to be created under the beame-id signing the statement.


So what does that mean ?




The chain is evident from the common name. This mean that a parent can trust its children, and children can recognize parents (know who is your daddy).

The next reasonable question is how can trust be established between siblings, and grandparents and cousins? We will describe in another document called Building Cryptographic Trust.


Recent Posts

Private cloud is easy

PKI based identity on a blockchain

Insta-SSL as a simple way to use RDP / VNC / SSH into LANs

VMs, Docker and vs NSA

x.509 based identity, OS level or dedicated application?