Session Certificates

You can configure a dynamic network to use session certificates when sending messages. This requires additional steps when onboarding an MGM Membership Group Manager. May also be referred to as the Network Manager. It is a virtual node and Corda identity that acts as a central registrar for group membership. or member Corda identity that has been granted admission to a membership group. Synonym for a virtual node or group member. into the dynamic network.

Generate a CSR

After creating the MGM or member session key pair, but before building the registration context, generate a CSR Certificate Signing Request. This is a specially formatted encrypted message sent from a Secure Sockets Layer (SSL) digital certificate applicant to a certificate authority (CA). The CSR validates the information the CA requires to issue a certificate. for the session certificate by running the following command, replacing X500_NAME with the X.500 A series of international standards defining a global directory service protocol for computer networks. It provides a structured framework for storing, accessing, and managing information about network resources and users in a hierarchical and distributed manner. name of the MGM or member:

curl --fail-with-body -s -S -k -u $REST_API_USER:$REST_API_PASSWORD  -X POST -H "Content-Type: application/json" -d '{"x500Name": "'$X500_NAME'"}' $REST_API_URL"/certificates/"$HOLDING_ID/$SESSION_KEY_ID > $WORK_DIR/request.csr

Similarly to the TLS Transport Layer Security. A protocol that establishes an encrypted session between two computers on the Internet. certificate, the CSR can be processed to issue a certificate using a CA Certificate Authority. The holders of a PKI trust root that can issue certificates to customers. chosen by the MGM operator. The CA trustroot for session certificates should be configured during the MGM onboarding.

Once you have a certificate based on the CSR exported from Corda issued by the CA, you must upload the certificate chain to the Corda cluster. To upload the certificate chain, run:

curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT  -F certificate=@/tmp/ca/request/certificate.pem -F alias=session-certificate $REST_API_URL/certificates/vnode/$HOLDING_ID/p2p-session

You can optionally omit the root certificate. If revocation is enabled and the root certificate does not have a CRL or OSCP endpoint, you must omit the root certificate.

Revocation Checks

If session certificates are used, revocation checks In the context of X.509 certificates, revocation checks refer to the process of verifying if a digital certificate is still valid and has not been revoked by the issuing Certificate Authority (CA). are performed by the P2P Gateway. As a result, the P2P Gateway’s firewall zone must be configured to allow access to the certificate’s online certificate status protocol (OSCP) and/or Certificate Revocation List (CRL) endpoint.

If the CA has not been configured with revocation, you can disable revocation checks. By default, revocation checks are enabled. To disable revocation checks, do the following:

1. Retrieve the current P2P link manager Establishes end-to-end secure sessions for virtual nodes to communicate over. configuration version:

   curl -k -u $REST_API_USER:$REST_API_PASSWORD -X GET $REST_API_URL/config/corda.p2p.linkManager
   

2. Save the displayed version number from the response as a variable:

   export CONFIG_VERSION=<configuration-version>
   

3. Send the following request to disable revocation checks for the specified P2P link manager:

   curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT -d '{"section":"corda.p2p.linkManager", "version":"'$CONFIG_VERSION'", "config": { "revocationCheck": { "mode": "OFF" } }, "schemaVersion": {"major": 1, "minor": 0}}' $REST_API_URL"/config"
   

Build Registration Context for MGM Registration

If using session certificates, make the following changes to the MGM registration context:

1. Add an extra JSON field corda.group.trustroot.session.0 with the truststore of the CA to the registration context (similar to corda.group.trustroot.tls.0).
2. Set the JSON field corda.group.pki.session to "Standard" instead of "NoPKI".

Configure Virtual Node as Network Participant

If using session certificates, you must also add the sessionCertificateChainAlias JSON field to the network setup REST request. For example:

curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT -d '{"p2pTlsCertificateChainAlias": "p2p-tls-cert", "useClusterLevelTlsCertificateAndKey": true, "sessionKeysAndCertificates": [{"sessionKeyId": "'$SESSION_KEY_ID'", "sessionCertificateChainAlias": "session-certificate", "preferred": true}]}' $REST_API_URL/network/setup/$HOLDING_ID