Mutual TLS Connections

Corda 5 uses TLS Transport Layer Security. A protocol that establishes an encrypted session between two computers on the Internet. to secure a connection between two clusters. While establishing a TLS connection between the gateways of two clusters, the server gateway sends its certificate to the client gateway. The client gateway verifies the server certificate using its trust root certificate. In mutual TLS, in addition to the client verifying the server certificate, the server gateway also requests the client gateway send a client certificate and verifies that it is using its trust root certificate.

As the gateway manages the TLS connections for an entire cluster A complete set of worker processes. Clusters require a fully functioning virtual node infrastructure. , the TLS mode (mutual or one-way) is defined in the gateway configuration and applies to the entire cluster. As a result, any group hosted in a mutual TLS cluster must be a mutual TLS group, and all its members Corda identity that has been granted admission to a membership group. Synonym for a virtual node or group member. must be hosted on a mutual TLS cluster.

The server gateway has a set of accepted certificate subjects. As part of the client certificate verification, the server rejects a connection with a certificate that has a subject not specified in the allowed list. Before a member can register with a cluster that is configured with mutual TLS, you must add the certificate subject of that member to the allowed list of the 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. . Once a member is successfully onboarded, the MGM distributes the certificate subject of the member to all other members in the group. The gateway in each member cluster uses this to accept TLS connections from any onboarded member.

Modify the Cluster Configurations

To configure a cluster to use mutual TLS, you must set the sslConfig.tlsType flag in the corda.p2p.gateway configuration section to MUTUAL for the following:

• The MGM cluster before registering the MGM.
• All member clusters before uploading the CPI Corda Package Installer. A signed ZIP/JAR combination of a CPB and a Group Policy File that defines not only the application code that a virtual node will run, but also the details of the MGM with which to register, and the details of network PKI requirements. .

Enable Mutual TLS Using Bash

If using Bash, perform the following steps to enable mutual TLS by configuring the gateway SSL:

1. Retrieve the current gateway configuration version:

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

2. Store the version number from the response:

   export CONFIG_VERSION=<configuration-version>
   

3. Using that version number, send the following request:

   curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT -d '{"section":"corda.p2p.gateway", "version":"'$CONFIG_VERSION'", "config":"{ \"sslConfig\": { \"tlsType\": \"MUTUAL\"  }  }", "schemaVersion": {"major": 1, "minor": 0}}' $REST_API_URL"/config"
   

   This command overwrites the revocation check 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). setting. If you chose to disable revocation checks, use the following command instead:

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

Enable Mutual TLS Using PowerShell

If using PowerShell, perform the following steps to enable mutual TLS by configuring the gateway SSL:

$CONFIG_VERSION = (Invoke-RestMethod -SkipCertificateCheck  -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Uri "$REST_API_URL/config/corda.p2p.gateway").version
Invoke-RestMethod -SkipCertificateCheck  -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Method Put -Uri "$REST_API_URL/config" -Body (ConvertTo-Json -Depth 4 @{
 section = "corda.p2p.gateway"
 version = $CONFIG_VERSION
 config = @{
     sslConfig = @{
         tlsType = "MUTUAL"
     }
 }
 schemaVersion = @{
     major = 1
     minor = 0
 }
})

This command overwrites the revocation check setting. If you chose to disable revocation checks, use the following command instead:

$CONFIG_VERSION = (Invoke-RestMethod -SkipCertificateCheck  -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Uri "$REST_API_URL/config/corda.p2p.gateway").version
Invoke-RestMethod -SkipCertificateCheck  -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Method Put -Uri "$REST_API_URL/config" -Body (ConvertTo-Json -Depth 4 @{
    section = "corda.p2p.gateway"
    version = $CONFIG_VERSION
    config = @{
        sslConfig = @{
            revocationCheck = @{
                mode = "OFF"
            }
            tlsType = "MUTUAL"
        }
    }
    schemaVersion = @{
        major = 1
        minor = 0
    }
})

Set the TLS Type in the MGM Context

To register an MGM in a mutual TLS cluster, you must explicitly set the TLS type in the registration context. That is, the corda.group.tls.type field must be Mutual. If the field is not set, it defaults to one-way TLS. For example:

export REGISTRATION_CONTEXT='{
  "corda.session.keys.0.id": "'$SESSION_KEY_ID'",
  "corda.ecdh.key.id": "'$ECDH_KEY_ID'",
  "corda.group.protocol.registration": "net.corda.membership.impl.registration.dynamic.member.DynamicMemberRegistrationService",
  "corda.group.protocol.synchronisation": "net.corda.membership.impl.synchronisation.MemberSynchronisationServiceImpl",
  "corda.group.protocol.p2p.mode": "Authenticated_Encryption",
  "corda.group.key.session.policy": "Combined",
  "corda.group.pki.session": "NoPKI",
  "corda.group.pki.tls": "Standard",
  "corda.group.tls.type": "Mutual",
  "corda.group.tls.version": "1.3",
  "corda.endpoints.0.connectionURL": "https://'$P2P_GATEWAY_HOST':'$P2P_GATEWAY_PORT'",
  "corda.endpoints.0.protocolVersion": "1",
  "corda.group.trustroot.tls.0" : "'$TLS_CA_CERT'"
}'

Update the MGM Allowed Certificate Subject List

To add a member TLS certificate subject to the MGM allowed list, run the following, where CN=CordaOperator,C=GB,L=London,O=Org is the subject of the TLS certificate created as part of member onboarding

curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT  "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperator,C=GB,L=London,O=Org"

Invoke-RestMethod -SkipCertificateCheck  -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Uri "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperator,C=GB,L=London,O=Org" -Method Put

The allowed-client-certificate-subjects API also supports a DELETE and GET to manage the accepted list of certificates by the MGM. For example:

curl -k -u $REST_API_USER:$REST_API_PASSWORD -X DELETE  "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperatorTwo,C=GB,L=London,O=Org"
curl -k -u $REST_API_USER:$REST_API_PASSWORD -X PUT  "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperatorThree,C=GB,L=London,O=Org"
curl -k -u $REST_API_USER:$REST_API_PASSWORD "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects"

Invoke-RestMethod -SkipCertificateCheck -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Method Delete -Uri "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperatorTwo,C=GB,L=London,O=Org"
Invoke-RestMethod -SkipCertificateCheck -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Method Put -Uri "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects/CN=CordaOperatorThree,C=GB,L=London,O=Org"
Invoke-RestMethod -SkipCertificateCheck -Headers @{Authorization=("Basic {0}" -f $AUTH_INFO)} -Uri "$MGM_API_URL/mgm/$MGM_HOLDING_ID/mutual-tls/allowed-client-certificate-subjects"