A newer version of this documentation is available.

View Latest

Regenerate All Certificates

  • reference
    +
    The REST API can be used to regenerate the cluster’s root and node certificates.

    Http Method and URI

    POST /controller/regenerateCertificate

    Description

    When a one-node Couchbase Cluster is first created, a default root certificate for the cluster is automatically provided: additionally, a default node certificate, signed by the root certificate, is automatically provided for the node. Subsequently, as further nodes are added to the cluster, each node is automatically assigned its own, default node certificate, signed by the root certificate.

    These default root and node certificates support pre-production certificate-based authentication, including that required by node-to-node encryption. However, being generated by the cluster itself, they provide only minimal security, and are not appropriate for production purposes.

    Therefore, in preparation for a cluster’s full, production deployment, a root certificate provided by an acknowledged authority should be uploaded to the cluster; and, on each node, an individual node certificate, signed by the new root, should be uploaded.

    Should problems occur during or subsequent to the deployment of these new certificates, all certificates can be regenerated, using the POST method with the /controller/regenerateCertificate URI: this substitutes a default root certificate and, on each node, a default node certificate, for those uploaded by the administrator.

    Note that on Couchbase Server Version 7.1 and later, when regeneration is performed, no trusted root certificate is removed from the cluster: all trusted root certificates remain in the cluster’s trust store; and can be removed manually, as appropriate. For information, see Using Multiple Root Certificates.

    To regenerate certificates, the administrator must have either the Full Admin or the Local Admin Security Admin role.

    Curl Syntax

    The curl syntax is as follows:

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

    Responses

    Success returns 200 OK and the text of the regenerated, default root certificate. An incorrect username-password combination fails with 401 Unauthorized. An incorrectly specified 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. An attempt to regenerate certificates without the Full Admin, the Local User Security Admin, or the External User Security Admin role fails with either 401 Unauthorized or 403 Forbidden with a notification such as "message":"Forbidden. User needs one of the following permissions","permissions":["cluster.admin.security!write"].

    Example

    The following call regenerates the root and node certificates for the cluster of which node 10.143.201.101 is a member:

    curl -v -X POST http://10.143.201.101:8091/controller/regenerateCertificate \
    -u Administrator:password

    If the call succeeds, the text of the regenerated, default root certificate is returned. For example:

    -----BEGIN CERTIFICATE-----
    MIIDAjCCAeqgAwIBAgIIFi4nc7UqQFwwDQYJKoZIhvcNAQELBQAwJDEiMCAGA1UE
    AxMZQ291Y2hiYXNlIFNlcnZlciAyOGIzZDQ2MTAeFw0xMzAxMDEwMDAwMDBaFw00
    OTEyMzEyMzU5NTlaMCQxIjAgBgNVBAMTGUNvdWNoYmFzZSBTZXJ2ZXIgMjhiM2Q0
    NjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCYtqTjsfzaIFNotdPK
    APuel4oi8y/0TIL2g/8Fc0lcetKtdyGuTajXJ0VsD+M8H1kNbMQuIlxKG03OKxc3
    eg/4mUZZOhLFvw0XWdhi/NwmoylHrUhLNeS1pt2TlA0+54acpOzOb3STmjR8DIz1
    mz69QfMruTvoSc2RY4ACCS/EHzAmshQvsOmKje3aseyYlQWZvwm9ApEdNnlPDTdp
    MQcBvUcVsLs3cAC5Ri2YltiOWUpU8U98ySkphvbtp7pTGbqPFL0A3m3pnDeFKDU4
    3KwZks3uAX2paZoLfWRH37JkUeA1bbaIfMWJ0Bsx+QbZhdDFWPou/UIcq5eFpJlS
    7nSLAgMBAAGjODA2MA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggrBgEFBQcD
    ATAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQAH4uM0YKyPpYwD
    UUT340DRSUjDUZ/DcdilMJCagQucQHYwU+sLrlOLOSidbycQi9blSLHmNOjPQWGC
    v2RIJg37SCFUthUSS60zJ2tJdF0mttcbRQVczJTZFdh3uqmWtTCoYfD9lPZre5Gb
    kfvnGKawoeDNDpJXTnu463pCOxG+d+rM+rGFngocHMa29Wiev8juddH9baekVBmh
    mRRQZJFB58xLUykykSVby6V9jy4OoRTOfhKvCGaG2vpku6LubZmbxvTt/Le5hXUz
    /A04ULozlHP/37sEvmfdJ38O3vbbiYMOcOSuChoTThnFKXkPciivrPbntwXaQPmL
    VAloPTuo
    -----END CERTIFICATE-----

    The root and node certificates for the cluster have all now been restored to default values.

    See Also

    Information on uploading and retrieving root and node certificates with the REST API is provided in Upload and Retrieve the Root Certificate and Upload and Retrieve a Node Certificate, respectively. A general introduction to certificates is provided in Certificates. Routines for generating and deploying server and client certificates are provided in Configure Server Certificates and Configure Client Certificates, respectively.