Upload and Retrieve the Root Certificate
- 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
.
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.