Certificate management

cert-manager

By default Paladin uses the cert-manager operator to generate self signed certificates for each node. These certificates are published to the registry, and used for mTLS when Paladin nodes are communicating with each other over GRPC

Custom certificate manager

customnet installations may use certificates generated by a custom certificate manager provided the following requirements are met:

• the key pair and certificate authority (if available) are made available in a kubernetes.io/tls Kubernetes secret
• the common name of the certificate is the node name
• the node endpoint that is published in the registry is a subject alternative name in the certificate

The secret is provided in the transports section for the node in the helm values file.

paladinNodes:
  - name: "node1"
    transports:
    - name: grpc
      tls:
        secretName: node1-custom-certs  

Certificate rotation

If you are rotating certificates which the Paladin operator has generated via cert-manager, follow the steps under Rotate certificates generated with cert-manager.

If you are rotating certificates from a custom certificate manager, follow their instructions to rotate certificates.

Once the certificates have been rotated, or if you are updating the registry with certificates which have already rotated, follow the steps under Update the registry

N.B. In the period of time between the certificates rotating and the registry being updated, nodes will be unable to communicate with each other.

Rotate certificates generated with cert-manager

1. Install the cmctl command line tool
2. List all the certificates generated for Paladin nodes

   kubectl get certificate -l app.kubernetes.io/part-of=paladin
   

   NAME                 READY   SECRET               AGE
   paladin-node1-mtls   True    paladin-node1-mtls   21h
   paladin-node2-mtls   True    paladin-node2-mtls   21h
   paladin-node3-mtls   True    paladin-node3-mtls   21h
   

3. Use cmctl to renew all the certificates

   cmctl renew paladin-node1-mtls --namespace paladin
   cmctl renew paladin-node2-mtls --namespace paladin
   cmctl renew paladin-node3-mtls --namespace paladin
   

4. Wait for all the Paladin node pods to roll and pick up the new certificates

   kubectl get pods -l app=paladin -w
   

   
   
   See example output

   NAME              READY   STATUS    RESTARTS   AGE
   paladin-node1-0   2/2     Running   0          21h
   paladin-node2-0   2/2     Running   0          21h
   paladin-node3-0   2/2     Running   0          21h
   paladin-node1-0   2/2     Terminating   0          21h
   paladin-node2-0   2/2     Terminating   0          21h
   paladin-node3-0   2/2     Terminating   0          21h
   paladin-node2-0   1/2     Terminating   0          21h
   paladin-node1-0   0/2     Completed     0          21h
   paladin-node2-0   0/2     Completed     0          21h
   paladin-node3-0   0/2     Completed     0          21h
   paladin-node1-0   0/2     Completed     0          21h
   paladin-node1-0   0/2     Completed     0          21h
   paladin-node3-0   0/2     Completed     0          21h
   paladin-node1-0   0/2     Pending       0          0s
   paladin-node3-0   0/2     Completed     0          21h
   paladin-node1-0   0/2     Pending       0          0s
   paladin-node3-0   0/2     Pending       0          0s
   paladin-node2-0   0/2     Completed     0          21h
   paladin-node3-0   0/2     Pending       0          0s
   paladin-node2-0   0/2     Completed     0          21h
   paladin-node2-0   0/2     Pending       0          0s
   paladin-node2-0   0/2     Pending       0          0s
   paladin-node1-0   0/2     ContainerCreating   0          1s
   paladin-node3-0   0/2     ContainerCreating   0          1s
   paladin-node2-0   0/2     ContainerCreating   0          0s
   paladin-node1-0   1/2     Running             0          7s
   paladin-node3-0   1/2     Running             0          8s
   paladin-node2-0   1/2     Running             0          7s
   paladin-node1-0   2/2     Running             0          16s
   paladin-node3-0   2/2     Running             0          16s
   paladin-node2-0   2/2     Running             0          16s
   

Update the registry

These steps need to be repeated for every Paladin node

1. Get the address of the registry

   kubectl get registry
   

   NAME           TYPE   STATUS      CONTRACT
   evm-registry   evm    Available   0x20627c59237c42aeefff4445519881d6dd9c8727
   

2. Get the identity hash of the node in the registry
3. Get the local transport details

   curl http://localhost:31548 --header 'Content-Type: application/json' \
   --data '{
       "jsonrpc": "2.0",
       "id": "1",
       "method": "transport_localTransportDetails",
       "params": ["grpc"]
   }'
   

   N.B. it is important to ensure that the Paladin node pod has rolled to pick up the new certificates so that the response from this RPC call is accurate

4. Submit a transaction to the node to update the transport details, filling in the node name as well as the registry address, identity hash and local transport details from the above steps.

   curl --location http://localhost:31548 --header 'Content-Type: application/json' \
   --data '{
       "jsonrpc": "2.0",
       "id": "1",
       "method": "ptx_sendTransaction",
       "params": [
           {
               "type": "public",
               "function": "setIdentityProperty",
               "from": "registry.<node name>",
               "to": "<registry address>",
               "data": {
                   "name": "transport.grpc",
                   "identityHash": "<identity hash>",
                   "value": "<local transport details>"
               },
               "abi": [{
                   "inputs": [
                       {
                           "internalType": "bytes32",
                           "name": "identityHash",
                           "type": "bytes32"
                       },
                       {
                           "internalType": "string",
                           "name": "name",
                           "type": "string"
                       },
                       {
                           "internalType": "string",
                           "name": "value",
                           "type": "string"
                       }
                   ],
                   "name": "setIdentityProperty",
                   "outputs": [],
                   "stateMutability": "nonpayable",
                   "type": "function"
               }]
           }
       ]
   }'