Obtaining Certificates
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 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 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:
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 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"
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.