Load Root Certificates

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

    Http Method and URI

    POST /node/controller/loadTrustedCAs

    Description

    Loads trusted CA (or root) certificates that reside on the accessed node into the Couchbase-Server cluster. All loaded CA certificates can be accessed by all nodes. Loaded 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 CA 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

    New, trusted CA 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.

    See Also

    An overview of certificate management is provided in Certificates. Steps for certificate creation are provided in Configure Server Certificates and Configure Client Certificates.