Upload and Retrieve the Root Certificate

reference

deprecated

The REST API can be used to upload and retrieve the cluster’s root certificate. It can also be used to retrieve information on the cluster, by referencing a copy of the root certificate. These methods are deprecated in Couchbase Server Version 7.1.

Http Methods and URIs

The APIs listed below for uploading and retrieving the cluster’s root certificate are deprecated. Users of Couchbase Server Version 7.1+ should use instead the APIs described in Certificate Management API.

POST /controller/uploadClusterCA

POST /settings/security/allowNonLocalCACertUpload

GET /settings/security/allowNonLocalCACertUpload

GET /pools/default/certificate

Description

The POST method and /controller/uploadClusterCA URI (which are deprecated in 7.1) upload an appropriately configured certificate to the cluster, so that it becomes the root certificate for the cluster. Either the Full Admin or the Security Admin role is required. The certificate must be specified as binary data, in a location on the filesystem, for successful upload to occur. For security reasons, in versions 7.1 and after, by default, this method and URI can be used on localhost only (see Responses, below, for the associated error message). However, this default setting can be changed, by means of the POST method and /settings/security/allowNonLocalCACertUpload URI, with the -d false flag: this also can be used on localhost only. The status of the current setting can be retrieved with the GET method and /settings/security/allowNonLocalCACertUpload URI. See Configure On-the-Wire Security, for more information.

The GET method and /pools/default/certificate URI are deprecated in 7.1. After the cluster has been upgraded to 7.1, they continue to return the most recent certificate uploaded by means of the deprecated API POST /controller/uploadClusterCA, until at least one new root certificate is uploaded using the new, 7.1 API POST /node/controller/loadTrustedCAs (as described in Load Root Certificates): following which they always return 400 Bad Request, with the message this API is disabled, please use GET /pools/default/trustedCAs — see Get Root Certificates, for details. This call is authorized for all Couchbase Server roles.

Curl Syntax

The curl syntax for each call is as follows:

curl -X POST
  --data-binary "@./ca.pem"
  http://<ip-address-or-host-name>:8091/controller/uploadClusterCA
  -u <username>:<password>

curl -X POST
  http://<ip-address-or-host-name>:8091/settings/security/allowNonLocalCACertUpload
  -d <true | false>
  -u <username>:<password>

curl -X GET
  http://<ip-address-or-host-name>:8091/settings/security/allowNonLocalCACertUpload
  -u <username>:<password>

curl -X GET
  http://<ip-address-or-domain-name>:8091/pools/default/certificate
  -u <username>:<password>

The certificate specified for upload to the deprecated POST method must be an appropriately configured binary, accessible by means of the given path. The certificate must be named ca.pem.

The certificate-copy returned by the deprecated GET method and /pools/default/certificate URI should be appropriately saved: for example, with > <certificate-copy-name>, on the local filesystem. Note that if the URI is extended to /pools/default/certificate?extended=true, an object is returned, rather than the raw, pem-encoded certificate-content alone. This object contains the following fields:

type: Whether the certificate was generated by Couchbase Server, or was uploaded by an administrator.
pem: The pem-encoded certificate-content.
subject: the Subject Common Name of the certificate.
expires: Expiration data.
warnings: Warnings, if appropriate.

Responses

For the POST method, success gives 200 OK, and returns the readable text of the uploaded certificate. Additionally, warnings may be displayed — for example, if the root certificate is uploaded (as may be expected) prior to the uploading of corresponding node certificates (whereby the current node certificates have not been signed by the new root), the warning may be as follows: [{"node":"ns_1@127.0.0.1","message":"Certificate is not signed with cluster CA."}]. Failure to authenticate gives 401 Unauthorized. An incorrectly specified URI fails with 404 Object Not Found. Failure to specify an appropriately configured certificate fails with 400 Bad Request and the notification {"error":"Malformed certificate"} (the message Couldn’t read data from file may also be displayed). An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

If GET /pools/default/certificates, which is deprecated in version 7.1, is used on a cluster with more than one root CA, 400 Bad Request is returned, with the following error message: deprecated, please use /pools/default/trustedCAs.

If the POST method and /controller/uploadClusterCA URI (which are deprecated in 7.1) is used from a host other than localhost, 400 Bad Request is returned, with the following error message: API is accessible from localhost only (this behavior can be changed by means of POST /settings/security/allowNonLocalCACertUpload, see documentation for details).

For the GET method and /pools/default/certificate URI, success gives 200 OK, and returns the readable text of the uploaded certificate. Failure to authenticate gives 401 Unauthorized. A malformed URI fails, with 404 Object Not Found. An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

Examples

The following example uploads an appropriately configured root certificate:

curl -v -X POST http://localhost:8091/controller/uploadClusterCA \
--data-binary "@./ca.pem" \
-u Administrator:password

If successful, the call returns 200 OK, and displays the following output:

{"cert":{"type":"uploaded","pem":"-----BEGIN CERTIFICATE-----\nMIIDCzCCAfOgAwIBAgIJ
    .
    .
    .
AH\n-----END CERTIFICATE-----\n","subject":"CN=Couchbase Root CA","expires":"2030-08 22T03:14:49.000Z"},"warnings":[{"node":"ns_1@127.0.0.1","message":"Certificate is not
signed with cluster CA."}]}

The output thus displays in readable form the body of the new root certificate (shown here in truncated form). It also provides, in this case, a warning: indicating that the node certificate for the node is not yet one signed by the new root certificate. This can be remedied by uploadoing an appropriately signed, new node certificate.

The following example retrieves the current root certificate:

curl -v -X GET http://10.143.201.101:8091/pools/default/certificate \
-u Administrator:password > cert-copy

If successful, this returns 200 OK, with a copy of the current root certificate. This can be inspected at the command line, with a tool such as more. Note that success only occurs if the cluster has at most one root CA: if the cluster has more than one root CA, 400 Bad Request is returned, with the following error message: deprecated, please use /pools/default/trustedCAs.