Organizational Identity
A Membership is an organization’s representation within a consortium and serves as the parent resource for deployed nodes and services. Memberships are in effect an “asserted identity” and can be underpinned with digital certificates for trustworthy and authoritative identification. An organization can have one or more memberships, whether for delineation of inter-organizational departments or for the proxied management of resources on behalf of fellow organizations.
The Importance of Enterprise Identity
Identity is a critical tenet of any enterprise-grade blockchain network. In the public permission-less networks participants can transact anonymously and are only identifiable by an account or signing address. This is fine for peer to peer cryptocurrency transactions, however, in private permission-based orchestrations, there need to be robust mechanisms for authoritative identification that maps back to real world trust paradigms. This is particularly important for financial use cases where strict regulations exist around AML (anti money laundering) and KYC (know your customer) compliance.
Fellow members of the business network need a shared framework to definitively identify their counterparts and issue their own attestations on asserted identities. Kaleido addresses this requirement with the well-known Public Key Infrastructure (PKI) scheme, whereby any organization participating in the consortium can underpin their memberships with a properly-signed digital x509 certificate. As such, the rest of the business network can download, parse and inspect the certificate chain to ensure that the asserted identity is vouched for by a reputable certificate authority.
Kaleido takes this enterprise identity mandate a step further by offering the ability to bind digital certificates with Ethereum signing accounts and map the relationship within a smart contract. By doing so, transaction objects can be signed with user-controlled private keys and deterministically mapped back to the trusted certificate chain. This brings enterprise identity to both the network and blockchain layers and is critical for scenarios where auditability and transparency is required.
Confirming your Identity
Kaleido allows for an organization’s asserted identity (i.e. membership) in a consortium to be underpinned with a digital x509 certificate for authoritative identification. To confirm an asserted identity, follow these instructions:
- Navigate to your consortium home page
- Click the dropdown next to one of your memberships
- Select the Confirm Identity option
This will open up the Identity Panel and expose two options for certificate generation/upload: Self-Signed or Externally Signed
The console will guide you through the steps for each approach and link out to the appropriate documentation where necessary.
Obtaining a Kaleido-Compliant x509 Certificate
Kaleido employs the well known Public Key Infrastructure (PKI) cryptographic scheme as a mechanism for enhancing identity and trust within a business consortium. Via common PKI techniques, an asserted organizational identity (i.e. membership) can be mapped to an uploaded digital certificate and then verified by the fellow members of the consortium prior to transacting. This document will explore one potential approach to generating a public/private key pair and a Kaleido-compliant x509 certificate via a certificate signing request (CSR). Kaleido enforces no requirements around curves, hashing algorithms or certificate roots; the only mandate is a properly formatted Common Name (CN) field in the resulting certificate. All configurations can and should be implemented in accordance with your organizational policies.
The below example uses a NIST approved ECDSA – secp384r1 – for key generation, and self-signs the certificate request with the locally generated private key. The key pair used to sign the asserted identity is independent of the key pairs used in the ID Registry Service, which leverage the core Ethereum curve – secp256k1 – to generate Ethereum account addresses and their accompanying private keys. While self-signing is not explicitly prohibited and is useful for sandbox/developmental environments, in a production scenario fellow consortia members are unlikely to validate an uploaded identity not derived from a trusted authority. You are strongly recommended to send your properly formatted certificate signing request (CSR) to either your in-house CA or a reputable external service.
Listed below are the Kaleido-compatible elliptic curve names and their aliases for ECDSA: secp256k1, secp256r1, P-256, prime256v1, secp384r1, P-384
Create a Private Key
The below is a command line prompt using the openssl library and ECDSA secp384r1. The algorithm and bit size should be adjusted for organizational compliance:
This outputs a private key aptly named private.key in the present working directory.
Assemble the CSR
The Certificate Signing Request (CSR) is the most important component and the only piece with a Kaleido requirement. Specifically, the Kaleido Unique Identifier from the Identify Yourself panel must be inserted as the Common Name (CN) within the Distinguished Name (DN) of the certificate. This string is comprised of the Organizational ID associated with the membership, as well as a nonce for the asserted identity. Kaleido will parse the uploaded certificate and check that the CN field identically matches the supplied unique identifier. This Kaleido Unique Identifier appears at the top of the certificate upload panel and exposes the following syntax – orgID-nonce-membershipName.
The private key specified in the request is used to generate a corresponding public key, and to sign the object. You can optionally choose to specify a hashing algorithm for the signature (e.g. sha256); this is recommended.
The following CSR takes an example Kaleido Unique Identifier of u0mvtabcde-44urk12345-orgA and passes in the DN information as a single string.
# Full request
openssl req -new -key private.key -out kaleido.csr -sha256 -subj "/C=US/ST=NC/L=Raleigh/O=Kaleido/OU=Engineering/CN=u0mvtabcde-44urk12345-orgA"</code></pre>
To interactively construct the CSR, withhold the -subj field and the ensuing string:
# interactive request; you will sequentially enter values for the various DN fields
openssl req -new -key private.key -out kaleido.csr -sha256
Self Sign the CSR
IMPORTANT: This is NOT recommended for production. You should send the CSR to your in house CA or to a reputable external authority. This is simply a demonstration of creating an x509 certificate with a compliant CN.
The below command uses the same local private key to sign the x509 certificate over sha256. This is a suitable exercise for developmental rinse/wash/repeat scenarios, but self signed certs should not be uploaded for identity assertion in a production or pre-prod environment. Kaleido issues no restrictions on the signing techniques for proper Certificate Authorities, as the uploaded certificate is an off-chain object not associated with the blockchain protocol layer. However, it is recommended to target CAs that use secure key storage practices (e.g. HSMs for master key) and utilize strong collision-resistant hashing algorithms.
The outputted x509 certificate is what you will you upload to Kaleido. If the CN matches the expected string, the identity will be verified. Fellow participants of the consortium will then be able to inspect the human readable CA chain and pass their own judgement.
Parse the x509 Cert
This will convert the base64 encoded certificate content to human readable text and allow you to inspect the cert for properly formatted Distinguished Name content, namely the CN field.