Load Root Certificates

Trusted CA (or 'root') certificates can be loaded into the trust store of the Couchbase-Server cluster; in order to provide authority to the cluster’s nodes, and to authenticate clients' access-attempts. Intermediate certificates can also be loaded into the trust store.

HTTP Method and URI

POST /node/controller/loadTrustedCAs

Description

Loads trusted certificates into the Couchbase-Server trust store. All loaded certificates can be accessed by all nodes. Loaded CA (or root) certificates can be used to provide authority to the cluster’s nodes, and can be used to authenticate clients' access-attempts.

The Full Admin, the Local User Security Admin, or the External User Security Admin role is required.

Note the following:

Files to be loaded must reside in the inbox/CA directory. (Note that the loading process uses this directory in order to ensure security.)
Each file may contain several certificates.
Certificates must be in pem format.
Any file whose name starts with . is ignored.

Note also that use of multiple root certificates is not possible prior to Couchbase Server Version 7.1. The POST /node/controller/loadTrustedCAs method and URI can therefore only be used on clusters all of whose nodes are running at least version 7.1: it cannot be used if any cluster node is running a version prior to 7.1.

Prior to being loaded, for security reasons, the trusted certificates must be copied into the folder inbox/CA; which has been manually created by the administrator on a given node, in the appropriate platform-specific location. The node should be the one that is to be referenced in the POST /node/controller/loadTrustedCAs call. The platform-specific location must be one of the following:

Operating System	Folder Location
Linux	/opt/couchbase/var/lib/couchbase/inbox/CA
Windows	C:\Program Files\couchbase\server\var\lib\couchbase\inbox\CA
Mac OS X	/Applications/Couchbase Server.app/Contents/Resources/couchbase-core/var/lib/couchbase/inbox/CA

Operating System

Folder Location

Linux

/opt/couchbase/var/lib/couchbase/inbox/CA

Windows

C:\Program Files\couchbase\server\var\lib\couchbase\inbox\CA

Mac OS X

/Applications/Couchbase Server.app/Contents/Resources/couchbase-core/var/lib/couchbase/inbox/CA

New, trusted certificates can be loaded at any time, from any node. Only the certificates within the inbox/CA folder of the specified node are loaded: therefore, if multiple certificates are to be loaded, and these reside on multiple nodes, a separate call must be used for each node.

Curl Syntax

The curl syntax is as follows:

curl -X POST http://<ip-address-or-domain-name>:8091/node/controller/loadTrustedCAs
 -u <username>:<password>

Responses

Success returns 200 OK and a JSON array, each of whose members is an object whose key-value pairs provide information on a trusted CA certificate that has been recently loaded on the current node — this may not be the complete list of certificates that have been and remain loaded for the cluster. If no certificates are available to be loaded (either because all certificates in inbox/CA have already been loaded, or because no certificates were previously copied into inbox/CA), the returned array is empty.

Failure to authenticate returns HTTP/1.1 401 Unauthorized. Authentication with inadequate credentials returns 403 Forbidden, and an error message such as: {"message":"Forbidden. User needs the following permissions","permissions":["cluster.admin.security!write"]}.

A malformed URI returns HTTP/1.1 404 Object Not Found. An incorrect method returns HTTP/1.1 405 Method Not Allowed.

Example

The following example shows the creation of the inbox/CA folders, the copying of a trusted CA certificate into the destination CA folder, and the loading of the certificate by means of the REST API.

sudo mkdir -p /opt/couchbase/var/lib/couchbase/inbox/CA
sudo cp ca.pem /opt/couchbase/var/lib/couchbase/inbox/CA
curl -X POST http://10.144.220.101:8091/node/controller/loadTrustedCAs -u Administrator:password

Formatted, the output appears as follows:

[
  {
    "id": 1,
    "loadTimestamp": "2021-11-22T16:55:50.000Z",
    "subject": "CN=Couchbase Root CA",
    "notBefore": "2021-11-22T16:37:47.000Z",
    "notAfter": "2031-11-20T16:37:47.000Z",
    "type": "uploaded",
    "pem": "-----BEGIN CERTIFICATE-----\nMIIDGTCCAgGgAwIBAgIUZhSikh0Wl3wxgKtEqgmi2NDBZKswDQYJKoZIhvcNAQEL\nBQAwHDEaMBgGA1UEAwwRQ291Y2hiYXNlIFJvb3QgQ0EwHhcNMjExMTIyMTYzNzQ3\nWhcNMzExMTIwMTYzNzQ3WjAcMRowGAYDVQQDDBFDb3VjaGJhc2UgUm9vdCBDQTCC\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMso+6juWKMLD7HDuoiGDGeU\nldjh6bZEkXsYAmFEziZnreEONoGr3ZS1MtOro2F6dPM6QDKkSlhG7DogYGz96xPG\niLWWKuMUhhbqVkzjScYhg4FEsm356j8zVt6orn4D6BaT3RKaYP+SQP802t7/Jv6Y\nGjIl9+HUDMiwJ0qx5kci208mZacjrI/iw05f89IgB9mj4l81nb2DJXcuyfZFmYYV\nx8NcxbIWbfCFZDlftWNDkyyrjM1nM8MgSxXJLFCLLLRyYKfiS4h9ikzUM87hPXC+\ntj1Lpnbq5RQKAUHTaR7Sx9pWB/iB4tv3+Rk6lpDSLox5E36DxaTqJdgYnvonyVkC\nAwEAAaNTMFEwHQYDVR0OBBYEFIqaO4ZZnPAI9xfup7MeNB77+j9cMB8GA1UdIwQY\nMBaAFIqaO4ZZnPAI9xfup7MeNB77+j9cMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZI\nhvcNAQELBQADggEBAMgN7PZlf88L3YV5pBQQb+t4p59Gagsw8Rt8z0XNTlVAPqd5\nkCU3KRJvf1AioQHGcvoKlAL9lIOzbeSmxUcWxg9UV5lPtDkIIISMFBajYDdwKGgy\nu0T9FVpwbXEM9hfLr0aDCQwWCw7u8j/hPTNMo0vqaH9ApS0Y/CR/bLR9PBhorR7G\naCOj4Nd5yrptbZjgvctvE1QxzulEOcndXMwUipV+LluO0AbtCym+07O0oScT5g5A\n9HC3NIyKRMvqQjzSjz/ddahdL3jBgImN+dSJDGQjCL/gl5jcuACHKtHcdoqmIGmZ\nRDy/b+3vQ/g1+iwfq+m6m0pZHIzilIoHM8jMzjI=\n-----END CERTIFICATE-----\n\n",
    "loadHost": "10.144.220.101",
    "loadFile": "/opt/couchbase/var/lib/couchbase/inbox/CA/ca.pem"
  }
]

The output thus confirms that a single trusted certificate, with the common name CN=Couchbase Root CA, was loaded on host 10.144.220.101, from file-location /opt/couchbase/var/lib/couchbase/inbox/CA/ca.pem, at the time stamped 2021-11-22T16:55:50.000Z.