diff --git a/modules/introduction/pages/whats-new.adoc b/modules/introduction/pages/whats-new.adoc index 107dd76ac1..0d17f4dc03 100644 --- a/modules/introduction/pages/whats-new.adoc +++ b/modules/introduction/pages/whats-new.adoc @@ -1,6 +1,7 @@ = What's New in Version 7.6 :description: Couchbase is the modern database for enterprise applications. Couchbase Server 7.6 combines the strengths of relational databases with the flexibility, performance, and scale of Couchbase. :page-aliases: security:security-watsnew +:page-toclevels: 2 [abstract] {description} diff --git a/modules/introduction/partials/new-features-76.adoc b/modules/introduction/partials/new-features-76.adoc index 6ef368682f..b4c85e947c 100644 --- a/modules/introduction/partials/new-features-76.adoc +++ b/modules/introduction/partials/new-features-76.adoc @@ -63,7 +63,7 @@ You can migrate buckets while the database continues running. To complete the migration you must trigger a swap rebalance or a graceful failover followed by a full recovery on each node that contains the bucket. See xref:manage:manage-buckets/migrate-bucket.adoc[]. -=== Security +=== Security and Authentication * Security settings now provide additional parameters, for the configuration of Couchbase-Server user-password hashing. See xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security]. @@ -86,6 +86,32 @@ See xref:learn:security/authentication-domains.adoc#saml-authentication[SAML Aut This setting controls low-level network communication options when Couchbase Server securely connects to an LDAP server through intermediate systems such as proxies and firewalls. See xref:manage:manage-security/configure-ldap.adoc#advanced-settings[Advanced Settings] on the xref:manage:manage-security/configure-ldap.adoc[] page for more information about this setting. +* Couchbase Server now supports using Public-Key Cryptography Standard (PKCS) #12 format certificates for node certificates. +This format lets you bundle the node's private key, public key, and certificate chain into a single file. +See xref:learn:security/certificates.adoc#pkcs12[PKCS #12 Certificates for Nodes] for more information. + +* Couchbase Server now supports the X.509 Elliptic Curve Key cipher suites. +Elliptic Curve Key ciphers are less resource-intensive than other cipher suites. +They're useful when communicating with resource-constrained devices such as IoT hardware. +See xref:learn:security/certificates.adoc#private-key-formats[Private Keys] for more information. + +* Couchbase Server no longer supports TLS versions 1.0 and 1.1. +When upgrading to version 7.6 or later, the upgrade process automatically sets `minTLSVersion` to `tlsv1.2` if it's set to `tlsv1` or `tlsv1.1`. +Before you upgrade, be sure all the clients you use support TLS 1.2 or greater. +See xref:learn:security/on-the-wire-security.adoc[] for more information. + +* To prevent https://en.wikipedia.org/wiki/Lucky_Thirteen_attack[LUCKY13 attacks^], Couchbase Server 7.6 removes the following ciphers from the default cipher list: +** TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA +** TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA +** TLS_RSA_WITH_AES_256_CBC_SHA +** TLS_RSA_WITH_AES_128_CBC_SHAa + +* You can now enable alerts for certificate expiration. +When enabled, Couchbase Server alerts you when server, node, or XDCR certificates are within 30 days of expiration. +You can change the alert period via the new `certExpirationDays` alert limit setting. +Couchbase Server sends a second alert when certificates expire. +See xref:learn:security/certificates.adoc#certificate-expiration[Certificate Expiration] for more information. + === Metrics * Couchbase Server has a new service discovery endpoint to help you configure the Prometheus event monitoring system. @@ -95,6 +121,12 @@ See xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[Configure Promethe * Disk usage statistics now include transient files in progress, state files, and configuration files. +=== Index Service + +* You can choose to have the rebalance process move an index's files between nodes instead of rebuilding them from scratch. +This setting improves rebalance performance as moving the files is faster than rebuilding them. +See xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[Index Rebalance Methods] + === Search Service * Couchbase Server 7.6 introduces Vector Search to enable AI integration, semantic search, and the RAG framework. @@ -149,9 +181,9 @@ See xref:learn:data/expiration.adoc[] for more information. * `num_replica` configured for each index can now be found through {sqlpp} statement: `system:indexes` -* The Query service adds cluster-level and node-level parameters to limit the size of explain plans in the completed requests catalog. +* The Query Service adds cluster-level and node-level parameters to limit the size of explain plans in the completed requests catalog. -* The Query service adds support for sequential scans, which enables querying without an index. +* The Query Service adds support for sequential scans, which enables querying without an index. * The node-level and request-level N1QL Feature Control parameters now accept hexadecimal strings or decimal integers. @@ -171,19 +203,13 @@ This integration simplifies Eventing code logic and lets Eventing benefit from t * The Sub-Document MUTATEIN operation allows you to modify only parts of a document instead of the entire document. This Sub-Document operation is faster and more efficient than a full-document operation like REPLACE or UPSERT. -=== Index Service - -* You can choose to have the rebalance process move an index's files between nodes instead of rebuilding them from scratch. -This setting improves rebalance performance as moving the files is faster than rebuilding them. -See xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[Index Rebalance Methods] - === Install & Upgrade * Due to an Erlang compatibility issue, you cannot directly upgrade to Couchbase Server 7.6 from version 6.5 through 7.0. To upgrade a database running one of these earlier versions to 7.6, first upgrade it to Couchbase Server 7.1 or 7.2. See xref:install:upgrade.adoc[] for more information. -=== Community Edition +=== Couchbase Server Community Edition * You can no longer set the `sendStats` to `false` in Couchbase Server Community Edition clusters. You can still set `sendStats` to `false` on Couchbase Server Enterprise Edition clusters. diff --git a/modules/learn/assets/images/security/security_certificates_page.png b/modules/learn/assets/images/security/security_certificates_page.png new file mode 100644 index 0000000000..f04f1dd54d Binary files /dev/null and b/modules/learn/assets/images/security/security_certificates_page.png differ diff --git a/modules/learn/pages/security/certificates.adoc b/modules/learn/pages/security/certificates.adoc index 19ec1a7f5e..0ca98ae4ec 100644 --- a/modules/learn/pages/security/certificates.adoc +++ b/modules/learn/pages/security/certificates.adoc @@ -1,342 +1,378 @@ = Certificates -:description: Couchbase Server supports x.509 certificates for client and server. +:description: Couchbase Server supports using certificates for client and server security and authentication. :page-aliases: security:security-certs-auth,security:security-encryption - +:page-toclevels: 3 [abstract] + {description} [#certificates-in-couchbase] == Certificates and Couchbase Server -Couchbase Server supports the use of x.509 certificates, for clients and servers. -This ensures that: +To maintain security, Couchbase Server can verify the identity of any system it connects to or that tries to connect to it. +This verification ensures that only authorized systems can interact with the database. +By default, Couchbase Server nodes always verifies the identity of other nodes in the cluster. +You can choose to have Couchbase Server also verify the identity of client systems and XDCR clusters. +Couchbase Server verifies the identity of systems using certificates. -* Only approved users, applications, machines, and endpoints have access to system resources. -Consequently, the mechanism can be used by Couchbase SDK clients, to access Couchbase Services; and by source clusters that use XDCR to replicate data to target clusters. +Similarly, you can configure Couchbase Server to identify itself to other systems using certificates. +This use of certificates lets other systems such as clients and XDCR clusters verify the identity of your database. -* Clients can verify the identity of Couchbase Server, thereby ensuring that they are not exchanging data with a rogue entity. +Certificates indicate trust (and therefore identity) by cryptographically signing other certificates. +You use a certificate's private key to sign another certificate. +In this case, the certificate you use to sign another is called a Certificate Authority (CA) or a root certificate. +When you use a CA to sign a certificate, you're indicating you trust the system using certificate. +If Couchbase Server trusts the CA, it can trust a system that identifies itself with a certificate signed by the CA. +You can also use the signed certificate as an intermediate certificate by using its own private key to sign new certificates. +By signing the new certificate, the intermediate certificate extends the trust of the CA to the newly signed certificate. +This series of signings establishes a chain of trust from the CA, through the intermediate certificate, to new certificate. -Full Admin, Local User Security Admin, or External User Security Admin privileges are required, for the management of certificates. +This page provides a general overview of using certificates with Couchbase Server and clients. +It assumes you know the basics of Transport Layer Security (TLS) and certificates. +To learn more about these topics, see the Wikipedia article on https://en.wikipedia.org/wiki/Public_key_certificate[Public key certificate^], and OpenSSL's https://wiki.openssl.org/index.php/Command_Line_Utilities[Command Line Utilities] page. -This page provides a general overview of certificates, and of their management in the context of Couchbase Server. -For step-by-step instructions on certificate creation and deployment, see xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] and xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. +Managing certificates requires Full Admin, Local User Security Admin, or External User Security Admin privileges. -[#certificate-content] -== Certificate Content +For step-by-step instructions for creating and deploying certificate for Couchbase Server and clients, see xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] and xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. -Certificate-based authentication relies on a _Certificate Authority_ (CA), to validate identities and issue certificates. -Each certificate includes: +[#certificate-hierarchies] +=== Couchbase Server's Trust Store -* The name of the entity it identifies. +You tell Couchbase Server which CAs and intermediate certificates to trust by adding them to its trust store. +The trust store is a collection of certificates that's shared cluster-wide--each node can access the certificates in it. +The nodes in the cluster use these certificates to determine whether to trust other nodes during TLS connection negotiation. -* An expiration date. +When a system--another node, or a client or XDCR cluster when configured to connect securely--interacts with a node, it provides its certificate as identification. +The node tries to identify the system by establishing a chain of trust from the system's certificate to a certificate in the trust store. +For example, suppose a client system has a certificate signed by an intermediate certificate which in turn was signed by a CA in the trust store. +In this case, the node finds a chain of trust from the system's certificate, through the intermediate certificate, and to a CA in the trust store. +Therefore, it can trust the identity of the other system. -* The name of the CA that issued the certificate. -* The digital signature either of the issuing CA, or of an intermediate certificate through which the authority of the issuing CA can be traced. +[#server-certificates] +=== Default Certificates -* A public key, which corresponds to the _private_ key that was used to generate the certificate; and which can therefore potentially be used in conjunction with that private key, so as to handle authentication and secure communication between client and server. +By default, when you create a new cluster, Couchbase Server generates a self-signed CA that it uses as its root CA. +It uses this CA to sign server certificates that it automatically generates for each node. +The root CA appears under *Trusted Root Certificates* on the *Certificates* tab of the *Security* page in the Couchbase Server Web Console. -This information associates the _identified entity_ (that is, the server-node or client bearing the certificate) with the issuing CA, such that third parties who know and trust the CA, but are unfamiliar with the identified entity, may elect to trust the identified entity on the basis of their trust in the CA. -Note that all systems that use certificates for authentication maintain their own collection of trusted CA certificates: if, when an entity attempts to authenticate, the entity proves that it has itself been authorized by a CA whose certificate is included in the system's collection, the entity may be trusted by the system. +image::learn:security/security_certificates_page.png[align=left] -Additionally, certificates can each be configured to contain _extensions_, which are used to constrain the certificate's capabilities (for example, by indicating the IP address of the server on which the certificate must reside; or by indicating the uses to which its public key must be restricted); or to identify a _username_, based on which client-authentication and authorization can proceed. +This page also lists each node's certificate. -[#certificate-hierarchies] -== Certificate Hierarchies +As you add nodes to the cluster, Couchbase Server automatically creates a new server certificate for them signed by this CA. +These default certificates allow the nodes to verify each other's identity, preventing outside systems from masquerading as a node. +They a basic level of security. -On a Couchbase-Server cluster, certificates are managed and deployed _hierarchically_. -The certificate with overall authority for the cluster is at the top of the hierarchy; and its authority is inherited by all certificates on lower tiers of the hierarchy. -One certificate _issues_ another certificate — thereby letting the new certificate inherit its own authority and occupy the tier immediately below itself — by the process of _certificate signing_. +You can add additional custom root certificates to Couchbase Server's trust store. +Common uses for the additional certificates includes signing certificates to identify client or XDCR clusters. +You can also use additional root certificates to replace the node certificates that Couchbase Server automatically generates. +The following sections explain these uses of custom certificates. -A _two-tier_ certificate hierarchy is one where the CA certificate has itself issued a certificate directly for one or more _identified entities_ — each of which could be an individual node within a cluster, or a client application that wishes to interact with the cluster. -If a third party trusts a CA, then it will also trust an identified entity whose own certificate has been issued by that CA. -The CA, being at the top of the two-tier hierarchy, is often referred to as the _Root CA_. +=== Custom Root Certificates -A _two-plus-tier_ certificate hierarchy is one where a Root CA has issued a certificate to an _intermediate authority_, which in turn has issued a certificate either to another intermediate authority, or directly to one or more entities that are to be identified. -Use of a two-plus-tier hierarchy requires that all intermediate certificates, as well as a given entity's certificate, be available for inspection when authentication is attempted; otherwise, the ultimate authority of the root will not be traced, and authentication will fail. -All certificates, both on the server-side and on the client-side, should therefore be made available to the requesting party as a complete _trust chain_. -In 7.1+, either of the following procedures can be used: +You can choose to create your own certificates, optionally signed by a well-known authority, and add them to Couchbase Server's trust store. +These additional certificates are listed under Trusted Root Certificates on the *Certificates* tab of the *Security* page, along with the self-signed CA. +You can use these custom root certificates to sign certificates for client systems and XDCR peers. -* The entity's own certificate, and all intermediate certificates, are provided directly to the requesting party. -The requesting party is expected to find the CA -- the last certificate in the chain -- in its own trust store; and if it does, authentication may proceed. +NOTE: You cannot use the private key for the self-signed root CA that Couchbase Server created to sign node certificates. +Therefore, the only way to create certificates for client systems and XDCR clusters is to create and add custom certificates to the trust store. -* The entity's own certificate alone is provided directly to the requesting party. -The requesting party is expected to find all associated intermediates, and the CA, in its own trust store; and if it does, authentication may proceed. +=== Custom Node Certificates -[#server-certificates] -== Default Certificates and Certificate Substitution +You can also use a custom root certificate to sign node certificates. +As long as the signing certificate has a chain of trust leading to a CA in the Couchbase Server's trust store, the node's certificate will be trusted by other nodes. -By default, Couchbase Server provides minimally defined _root_ and _entity_ certificates to protect cluster and individual nodes. -Administrators can replace these, with customized or externally acquired certificates, and with corresponding certificate-chains. -All certificates and certificate-chains for client-side use need to be explicitly created and/or deployed by administrators, as appropriate. +If you want to use custom node certificates, you can choose to replace the default self-signed root certificate with your own customized one. +To replace the self-signed CA, you must first replace each node's certificate with one you signed using the new CA. +Once no node has a certificate that was signed by the self-signed CA you can delete it. +You can learn which nodes have certificates signed by a root CA from its entry in the Couchbase Server Web Console's *Certificates* tab on the *Security* page. + The *Certs Issued For Nodes* field lists any nodes that have certificates signed by the certificate. -[#cluster-certificate] -=== Cluster Certificate +Couchbase Server only automatically generates node certificates for new nodes using its default self-signed root certificate. +If you remove this certificate, Couchbase Server does not automatically generate certificates for new nodes. +In this case, you must create a certificate for a new node before adding or joining it to the cluster. -The cluster certificate is the _root certificate_ issued for the cluster; and contains the public key of the corresponding Certificate Authority (CA). -The certificate itself is often referred to as the _Root CA_. -Programs that wish to interact securely with Couchbase Server must elect to trust this CA. -By means of _certificate signing_, the cluster certificate grants its authority to other certificates: this includes both server-side and client-side certificates. -Thus, if client and server share the same root certificate, they are likely to trust one another. +Couchbase Server requires that certificates for nodes meet the following requirements: -Couchbase Server provides a default, self-signed cluster certificate, which is created and deployed when the first node in a cluster is created. -A new, replacement cluster certificate can be deployed on the cluster by means of the Couchbase REST API or CLI. -The current cluster certificate is always visible on the *Root Certificate* panel of the *Security* screen of Couchbase Web Console. -See xref:manage:manage-security/manage-security-settings.adoc#root-certificate-security-screen-display[Root Certificate]. +* The node's certificate must have an attribute that limits its validity to the specific node. +See xref:#node-certificate-validation[Node Certificate Validation] for an explanation. +* The certificate must either: +** An X.509 format certificate in PEM format and named `chain.pem`. +In addition, you must also supply the certificate's private key in a file named `pkey.key`. +See xref:#private-key-formats[Private Keys] for a discussion of the private keys Couchbase Server supports. +** A PKCS #12 format file. +See xref:#pkcs12[PKCS #12 Certificates for Nodes] for more information about this format. -The file for the cluster certificate (indeed, for any other server or client certificate) is required to be in _Privacy Enhanced Mail_ (or _PEM_) format, with a `.pem` extension. -The file can have any name, although `ca.pem` is commonly used. -On creation, the certificate is generated (indeed, all certificates, whether server-side or client-side are generated) from a corresponding, already created _private key_; whose file is in _PKCS #1_ or _PKCS #8_ format, with a `.key` extension. -(For further information, see xref:learn:security/certificates.adoc#private-key-formats[Private Key Formats], below.) -The name of the private key often corresponds to the name of the certificate it generates: for example, `ca.key` would be used to generate `ca.pem`. -When an existing certificate is to be used to grant its authority to another, the existing certificate's `.key` and `.pem` files are both specified in the creation-process for the new certificate. +See xref:manage:manage-security/configure-server-certificates.adoc#root-and-node-certificates[Create and Deploy Cluster and Node Certificates] for step-by-step instructions on creating the new CA and node certificates. -Note that the private key of the default, self-signed cluster certificate is _not_ made available. -Consequently, custom certificate-chains based on the default certificate _cannot_ be created. -To create custom certificate-chains, a custom cluster certificate and private key must be generated (or alternatively, a Root CA must be acquired from an external authority, and certificate-chains then created based on an authority-signed _intermediate certificate_, as described below). -Examples of creating cluster and other certificates based on private keys are provided in xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] +=== Supported Certificate Formats -==== Multiple Root CAs +Most of the certificates you use with Couchbase Server are in the X.509 format. +Certificates you add to the trust store must meet the following criteria: + +* The certificate must be in a Privacy Enhanced Mail (PEM) file. +* These files have the extension `.pem`. +* The file can have any name, although `ca.pem` is commonly used. +* They contain a single certificate. -Couchbase Server allows multiple Root CA certificates to be loaded. -Together, these constitute a _trust store_, whereby Couchbase Server is able to determine whether or not to trust a client that is attempting access: if the client's Root CA, as identified through examination of the client-certificates's trust chain, resides in the cluster's trust store, the client may be trusted. +For examples of creating cluster and other certificates based on private keys see in xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] -The Couchbase-Server trust store includes one or more Root CAs that are used to provide authority to individual nodes: each node has at most one node certificate, potentially with a concatenated trust chain; and this points to a single Root CA in the cluster's trust store. -A single Root CA may be pointed to by the trust chains of multiple nodes. -All Root CAs in the trust store are accessible to all nodes, and multiple Root CAs may therefore be used in facilitating encrypted node-to-node communication. +[#pkcs12] +==== PKCS #12 Certificates for Nodes -For more information, see xref:learn:security/using-multiple-cas.adoc[Using Multiple Root Certificates]. +When creating custom certificates for nodes, you can use PKCS #12 format certificates instead of X.509 certificates. +This format lets you bundle the node's certificate, private key, and certificate chain into a single file. +Couchbase Server only supports this format for nodes. -[#intermediate-certificates] -=== Intermediate Certificates +When you upload a PKCS #12 certificate, Couchbase Server extracts the node's private key and certificate and handles them the same way it handles individual X.509 certificates. -An _intermediate certificate_ (sometimes referred to as a _subordinate certificate_, an _Intermediate CA_, or a _Signing CA_) can be either: +Several things to note when using PKCS #12 certificates: -* A certificate signed by the cluster certificate (the _Root CA_). +* The PKCS #12 file's name must be `couchbase.p12` and be located in the node's inbox directory. +* Make sure the node's inbox directory only contains the PKCS #12 certificate file. +If the directory contains both a PKCS #12 certificate and a private key file named `pkey.key`, the call to reload the node's certificates fails. +In this case, Couchbase Server cannot determine which file you want it to reload, and refuses to continue. -* One of a chain of intermediate certificates, each of which has been signed by that preceding it in the chain; except the first, which has been signed by the cluster certificate. +See xref:manage:manage-security/configure-server-certificates.adoc#pkcs12[Deploy a Certificate and Private Key to a Node in a PKCS #12 File] for an example of using this certificate format. -The main purpose of the intermediate certificate is to sign _node certificates_, _client certificates_, or other _intermediate certificates_; and thereby convey the authority of the cluster certificate to the node or client certificates _indirectly_. -This allows the cluster certificate's own private key to be only minimally used (and thereby more securely maintained) when multiple nodes or clients need to be signed — possibly across multiple clusters, subnets, or data centers. +[#node-certificate-validation] +==== Node Certificate Validation -The default certificates provided by Couchbase Server do not include intermediates: entity certificates are all signed directly by the root (the _cluster_ certificate). -However, if customized certificates and certificate-chains are substituted by the administrator, intermediate certificates can be defined and used. +In Couchbase Enterprise Server, each node certificate must have the node's name specified as a Subject Alternative Name (SAN). +This attribute restricts the certificate so it's only valid for the node named in the SAN. -Intermediate certificates can be uploaded to the Couchbase-Server trust store. -For information, see xref:learn:security/using-multiple-cas.adoc#adding-intermediate-certificates-to-the-trust-store[Adding Intermediate Certificates to the Trust Store]. +The SAN must meet the following requirements: -[#node-certificate] -=== Node Certificates +* If the node name is a Fully Qualified Domain Name (FQDN), the SAN must be the FQDN with a `DNS:` prefix. +For example, `DNS:node1.localhost.com`. +When the node name is an FQDN, the SAN cannot specify an IP address. -A _node certificate_, signed directly by the _cluster_ certificate, is assigned to each node in a Couchbase Cluster by default. -The process whereby default node certificates are generated (based on a new private key) and signed (by means of the current cluster certificate and cluster private key) is entirely automated; and occurs whenever a single-node cluster is created, and whenever additional nodes are added or joined. -Certificate-based security for a Couchbase Server-cluster is thereby provided, in a limited form, _out-of-the-box_ (supporting, for example, all the standard Couchbase-Server secure ports — which are described in xref:install:install-ports.adoc[Couchbase Server Ports] — and xref:learn:clusters-and-availability/node-to-node-encryption.adoc[Node-to-Node Encryption]). -However, broader security requirements may need to be supported by means of _customized_ certificates, configured to include special extensions and _Subject Alternative Names_, based on an administrator-selected root authority. +* If the node name is an IPv4 or an IPv6 IP address, the SAN must be the IP address, with an `IP:` prefix. +For example, `IP:127.0.0.1` or `IP:0:0:0:0:0:0:0:1`. +When the node name is an IP address, the SAN cannot specify an FQDN. -When customized node certificates have been prepared for a cluster, the following elements must be deployed on each node of the cluster, for its node certificate to become active: +NOTE: You can use the wildcard character in all expressions. -* The node private key, which has been used to create the node certificate for the current node. -On each node, this must be named `pkey.key`. +For examples configuring node certificate including setting the node's name as a SAN, see xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates]. -* The node certificate chain-file. -On each node, this must be named `chain.pem`. -When the node certificate has been signed directly by the cluster certificate, `chain.pem` is nothing more than the node certificate file, renamed. -However, when the node certificate has gained the CA's authority by means of a sequence of one or more intermediate certificates, `chain.pem` may be a correspondingly ordered _concatenation_ of all the certificates in the chain, except the cluster certificate: access to this file allows the authority of the node certificate to be established by progressive examination of the signing authorities in its chain. -+ -Alternatively, if indeed the node certificate has gained the CA's authority by means of a sequence of one or more intermediate certificates, `chain.pem` may still be configured to contain only the node certificate; if it is assumed that all intermediates in the chain are already resident in the client's _trust store_. +[#intermediate-certificates] +=== Intermediate Certificates + +An intermediate certificate--sometimes referred to as a subordinate certificate, an intermediate CA, or a signing CA--can be either: + +* A certificate signed by the root CA certificate. -Couchbase Server requires that these files, when newly created, be manually copied to a specific location in the filesystem: from this location, they are deployed by Couchbase Server. -Examples are provided in xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates]. +* One of a chain of intermediate certificates, each of which was signed by one preceding it in the chain. +The first certificate in the chain must be in Couchbase Server's trust store. + +The main purpose of the intermediate certificate is to sign node certificates, client certificates, or other intermediate certificates. +Signing node certificates convey the authority of the root certificate to the node or client certificates indirectly. +Using the intermediate certificate instead of the root certificate's own private key limits the key's use, making it more secure. + +The default certificates provided by Couchbase Server do not include intermediates: entity certificates are all signed directly by the root certificate. +However, if you use customized certificates and certificate chains, you can define intermediate certificates. + +You can upload intermediate certificates to the Couchbase Server trust store. +For information, see xref:learn:security/using-multiple-cas.adoc#adding-intermediate-certificates-to-the-trust-store[Adding Intermediate Certificates to the Trust Store]. -In Couchbase Enterprise Server Version 7.2 and later, each node certificate must be configured with its node's name correctly specified as a _Subject Alternative Name_. -See xref:learn:security/certificates.adoc#server-certificate-validation[Server Certificate Validation], below for details. [#client-certificates] -=== Client Certificates +== Client Certificates -A Couchbase Server-client can use a _client certificate_ to identify itself to Couchbase Server: this allows the server to authenticate the client, and to authorize the client's associated _user_. -Information included in the certificate identifies the user by means of a _username_. +A client can use a client certificate to identify itself to Couchbase Server. +The certificate allows the server to authenticate the client and to authorize the client's associated user. +Information included in the certificate identifies the user by means of a username. -Couchbase Server creates and uses client certificates by default, for inter-node communication; but these are not visible to the user. -Client certificates required for XDCR or SDK-client access must be explicitly created by the administrator; based on a customized, replacement cluster certificate. +Administrators must sign the client certificates for XDCR or SDK-client connections using a root CA certificate in Couchbase Server's trust store. -When authenticating a client that uses certificate-based authentication, Couchbase Server asks the client to present the client certificate. -Couchbase Server inspects the client certificate: if this is ascertained to be part of a chain that leads to a root authority that is recognized by Couchbase Server, the client may be trusted. -The certificate's time-validity and other details are checked. -If the certificate has not expired and is valid in all other necessary respects, the _username_ provided by the certificate is determined, and this is checked by Couchbase Server against registered users and their roles. -If the user exists, and the associated roles are appropriate, access is granted; otherwise, access is denied. +When authenticating a client that uses certificate-based authentication, Couchbase Server asks the client to present its certificate. +If Couchbase Server finds that the certificate's chain of trust leads to a root authority that it recognizes, it trusts the client. +Couchbase Server then verifies that the certificate has not expired. +After verifying the certificate is still valid, Couchbase Server extracts the username from the certificate. +If the username matches an existing user and the user has the correct roles to access Couchbase Server via the client, Couchbase Server lets the client connect. -Note that the private key used to create the client certificate is itself used in the process whereby the client authenticates itself against the server: the client digitally signs a message, using its private key, and sends this message to the server; allowing the client's _public_ key then to be used by the server to verify that the message has indeed been sent by the client. -An example of specifying the private key for this purpose, in the context of securing XDCR, is provided in xref:manage:manage-xdcr/enable-full-secure-replication.adoc#specify-full-xdcr-security-with-certificates[Specify Root and Client Certificates, and Client Private Key]. -A further example, in the context of securing contact with an LDAP host, is provided in xref:manage:manage-security/configure-ldap.adoc#client-certificate[Configure LDAP]. +A similar process allows the server to authenticate with the client in a process called mutual TLS (mTLS) or https://en.wikipedia.org/wiki/Mutual_authentication[mutual authentication^]. -Note also that these steps, whereby the client authenticates with the server, are additionally followed to allow the server to authenticate with the client. -The overall, two-way authentication process is referred to as _mutual TLS_ (_mTLS_) or https://en.wikipedia.org/wiki/Mutual_authentication[mutual authentication^]. +NOTE: The client's authentication with the server relies on the private key used to create the client certificate. +The client digitally signs a message with its private key and sends the message to the server. +The server uses the client's public key to verify that the client sent the message. + +For an example of using private keys to secure XDCR, see xref:manage:manage-xdcr/enable-full-secure-replication.adoc#specify-full-xdcr-security-with-certificates[Specify Root and Client Certificates, and Client Private Key]. + +For an example iof using certificates to secure a connection to an LDAP host, see xref:manage:manage-security/configure-ldap.adoc#client-certificate[Configure LDAP]. [#identity-encoding-in-client-certificates] -==== Specifying Usernames for Client-Certificate Authentication +=== Specifying Usernames for Client Certificate Authentication -The _username_ to be authorized by Couchbase Server can be specified by means of several elements included in the client certificate. -Couchbase Server can be configured to search for appropriate elements within the client certificate; and then attempt to authenticate and authorize, using each element as the basis for a Couchbase-Server username. +The client certificate can contain the username to use for a client connection. +You can configure Couchbase Server to search for a username among multiple elements within the client certificate. +If it finds an element that could contain a username, Couchbase Server attempts to authenticate and authorize username. -If multiple elements within the client certificate are so used, the first to be successfully authenticated by Couchbase Server is the one used. -The order in which the elements are examined is that configured on Couchbase Server, as described in xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client Certificate Handling]. +If you configure multiple elements within the client certificate to be potential usernames, Couchbase Server attempts to authenticate each until it either authenticates one or runs out of elements. +You set the order in which Couchbase Server examines the elements in the client certificate for usernames. +See xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client Certificate Handling] for details. [#specifying-usernames-in-certificates] -===== Embedding Usernames in Certificates +=== Embedding Usernames in Certificates -Within a certificate presented for authentication, the elements that can be used to specify a username include the following: +You can use the following elements in a certificate to specify a username: -* The `Subject` for the certificate, featuring the _Common Name_. -For example, on the command-line, during client-certificate preparation, `-subj "/CN=clientuser"` might be specified; to allow `clientuser` to be identified as the username. +* The `Subject` for the certificate, featuring the Common Name. +For example, when creating the client-certificate using the command line, you can set the subject of the certificate to `clientname` by using the `-subj "/CN=clientuser"` argument. + -Note that use of Subject Common Name is now deprecated (see https://tools.ietf.org/html/rfc6125#section-6.4.4[section 6.4.4 of RFC 6125^]); but continues to be supported by Couchbase Server. -See also xref:learn:security/certificates.adoc#deprecation-of-subject-common-name[Deprecation of Subject Common Name], below. +NOTE: The Internet Engineering Task Force (IETF) has deprecated the Subject Common Name as described in https://tools.ietf.org/html/rfc6125#section-6.4.4[section 6.4.4 of RFC 6125^]. +Couchbase Server continues to support using the Subject Common Name. +See also xref:learn:security/certificates.adoc#deprecation-of-subject-common-name[Deprecation of Subject Common Name]. -* The `DNS` name, provided as a _Subject Alternative Name_ for the certificate. -For example, `subjectAltName = DNS:node2.cb.com` would, with no prefix or delimiter specified in the Couchbase Server handling-configuration, allow `node2.cb.com` to be identified as the username. +* The `DNS` name, provided as a Subject Alternative Name for the certificate. +For example, if you add `subjectAltName = DNS:node2.cb.com` to the certificate, you can configure Couchbase Server to use `node2.cb.com` as the username withouy a prefix or delimiter specified in the handling-configuration. + -_Prefix_ and _delimiter_ are explained below, in xref:learn:security/certificates.adoc#identifying-certificate-based-usernames-on-couchbase-server[Identifying Certificate-Based Usernames on Couchbase Server]. +Prefix and delimiter are explained later in xref:learn:security/certificates.adoc#identifying-certificate-based-usernames-on-couchbase-server[Identifying Certificate-Based Usernames on Couchbase Server]. -* The `email`, provided as a _Subject Alternative Name_ for the certificate. -For example, `subjectAltName = email:john.smith@mail.com` would, with no prefix configured or delimiter specified, allow `john.smith@mail.com` to be extracted and identified as the username. -Note, however, that since the character `@` is not permitted in Couchbase Server usernames, no such user could exist. -Nevertheless, the user `john.smith` _could_ be defined on Couchbase Server; and this name could be extracted from `john.smith@mail.com`, given appropriate server-side configuration of a _delimiter_, as explained in xref:learn:security/certificates.adoc#identifying-certificate-based-usernames-on-couchbase-server[Identifying Certificate-Based Usernames on Couchbase Server], below. +* The `email` defined as a Subject Alternative Name for the certificate. +For example, if you add `subjectAltName = email:john.smith@example.com` to the certificate, you can configure Couchbase Server to use `john.smith@example.com` as the username. +However, because Couchbase Server does not allow the character `@` in usernames, `john.smith@example.com` is not valid. +You can configure Couchbase Server extract just the account portion of the email address (`john.smith`) by defining `@` as a delimiter. +See xref:learn:security/certificates.adoc#identifying-certificate-based-usernames-on-couchbase-server[Identifying Certificate-Based Usernames on Couchbase Server] form an explanation. -* The `URI` provided as a _Subject Alternative Name_ for the certificate. -For example, `subjectAltName = URI:www.acme.com` would, with no prefix or delimiter specified, allow `www.acme.com` to be extracted and identified as the username. +* The `URI` defined as a Subject Alternative Name in the certificate. +For example, if you add `subjectAltName = URI:www.example.com` to the certificate, you can configure Couchbase Server to use `www.example.com` as the username. -Examples of specifying _Subject Common Names_ and _Subject Alternative Names_ are provided in xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] and xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. +For examples of setting Subject Common Names and Subject Alternative Names in certificates, see xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] and xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. [#identifying-certificate-based-usernames-on-couchbase-server] -===== Identifying Certificate-Based Usernames on Couchbase Server - -Client-certificate handling is _disabled_ by default on Couchbase Server: it can optionally be _enabled_; and if required, specified as _mandatory_. - -When client-certificate handling has been enabled, _paths_ specified within the client certificate can be configured to be searched for, in order to retrieve _usernames_ for authentication. - -Each specified _path_ can be one of the following path-types: +=== Identifying Certificate-Based Usernames on Couchbase Server -* `subject.cn`. -The _Subject Common Name_ specified in the certificate will be extracted. +By default, Couchbase Server does not handle client certificates. +You can enable client certificate handling so that it is optional or even mandatory. -* `san.dns`. -The `DNS` _Subject Alternative Name_ for the certificate will be extracted. +When you enable client-certificate handling, you can configure Couchbase Server to search for paths within the client certificate that contain usernames for authentication. -* `san.email`. -The `email` _Subject Alternative Name_ for the certificate will be extracted. +Each specified path can be one of the following path-types: -* `san.uri`. -The `URI` _Subject Alternative Name_ for the certificate will be extracted. +* `subject.cn`: extracts the Subject Common Name. -Any number of paths can be specified on Couchbase Server, with multiple instances of any path-type. +* `san.dns`. extracts the `DNS` Subject Alternative Name. -The name retrieved by searching for a Couchbase Server-specified path can optionally be _parsed_, so that the symbols that constitute the username are isolated from extraneous characters. -This is achieved by associating the path with a specified _prefix_ and/or _delimiter_: +* `san.email`: extracts the `email` Subject Alternative Name. -* If neither a prefix nor a delimiter is specified for a given path, no parsing of the corresponding name is attempted; and authentication is attempted with the unparsed name. +* `san.uri`: extracts the `URI` Subject Alternative Name. -* If only a prefix is specified for a given path, parsing is attempted in accordance with the specified prefix. -If no instance of the prefix is located in the name, authentication is then attempted with the name unchanged. +You can specify any number of paths for Couchbase Server to extract. +You can also have it extract multiple instances of any path-type. -* If only a delimiter is specified for a given path, parsing is attempted in accordance with the specified delimiter. -If no instance of the delimiter is located in the name, authentication is then attempted with the name unchanged. +In some cases, the value in the certificate cannot match a Couchbase Server user name. +For example, email addresses are not valid usernames because they contain the `@` character. +To handle these case, you can have Couchbase Server parse the value from the certificate to extract the username. +You can define a prefix, delimiter, or both that Couchbase Server uses to extract a portion of the element it extracts from the path. -* If both a prefix and a delimiter are specified for a given path, parsing is attempted for each in turn — prefix first, then delimiter — as described above. -Authentication is then attempted with the string produced by these sequential parsing-attempts. +* If you define neither a prefix or delimiter for a path, Couchbase Server does not parse element's content. +It attempts to match the value as-is to an existing username. -_Prefix_ and _delimiter_ are defined as follows: +* You can define a prefix which is a string of text Couchbase Server attempts to match of the start of the value extracted from the certificate. +If the prefix matches the start of the value, Couchbase Server removes the matching prefix from the value. +It then tries to match the remaining string to a Couchbase Server username. +If the prefix does not match the start of the value, Couchbase Server tries to match the entire value to a username. +For example, suppose you specify `san.uri` as a path in the certificate to use, and set the prefix to `www.`. +If Couchbase Server extracts the value `www.example.com` from the `san.uri` element in the certificate, the prefix matches leading `www.`, leaving Couchbase Server with `example.com` as the username. +If instead the `san.uri` is `example.com`, the prefix does not match. +In this case, Couchbase Server attempts to match `example.com` to a username. -* _Prefix_: One or more characters that, if exactly matched with the substring that begins the string specified as the Subject Common Name or Subject Alternative Name, are removed from that string. -For example, if a certificate-specified `san.uri` is `www.couchbase.com`, and the server-specified prefix is `www.`, then `www.` is removed from `www.couchbase.com`, leaving the string `couchbase.com`. +* You can define a delimiter, which is a single character that Couchbase Server should use to split the value extracted from the certificate. +If it finds the delimiter in the value, Couchbase Server uses the portion of the value before the delimiter as the username. +If Couchbase Server does not find the delimiter in the value, it uses the entire value as the username. +For example, suppose you specify `san.email` as a path in the certificate, and set the delimeter to `@`. +If Couchbase Server extracts the value `john.smit@example.com` as the value of `san.email`, it splits the value at the `@`, leaving it with `john.smith` to match to a username. + -However, if a certificate-specified `san.uri` is `foo.bar.com`, and the server-specified prefix is `www.`, nothing is removed from `foo.bar.com`. - -* _Delimiter_: A single character that, if matched with a single instance in the string being parsed, causes both itself and all subsequent characters to be discarded from the string. -For example, a delimiter of `.` causes the substring `.com` to be discarded from `couchbase.com`; and leaves `couchbase` as the username to be authenticated. -+ -Note that if a string contains multiple instances of the character specified as the delimiter, the _first_ instance is the one used. -For example, a delimiter of `.` causes the substring `.couchbase.com` to be discarded from `www.couchbase.com`, leaving `www` as the username to be authenticated. +NOTE: If the value contains multiple instances of the delimiter, Couchbase Server only uses the portion before the first delimiter. +For example, if you set the delimiter to `.` and the value is `www.example.com`, Couchbase Server attempts to match `www` to a username. +It does not attempt to match any other portion of the value if the first part does not match. For step-by-step instructions, see xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client Certificate Handling]. [#deprecation-of-subject-common-name] == Deprecation of Subject Common Name -Use of the _Subject Common Name_ to identify either a server or a client is now deprecated (see https://tools.ietf.org/html/rfc6125#section-6.4.4[section 6.4.4 of RFC 6125^]). +The IETF has deprecated using Subject Common Name to identify either a server or a client in https://tools.ietf.org/html/rfc6125#section-6.4.4[section 6.4.4 of RFC 6125^]. For Couchbase Enterprise Server Version 7.2 and later, this means that: -* The node-certificate for each server in the cluster must specify its node-name as a _Subject Alternative Name_: see xref:learn:security/certificates.adoc#node-certificate-validation[Node-Certificate Validation], immediately below, for details. -Subject Common Name may continue to be specified. - -* A client-certificate may continue to specify only a Subject Common Name. +* The node certificate for each server in the cluster must specify its node name as a Subject Alternative Name. +See xref:learn:security/certificates.adoc#node-certificate-validation[Node-Certificate Validation] for details. +You can still use Subject Common Name. -Examples of certificate-creation provided in xref:manage:manage-security/manage-certificates.adoc[Manage Certificates] continue to include definitions of Subject Common Name for both server and client. - -[#node-certificate-validation] -== Node-Certificate Validation +* A client certificate may continue to specify just a Subject Common Name. -In Couchbase Enterprise Server Version 7.2 and later, each _node certificate_ must be configured with the node-name correctly specified as a _Subject Alternative Name_ (SAN). +Examples of certificate creation provided in xref:manage:manage-security/manage-certificates.adoc[] continue to include definitions of Subject Common Name for both server and client. -The SAN must meet the following requirements. -(Note that the wildcard character is permitted in all expressions.) -* If the node-name is a _Fully Qualified Domain Name_ (FQDN), the SAN must specify this FQDN, using the `DNS:` prefix. -For example, `DNS:*.localhost.com`. -Note that when the node name is an FQDN, the SAN _cannot_ specify an IP address. - -* If the node-name is an _IPV4 IP Address_, the SAN must specify this IP address, using the `IP:` prefix. -For example, `IP:127.0.0.1`. -Note that when the node-name is an IP address, the SAN _cannot_ specify an FQDN. - -* If the node-name is an _IPV6 IP Address_, the SAN must specify this IP address, using the `IP:` prefix. -For example: `IP:0:0:0:0:0:0:0:1`. -Note that when the node-name is an IP address, the SAN _cannot_ specify an FQDN. - -For complete examples of server-certificate configuration, specifying the node-name as a SAN, see xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates]. [#certificate-checking] === Certificate Checking -Certificate-checking occurs in the following situations: +Couchbase Server checks the validity of certificates in following situations: -* A certificate is uploaded to a node. -If the name of the node is not correctly specified as a SAN: +* You upload certificate to a node. +If the name of the node is not specified as a SAN: ++ +-- +** If the name of the node can be changed, Couchbase Server issues a warning, and the upload succeeds. -** If the name of the node itself can be changed, a warning is returned, and the upload succeeds. +** If the name of the node cannot be changed, Couchbase Server reports an error, and the upload fails. +-- ++ +To learn when you can rename a node, see xref:learn:clusters-and-availability/nodes.adoc#node-renaming[Node Renaming]. -** If the name of the node itself cannot be changed, an error is returned, and the upload fails. +* You add a node or a node joins the cluster. +Couchbase Server always checks the certificate on the new node to verify the node's name is correctly specified as a SAN. Depending on the cluster's configuration, Couchbase Server may perform the same check on the certificate of the cluster node handling the join. +If Couchbase Server finds an issue, its response depends on what sort of check it performed: -+ -For information on when the node itself can be renamed, see xref:learn:clusters-and-availability/nodes.adoc#node-renaming[Node Renaming]. +** New node: If the node name is not specified as a SAN, Couchbase Server returns an error and the add or join fails. + +** Cluster node: If the cluster has two or more nodes prior to the add or join, Couchbase Server does not perform a check. +Otherwise, the Couchbase Server performs the check. +If the node-name is not specified as a SAN, the add or join fails. -* A node is added or joined to a cluster. -In this case, the certificate on the new node (always) and on the cluster node handling the join (sometimes, depending on the cluster's configuration) is checked for a node-name correctly specified as a SAN: +[#certificate-expiration] +== Certificate Expiration -** _New node_: If the node-name is not correctly specified as a SAN, an error is returned, and the add or join fails. +When you create a certificate, you can choose to have it expire after a period of time. +Setting an expiration on certificates is a best practice, as it can help limit the impact of a certificate being compromised. +It also helps enforce certificate rotation. +See xref:manage:manage-security/rotate-server-certificates.adoc[]. -** _Cluster node_: If the cluster has two or more nodes prior to the add or join, the check is _not_ performed. -Otherwise, the check is performed; and if the node-name is not correctly specified as a SAN, the add or join fails. +When you set your certificates to expire, you must remember replace them before their expiration. +You can have the Couchbase Server alert feature notify you before a certificate expires. +By default, Couchbase Server sends this alert 30 days before the certificate expires. +You can change this alert period using the `/settings/alerts/limits` endpoint to change the `certExpirationDays` setting. +See xref:rest-api:rest-cluster-email-notifications.adoc[] for more steps to change this setting. +Couchbase Server also alerts a second time if a certificate has expired. +See xref:manage:manage-settings/configure-alerts.adoc[] for more information about alerts. [#private-key-formats] -== Private Key Formats +== Private Keys -In version 7.1 and later, Couchbase Server supports _PKCS #1_ and _PKCS #8_ — in each case, only for use with private keys: +Couchbase Server supports using both RSA and X.509 Elliptic Curve (EC) private keys. -* _PKCS #1_ can be used for _unencrypted_ private keys only. +Couchbase Server supports using the PKCS #1 file format only for unencrypted private keys. +This format only supports RSA keys. -* _PKCS #8_ can be used for both _unencrypted_ and _encrypted_ private keys: note that the user-specified `EncryptedPrivateKeyInfo` must use _PKCS #5 v2_ algorithms. +Couchbase Server supports using PKCS #8 file format for both unencrypted and encrypted private keys. +The user-specified `EncryptedPrivateKeyInfo` must use PKCS #5 v2 algorithms. +This format supports both RSA and Elliptic Curve keys. + +IMPORTANT: Couchbase Server does not support Elliptic Curve Key files containing EC PARAMETERS. +When generating EC keys using the `openssl` command, be sure to use the `-noout` argument to prevent it from adding an EC PARAMETERS section. [#json-passphrase-registration] == JSON Passphrase Registration -If a node-certificate is to be associated with an encrypted private key, a procedure can be defined to allow Couchbase Server to access and use the key's passphrase, when use of the key is required: the passphrase can be _registered_, by specifying a JSON object with the REST API. +If a node's certificate has an encrypted private key, you can give Couchbase Server the key's passphrase, so it can use the private key when necessary. +You register the passphrase by passing Couchbase Server a JSON object using the REST API. For information, see xref:rest-api:upload-retrieve-node-cert.adoc[Upload and Retrieve a Node Certificate]. - [#examples] == Examples diff --git a/modules/learn/pages/security/on-the-wire-security.adoc b/modules/learn/pages/security/on-the-wire-security.adoc index 211857cb20..86a908bd51 100644 --- a/modules/learn/pages/security/on-the-wire-security.adoc +++ b/modules/learn/pages/security/on-the-wire-security.adoc @@ -63,18 +63,23 @@ A _service_ can be _any_ of the Couchbase Server xref:learn:services-and-indexes The relationships between _global_ and _per service_ settings for TLS and cipher-suites are described in the following subsections. [#min-tls-version] -==== Establishing the Minimum TLS-Version +==== Setting the Minimum TLS Version -The minimum TLS version can be established either globally or per service: the server will not accept client connections with protocols below the level of the established, minimum version. +You can set the minimum version of TLS that Couchbase Server accepts either for the entire server or on a per-service basis. +Couchbase Server refuses connections from clients who use a version of TLS earlier than this minimum. +You can choose to set the minimum TLS version to either 1.2 or 1.3. -The minimum version can be established globally and for all services as `tlsv1`, `tlsv1.1`, `tlsv1.2` or `tlsv1.3`. -Note, however, that `tlsv1` and `tlsv1.1` are _deprecated_ in Couchbase Server Version 7.2. -Also, see xref:learn:security/on-the-wire-security.adoc#cipher-suite-configuration-limitations[Cipher-Suite Configuration Limitations], below, for further information. +IMPORTANT: Couchbase Server 7.6 and later do not support TLS versions 1 and 1.1. +Support for these earlier versions was deprecated in Couchbase Server 7.2. +When upgrading from a pre-7.6 version of Couchbase Server to version 7.6 or later, the upgrade process sets any TLS minimum setting that's lower than 1.2 to 1.2. -The cluster-wide default value for the minimum TLS version is `tlsv1.2`: this is used by a service if no value has been specified for that service, and no global value has been specified. +Couchbase Server defaults to requiring TLS version 1.2 or later if you have set Couchbase Server to enforce TLS. +You can change this global default to require at least TLS version 1.3. +Individual services use the system default value unless you set a minimum TLS version for them specifically. +See xref:manage:manage-security/manage-tls.adoc[] to learn how to change these settings. -If a particular minimum TLS-version is specified for a given service, that service uses its specified value. -If no TLS-version has been specified for a given service, but a global value has been specified, the service uses the global value. + +Also, see xref:learn:security/on-the-wire-security.adoc#cipher-suite-configuration-limitations[Cipher-Suite Configuration Limitations] for further information. ==== Establishing Cipher-Suite Preference diff --git a/modules/manage/assets/images/manage-settings/emailAlertsScreenInitial.png b/modules/manage/assets/images/manage-settings/emailAlertsScreenInitial.png index e01539d0db..e5c083a913 100644 Binary files a/modules/manage/assets/images/manage-settings/emailAlertsScreenInitial.png and b/modules/manage/assets/images/manage-settings/emailAlertsScreenInitial.png differ diff --git a/modules/manage/pages/manage-security/configure-server-certificates.adoc b/modules/manage/pages/manage-security/configure-server-certificates.adoc index a7ea7e1af4..a73e460efc 100644 --- a/modules/manage/pages/manage-security/configure-server-certificates.adoc +++ b/modules/manage/pages/manage-security/configure-server-certificates.adoc @@ -1,84 +1,53 @@ = Configure Server Certificates -:description: Couchbase Server Enterprise Edition supports X.509 certificates, for \ -the encryption of communications between the server and \ -networked clients. +:description: Couchbase Server Enterprise Edition supports using X.509 and PKCS #12 certificates for authenticating and encrypting data between the nodes in the cluster. [abstract] {description} -[#configure-server-side-certificates] -== Configure Server Certificates +This page explains how to configure server certificates for Couchbase Server Enterprise Edition. +For an overview of how Couchbase Server uses certificates, see xref:learn:security/certificates.adoc[Certificates]. -This section demonstrates how server certificates can be configured for Couchbase Server. -Note that the procedures are provided only as _limited examples_, giving guidance as to the basic steps typically involved in certificate creation. -Modification of the procedures will likely be required, for the preparation of certificates for different platforms and cluster-configurations. +The procedures in this page are only limited examples. +They cover the basic steps for creating certificates. +When creating and deploying certificates for your own database, you often have to modify these steps to suit your environment. -Two procedures are provided, each of which configures X.509 certificates on Ubuntu 18 for a one-node Couchbase Server-cluster. -Before attempting to follow either procedure, see the conceptual and architectural information provided in xref:learn:security/certificates.adoc[Certificates]. +This page gives detailed steps to configure X.509 certificates on a Linux-based single node Couchbase Server. +It demonstrates two scenarios. +The first shows directly signing the node's certificate using the root certificate. +The second shows creating an intermediate certificate from the root certificate and using that to sign the node's certificate. -The first procedure, xref:manage:manage-security/configure-server-certificates.adoc#root-and-node-certificates[Cluster Protection with Root and Node Certificates], is the simpler: it shows how to create a root certificate that is a trusted, self-signed authority; and how to use this to sign individual, per node certificates. +This page also explains how you can bundle certificates, private keys, and certificate chains into a single Public-Key Cryptography Standard (PKCS) #12 certificate file. +Couchbase Server supports using this type of file to upload node certificates. -The second procedure, xref:manage:manage-security/configure-server-certificates.adoc#root-intermediate-and-node-certificates[Cluster Protection with Root, Intermediate, and Node Certificates], demonstrates how a created root certificate and its private key are used to sign one or more _intermediate_ certificates; which are then in turn used with their own private keys to sign individual, per node certificates: such use of intermediate certificates and their private keys increases security — in that it minimizes use of the private key associated with the root certificate, when the signing of many node-certificates or client-certificates is required. - -Although these procedures demonstrate certificate management and deployment on single-node clusters, the steps they contain can also be used on _multi-node_ clusters; with some of the steps being necessarily repeated, across the different nodes. -See xref:manage:manage-security/configure-server-certificates.adoc#protection-of-multi-node-clusters[Protection of Multi-Node Clusters], below, for details. - -Note also that once a cluster has been protected with administrator-defined certificates in accordance with these procedures, any new nodes subsequently to be added to the cluster must be individually protected with conformant certificates, before addition can take place. -See xref:manage:manage-security/configure-server-certificates.adoc#adding-new-cluster-nodes[Adding New Cluster-Nodes], below, for details. - -=== Root Certificates: Single versus Multiple - -The examples in this section each feature creation and use of a single root certificate, which is used to provide its authority to a node certificate. -Prior to Couchbase Server 7.1, a single root certificate was the maximum that could be used for a cluster. -In Couchbase Server 7.1 and later, _multiple_ root certificates can be maintained in a _trust store_ for the cluster: this is described in xref:learn:security/using-multiple-cas.adoc[Using Multiple Root Certificates]. -Procedures for creating root certificates, and using these to sign node or intermediate certificates, are unaffected. -However, procedures for _loading_ root and node certificates have changed in 7.1: details are provided below. - -[#using-an-externally-provided-root-certificate] -=== Using an Externally Provided Root Certificate - -The examples below show how to _create_ a root certificate, and how to use that certificate's _private key_ to _sign_ (and thereby confer limited authority to) other certificates. -However, production deployments of Couchbase Server will frequently deploy an _externally provided_ root certificate for the cluster, this having been provided by a recognized certificate authority. -Additionally, an _intermediate_ (sometimes referred to as a _subordinate_) certificate, defined by the system administrator for the production environment, is likely to have been signed by the external authority, using its root certificate's private key: this allows the intermediate certificate and its private key to be used by the system administrator in creating additional certificates for deployment, each of these certificates thereby acquiring authority indirectly from the root. - -Therefore, to use the procedures provided below in the context of a root certificate having been provided by, and an intermediate certificate signed by, an external authority, substitute the externally provided root certificate for the generated `ca.pem`; use the externally signed intermediate in place of the generated intermediate; and use the private key of the externally signed intermediate to sign node and client certificates as appropriate. - -[#node-to-node-encryption-and-certificate-management] -=== Node-to-Node Encryption and Certificate Management - -Couchbase Server supports xref:learn:clusters-and-availability/node-to-node-encryption.adoc[Node-to-Node Encryption], whereby network traffic between the individual nodes of a cluster is encrypted. - -Prior to Couchbase Server Version 7.1, node-to-node encryption, which is managed by means of the Couchbase CLI, needed to be _disabled_ before management of either _root_ or _intermediate_ certificates could be performed. -This restriction is lifted in version 7.1: therefore, root and intermediate certificates _can_ now be managed while node-to-node encryption is enabled. +NOTE: Once you deploy cluster and node certificates to a database, you must create additional node certificates for any new nodes you add later. +See xref:manage:manage-security/configure-server-certificates.adoc#adding-new-cluster-nodes[Adding New Cluster Nodes] for details. [#root-and-node-certificates] -== Cluster Protection with Root and Node Certificates +== Create and Deploy Cluster and Node Certificates -The following procedure shows how to create a root certificate that is the trusted, self-signed authority used to sign individual, per node certificates. -Note that corresponding, subsequent procedures that create certificates for _client_-authentication are provided in xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-a-root-certificate[Client Access: Root Certificate Authorization] and xref:manage:manage-security/configure-client-certificates.adoc#java-client-access-root-certificate-authorization[Java Client Access: Root Certificate Authorization]. +The following procedure shows how to create a self-signed root certificate for a single-node database. +It then demonstrates using that certificate to sign a node certificate. +The steps for a multi-node cluster are similar, as explained at the end of the example. -Proceed as follows: +. Open a command line shell on the node. -. On the server to be certificate-protected, create working directories: +. In some directory (such as your home directory or `/tmp`) create working directories: + +[source, console] ---- mkdir servercertfiles cd servercertfiles mkdir -p {public,private,requests} ---- + -The `public` directory will be used to store certificates, which contain _public_ keys. -The `private` directory will contain _private_ keys. -The `requests` directory will store certificate _signing requests_, which are files generated from private keys: when a signing request is granted the signature of an appropriate authority, a _signed certificate_ is produced. - -. Create a _private key_ for the cluster. -+ -A private key can be used to decrypt data previously encrypted by the corresponding _public_ key. -It can also be used to sign a message that is then sent by the client to the server; allowing the client's identity to be verified by the server, using the client's public key. -In the key-creation sequence, the private key is created first. -Then, the public key is created, being _derived from_ the private key. +In this example, each directory has a different purpose: + -Enter the following: +* The `public` directory stores certificates, which contain public keys. +* The `private` directory contains private keys. +* The `requests` directory stores certificate signing requests. + +. Create a private key for the cluster: +[source, console] + ---- openssl genrsa -out ca.key 2048 @@ -86,57 +55,32 @@ openssl genrsa -out ca.key 2048 + The output of this command, `ca.key`, is the private key for the cluster. -. Create the _certificate_ (that is, the file that will contain the public key) for the cluster. -The certificate is intended to be _self-signed_, meaning that it will not be vouched for by any other authority. -This means that it can be created directly, based on the existing private key `ca.key`, without assistance from a third party. -+ -Enter the following: +. Create the certificate (the file that contains the public key) for the cluster: + +[source, console] ---- openssl req -new -x509 -days 3650 -sha256 -key ca.key -out ca.pem \ --subj "/CN=Couchbase Root CA" + -subj "/CN=Couchbase Root CA" ---- + -The `x509` flag indicates that in this case, an x509 structure, rather than a _request_ is to be generated. -(By contrast, a request _will_ need to be generated whenever the signature of a third-party authority is required: this is demonstrated below.) -The `days` flag specifies the number of days for which the certificate should be active. -The hashing algorithm to be used for digital-signature creation is specified as `sha256`. -The private key file on which the certificate is to be based is specified as `ca.key`, and the output-certificate is named as `ca.pem`. -The certificate's _issuer_ is specified to have the `CN` (_Common Name_) of `Couchbase Root CA`: as this name indicates, the certificate will be the _root_ certificate for the Couchbase Server-cluster. +The arguments to this command are: + -The output of the command is the certificate `ca.pem`; which contains the public key corresponding to the cluster's private key, `ca.key`. -+ -Optionally, the public key within the certificate can be displayed as follows: -+ ----- -openssl x509 -in ./ca.pem -noout -pubkey ----- -+ -The output has approximately the following appearance: -+ ----- ------BEGIN PUBLIC KEY----- -MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3HMfiSjCwakfMbA20HUd -V372JbQG9UGjf9V3xyMa90IHFD8cFjPYao7SZOpe0nkm2UmZRgQbTwWxC4CZqrYZ -pyrWLn9rjDFkzzbRjMRcZv2D0s0KkPrNYxfHj3cL/j5bpB4/hquvb4RglMkyyJo9 -mVx19lF4mtEsBqPGZBGArbzeArn4c1e6I4mqIfb9Vne/7vhIzLLSXoT5FmifWyGQ -4B9BSIrE9Ildwhez699MGfj+N+0xg2wTOIUVNvS1c5gF/uDS6t9Aswb60W+hjtF4 -d1ZBKBIVkmPGX0XOgGtdndXza4sjVkh3bB/ipWo9zUJYwFCWkofbqGeSnSz9n9o6 -fwIDAQAB ------END PUBLIC KEY----- ----- -+ -Note that by substituting other flags for `-pubkey`, other characteristics of the certificate can be displayed. -`-issuer` displays the certificate's issuer, and `-subject` its subject (in both cases, `subject= /CN=Couchbase Root CA`). -The `-version`, `-serial`, `-subject-hash`, and more can be displayed. -+ -The _entire certificate_ can be displayed as text, by means of the following command: +* `-x509`: generates an X.509 format certificate. +* `-days 3650`: the number of days before the certificate expires. +* `-sha256` the hashing algorithm to use for the digital signature. +* `-key ca.key`: sets the private key file the certificate is based on to the private key you created in the previous step. +* `-out ca.pem`: the filename for the certificate. +* `-subj "/CN=Couchbase Root CA"`: the `/CN=` portion of the argument sets the common name of the certificate's issuer to `Couchbase Root CA`. +This name identifies the certificate as the root certificate for the Couchbase Server cluster. + +. Optionally, you can review the content of the certificate you just created using the command: + +[source, console] ---- openssl x509 -text -noout -in ./ca.pem ---- + -The initial part of the output, which is extensive, is as follows: +The following is an example of the first part of the output: + ---- Certificate: @@ -159,78 +103,40 @@ Certificate: . ---- + -The displayed text thus provides information including the `Version`, the `Serial Number`, and the `Signature Algorithm` of the certificate. -The certificate's `Issuer`, `Subject`, and period of `Validity` are also shown. -The `Algorithm` and `Modulus` (and, further below, the `Exponent`) of the public key are shown. -+ -For detailed information on keys and key-generation, see https://en.wikipedia.org/wiki/RSA_(cryptosystem)[RSA (cryptosystem)]. +For detailed information about keys and key generation, see https://en.wikipedia.org/wiki/RSA_(cryptosystem)[RSA (cryptosystem)]. -. Create a private key for the individual node. -In addition to the root certificate and private key for the entire cluster, which are `ca.pem` and `ca.key`, a _node_ certificate and private key must also be created. -The node certificate, along with its corresponding node-private key, will reside on its own, corresponding node. -When deployed, each node certificate must be named `chain.pem`, and each node private key `pkey.key`. -Consequently, if the node certificates and private keys for multiple nodes are being prepared on a single system, the files should be given individual, distinctive names on creation; and then each deployed on its appropriate node as either `chain.pem` or `pkey.key`. -This renaming procedure is indeed followed here for demonstration purposes, even though only a one-node cluster is involved. +. Create a private key for the node. +Each node in the cluster needs its own private key and certificate. +Couchbase Server requires that you name the file containing the private key `pkey.key`. +However, if you're creating private keys for multiple nodes, you'll need to give them unique filenames to avoid them overwriting each other. +This example gives it a unique name, which you'll need to change when you deploy the private key to the node. + -Create the node private key as follows: +The command to create a private key is: + +[source, console] ---- openssl genrsa -out private/couchbase.default.svc.key 2048 ---- -+ -The output file is `couchbase.default.svc.key`, which is the private key for the node. -. Create a certificate signing request for the node certificate. -This step allows the materials required for certificate-creation to be passed to a third-party, who will _digitally sign_ the certificate as part of its creation-process, and thereby confirm its validity. -(In this demonstration, however, no actual third-party is involved: the certificate will be signed by means of the _root_ private key, which is owned by the current user.) -+ -Enter the following command: +. Create a Certificate Signing Request (CSR) for the node certificate: + +[source, console] ---- openssl req -new -key private/couchbase.default.svc.key \ --out requests/couchbase.default.svc.csr -subj "/CN=Couchbase Server" ----- -+ -The `key` specified as the input for the request is `couchbase.default.svc.key`, which was created in the last step. -The output request-file is specified as `couchbase.default.svc.csr`. -Note that this can be inspected as text, by entering the following command: -+ ----- -openssl req -text -noout -verify -in ./requests/couchbase.default.svc.csr + -out requests/couchbase.default.svc.csr -subj "/CN=Couchbase Server" ---- + -The initial part of the displayed output, which is extensive, is as follows: -+ ----- -verify OK -Certificate Request: - Data: - Version: 0 (0x0) - Subject: CN=Couchbase Server - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - Public-Key: (2048 bit) - Modulus: - 00:be:26:e5:06:c6:8e:43:bb:9d:bc:84:20:34:8e: - db:2f:d1:8b:b4:ff:c2:66:c0:61:70:8d:c3:8c:df: - . - . ----- -+ -The `Version` and `Subject` of the request are listed, along with information on the public key that is to be included in the certificate. +This step prepares the request you use to sign the node's certificate with the cluster's private key and certificate later. -. Define _certificate extensions_ for the node. -Certificate extensions specify constraints on how a certificate is to be used. -Extensions are submitted to the signing authority, along with the certificate signing request. +. Create a file that contains the certificate extensions that all nodes have in common. +These extensions define constraints on how a certificate can be used. +For detailed information about certificate extensions, see the https://tools.ietf.org/html/rfc5280#section-4.2.1[Standard Extensions^] section of the https://tools.ietf.org/html/rfc5280[Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL Profile)^]. +You submit the extensions to the signing CA, along with the CSR you generated in the previous step. +The next step adds information specific to an individual node. + -For example, the certificate's public key can be specified, by means of the `keyUsage` extension, to support _digital signatures_, but _not_ to support _key encipherment_ — or, _the opposite_ can be specified; or, support of _both_ digital signatures _and_ key encipherment can be specified. -Meanwhile, the `subjectAltName` extension can be used to specify the _DNS name_ and _IP address_ of the server on which the certificate resides; so that if the certificate is deployed in any other context, it becomes invalid. -+ -For detailed information on certificate extensions, see the https://tools.ietf.org/html/rfc5280#section-4.2.1[Standard Extensions] section of the https://tools.ietf.org/html/rfc5280[Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL Profile)]. -+ -Certificate extensions can be defined in a file, whose pathname is then provided as a parameter to the `openssl` command used to create the certificate. -Thus, such server-certificate extensions as are intended to be generic across all cluster-nodes might be written as follows: +Use this command to create the certificate extension file: + +[source, console] ---- cat > server.ext <> ./server.ext.tmp ---- + -This customized extensions file is to be used to authenticate a single node, whose IP address is `10.143.192.102`. -Note that if the DNS naming-convention is used by the cluster, the node's DNS name might be specified instead: for example, `DNS:node2.cb.com`. -+ -Note that in Couchbase Enterprise Server Version 7.2+, the node-name _must_ be correctly identified in the node certificate as a Subject Alternative Name -- as is done here, with `subjectAltName = IP:10.143.192.102`. -If such identification is not correctly configured, failure may occur when uploading the certificate, or when attempting to add or join the node to a cluster. -For information, see xref:learn:security/certificates.adoc#node-certificate-validation[Node-Certificate Validation]. +This command copies the file created in the previous step and adds a `subjectAltName` extension that identifies the node. +This example uses the node's IPv4 address. +This extension makes sure the node's certificate is valid for just the specific node. +No other node or client can use the certificate. +If your cluster uses DNS names to identify nodes, you must use the node's DNS name, such as `DNS:node2.cb.com` instead of its IP address. + -The creation of the customized extensions file should occur once for each node, with each customized extensions file containing only those extensions that apply to the current node. +NOTE: Couchbase Enterprise Server requires that the node's certificate identifies the node in a Subject Alternative Name extension. +Without this identification, Couchbase Server reports an error when you upload the certificate to the node or when you try to add the node to the cluster. +For more information, see xref:learn:security/certificates.adoc#node-certificate-validation[Node-Certificate Validation]. -. Create the node certificate, applying the certificate and digital signature of the appropriate authority, and the customized extensions file for the node, to the materials in the signing request. -+ -Enter the following: +. Create the node's certificate by signing it with the certificate and digital signature of the CA. +In this example, the CA is the root certificate created earlier. +Therefore, the command to sign the node's certificate uses the `ca.pem` and `ca.key` files: + +[source, console] ---- openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 -req \ --in requests/couchbase.default.svc.csr \ --out public/couchbase.default.svc.pem \ --extfile server.ext.tmp + -in requests/couchbase.default.svc.csr \ + -out public/couchbase.default.svc.pem \ + -extfile server.ext.tmp ---- + -The file generated by this command, `couchbase.default.svc.pem`, is the node certificate. -The root certificate and private key, `ca.pem` and `ca.key`, are specified as input values to the certificate-creation command. -This ensures that the new certificate's chain of trust includes the root certificate, `ca.pem`, and is digitally signed by `ca.key`; allowing that signature to be verified by means of the public key. +The arguments to this command are: ++ +-- +* `x509`: specifies that `openssl` is working with an X.509 certificate. +* `-CA ca.pem -CAkey ca.key`: tells `openssl` to use the key and certificate created in steps 1 and 2 as the CA. +* `-CAcreateserial`: tells `openssl` to create a serial number file if it does not already exist. +It then writes the serial number it assigns to the certificate to this file. +The serial file records the serial numbers of all the certificates `openssl` creates to make sure each certificate it creates has a unique serial number. +* `-days 365`: sets the number of days before the certificate expires. +* `-req`: tells `openssl` that you want to read a CSR to perform a certificate signing. +* `-in requests/couchbase.default.svc.csr`: has `openssl` read the CSR created in step 6. +* `out public/couchbase.default.svc.pem`: tells `openssl` sets where to save the signed node certificate. +* `-extfile server.ext.tmp`: tells `openssl` to read the extensions file created in step 9. +-- ++ +The file generated by this command, `couchbase.default.svc.pem`, is the node's certificate. + -The following confirmatory output is displayed: +The output of running the previous command looks like this: + +[source, console] ---- Signature ok subject=/CN=Couchbase Server Getting CA Private Key ---- -+ -Note that if a node certificate were actually submitted to an external authority for signing, then the authority's own `pem` and `key` would be specified as inputs, rather than `ca.pem` and `ca.key`: and in such a case, the authority's `pem` would need to become the root certificate for the cluster. -. Rename the node certificate and node private key. -For deployment on the node, the node certificate must be renamed `chain.pem`; and the node private key renamed `pkey.key`. -Proceed as follows: +. Before you can deploy the key private key and the certificate to the node, you must rename their files. +Couchbase Server requires that these files have specific filenames. +Rename the certificate file to `chain.pem` and the private key file to `pkey.key`: + +[source, console] ---- cd ./public mv couchbase.default.svc.pem chain.pem cd ../private mv couchbase.default.svc.key pkey.key ---- ++ +NOTE: In this example you could just have `openssl` output the correct filenames in steps 5 and 9. +In production, you often create certificates for multiple nodes at the same time, and so need to give each file a unique name. -. Deploy the node certificate and node private key. -These are deployed by being moved to the `inbox` directory of the server, and made _executable_. -The `inbox` directory must be created by the administrator. -Proceed as follows: +. If the node to which you're deploying the certificate does not have an inbox directory, create it. +The inbox directory is where Couchbase Server looks for certificate, key, and related files. +See xref:rest-api:load-trusted-cas.adoc[] for a list of the inbox paths on all platforms. +On Linux, this directory is `/opt/couchbase/var/lib/couchbase/inbox/`. + +[source, console] ---- -cd .. sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ +---- + +. Copy the node certificate and node private key by copying them to the `inbox` directory. ++ +[source, console] +---- +cd .. sudo cp ./public/chain.pem /opt/couchbase/var/lib/couchbase/inbox/chain.pem sudo cp ./private/pkey.key /opt/couchbase/var/lib/couchbase/inbox/pkey.key ---- - -. Ensure that all certificate and private key files in the `inbox` directory can be read by user `couchbase`. -This can be achieved by changing ownership of the files to `couchbase`, and setting `0600` permissions. ++ +NOTE: This example has a single node, so you created the node's certificate on the node where you'll deploy it. +Therefore, you can just copy the files into the correct directory using `cp`. +When creating certificates for multiple nodes, you must move the files to the node's filesystem to deploy them. +If you created all of the certificates on one node, you can use a command such as `scp` to copy the files from that node to the node the certificate is for. +Remember to create the `inbox` directory on each node as well. . Deploy the root certificate. -This is achieved by creating the directory `CA`, within the previously created `inbox` directory, and copying the root certificate into the `CA` directory. -Proceed as follows: +Couchbase Server expects to find the root certificate in a subdirectory named `CA` in the `inbox` directory. +Create the subdirectory and then copy the root CA file: + +[source, console] ---- sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/CA sudo cp ./ca.pem /opt/couchbase/var/lib/couchbase/inbox/CA/. ---- -. _Upload_ the root certificate for the cluster. -Use the following REST command: +. Make all files in the `inbox` directory readable by just the `couchbase` user: + +[source, console] +---- +sudo chown -R couchbase /opt/couchbase/var/lib/couchbase/inbox/* +sudo chmod -R 0700 /opt/couchbase/var/lib/couchbase/inbox/* +---- + +. Call the REST API to have Couchbase Server load the root certificate for the cluster: ++ +[source, console] ---- curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs -u Administrator:password ---- + -All root certificates currently resident in the `CA` directory are now placed in the trust store, and are ready for use. -This can be verified by means of Couchbase Web Console: access the *Security* screen, by means of the *Security* option in the left-hand navigation bar. -Then, left-click on the *Certificates* tab, located on the upper, horizontal navigation bar. +. Optionally, verify that Couchbase Server has added the new root CA to its trust store: ++ +-- +.. Sign into the Couchbase Server Web Console as a Full Administrator. +.. Click menu:Security[], and click menu:Certificates[] +-- ++ [#see-root-certificate-with-couchbase-web-console] -The screen's left-hand panel appears as follows: +In this example, you can see both the original automatically generated root certificate and the newly uploaded certificate. +The original generated root certificate appears at the top. + image::manage-security/rootCertificateWithSignedCert.png[600,align=left] + -The original _generated_ root certificate appears at the top. -A notification is now provided, to the effect that this `doesn't seem to be used by any node anymore.` -The new, _uploaded_ root certificate appears below. -The text of each certificate appears in the panel to the right. -Details on the certificate, and button for certificate-deletion, appear at the left. -Note that a certificate cannot be deleted once it has provided its authority to one or more node certificates on the cluster. +NOTE: You cannot delete a certificate if it has signed one or more node certificates that are in use in the cluster. +You can only delete the old autogenerated certificate after you have deployed new node certificates signed by the new root CA to each node. + -For further information on the *Certificates* tab on the *Security* screen, see xref:manage:manage-security/manage-security-settings.adoc#root-certificate-security-screen-display[Certificates]. +For more information about the *Certificates* tab on the *Security* screen, see xref:manage:manage-security/manage-security-settings.adoc#root-certificate-security-screen-display[Certificates]. -. _Load_ the node certificate that was copied into the `inbox`, with its private key: +. Load the node certificate and its private key by calling the xref:rest-api:upload-retrieve-node-cert.adoc[reloadCertificate] REST API: + +[source, console] ---- curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate -u Administrator:password ---- + -The node certificate is now activated for the current node, bearing the authority of the root CA with which it was signed. - -Note that when, as is typical, the cluster contains more than one node, this step must be performed on _each node_ of the cluster, with each individual IP address thereby specified in turn. +The node certificate is now activated for the current node, bearing the authority of the root CA. For more information using the REST API to manage certificates, see xref:rest-api:rest-certificate-management.adoc[Certificate Management API]. This includes details on retrieving root and nodes certificates that have been uploaded, and on certificate deletion. -[#configure-client-access-simple] -=== Configuring Client Access - -Once the cluster has been protected by the deployment of root and node certificates described above, a _client_ certificate can be signed by the root certificate, to allow a client to access the cluster. -Client-certificate preparation varies, depending on the type of client to be supported. -For steps to prepare a certificate supportive of Couchbase Server, see xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-a-root-certificate[Client Access: Root-Certificate Authorization]. -For steps to prepare a certificate supportive of a Java client, see xref:manage:manage-security/configure-client-certificates.adoc#java-client-access-root-certificate-authorization[Java Client Access: Root-Certificate Authorization]. - -Note that access by means of a client certificate must be specifically enabled, on the cluster that is to be accessed: see xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client-Certificate Handling]. +This example demonstrated configuring certificates for a single node database. +To deploy certificates for a multi-node cluster, repeat steps 6, 7, 9, 10, 11, 12, 15, and 18 for each node. +Remember that you must copy the node's certificate and key files to its own `inbox` directory to deploy them. [#root-intermediate-and-node-certificates] -== Cluster Protection with Root, Intermediate, and Node Certificates +== Create and Use Intermediate Certificates to Sign Node Certificates -Optionally, a root certificate can be used to sign an _intermediate_ certificate, which is then itself used to sign node certificates. -This increases security, since it minimizes use of the private key associated with the root certificate, when many node or client certificates are to be signed. +The previous example directly signed node certificates using the root certificate. +In some cases, you may want to use an intermediate certificate to sign the certificates for the nodes. +The primary reason to use an intermediate certificate is to prevent exposing the cluster's private key. -When a client attempts to access the cluster securely, it must be able to build the certificate chain used to convey the authority of the cluster's root CA (see xref:learn:security/certificates.adoc#intermediate-certificates[Intermediate Certificates]). -In Couchbase Server Version 7.1+, the certificates can be prepared for client inspection in either of two ways, which are: +For example, you may want to delegate the signing of node certificates. +By creating an intermediate certificate, you can keep the cluster's private key secret while allowing others to sign node certificates. +The administrators to whom you delegate the signing of node certificates can use the intermediate certificate for signing. +They do not need use to the cluster's private key to sign the node certificates. -* Concatenation of all intermediate and node certificates into a single _chain.pem_ file, which is uploaded from the node's _inbox_. +For more information, see xref:learn:security/using-multiple-cas.adoc#adding-intermediate-certificates-to-the-trust-store[Adding Intermediate Certificates to the Trust Store]. -* Upload, from the node's inbox, of a _chain.pem_ file containing only the unconcatenated node certificate; with the expectation that each intermediate certificate resides in the client's _trust store_. +When a peer (such as another node or a client) attempts to connect to a node securely, it uses the node's certificate to verify the node's identity. +The node can supply a chain of certificates to the peer in addition to its own. +To verify the node's identity, the peer searches for a CA it trusts in the chain of certificates from the node. +See xref:learn:security/certificates.adoc#intermediate-certificates[Intermediate Certificates] for more information. -Both procedures are shown below. -For more information, see xref:learn:security/using-multiple-cas.adoc#adding-intermediate-certificates-to-the-trust-store[Adding Intermediate Certificates to the Trust Store]. +In Couchbase Server you can supply the peer with the chain of trust it needs to identify the node in one of two ways: + +* Concatenation of all intermediate and node certificates into a single `chain.pem` file, which you deploy to the node. +The node provides this entire chain of trust to the peer when it tries to connect securely. -The steps and descriptions in the procedures below assume that the previous procedure, xref:manage:manage-security/configure-server-certificates.adoc#root-and-node-certificates[Cluster Protection with Root and Node Certificates], has already been successfully completed; and that familiarity with the basic certificate-related concepts explained there has been attained. +* Deploy a `chain.pem` file containing just the node's certificate. +In this case, the peer's trust store must already have all intermediate certificates that it needs to verify the node's identity. -Note that corresponding, subsequent procedures that create certificates for _client_-authentication are provided in xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-an-intermediate-certificate[Client Access: Intermediate Certificate Authorization] and xref:manage:manage-security/configure-client-certificates.adoc#java-client-access-intermediate-certificate-authorization[Java Client Access: Intermediate Certificate Authorization] +The following examples demonstrate both of these methods. +They assume that you have already completed the steps in xref:#root-and-node-certificates[Create and Deploy Cluster and Node Certificates]. [#intermediate-concatenation] -=== Deploying an Intermediate Certificate as Part of the Node's Chain +=== Deploy an Intermediate Certificate as Part of the Node's Trust Chain -Proceed as follows: +This example demonstrates creating root, node, intermediate, and client certificates. +It Concatenates these certificates together so the node can provide the client a complete chain of trust. -. On the node to be certificate-protected, create working directories: +. Open a command line shell on the node for which you want to create a certificate signed by an intermediate certificate. + +. In some directory, such as your home directory or `/tmp`, create working directories: + +[source, console] ---- mkdir servercertfiles2 cd servercertfiles2 mkdir -p {root,servers,clients}/{issued,reqs,private} ---- + -The directories `root`, `servers`, and `clients` will contain the issued certificates, requests, and private keys generated for the root, the individual nodes, and clients wishing to access the nodes. -Each directory therefore contains `issued`, `reqs`, and `private` subdirectories. +You'll use the `root`, `servers`, and `clients` directories to contain the certificates, requests, and private keys for the root, node, and client certificates. +The `issued`, `reqs`, and `private` subdirectories in these directories will contain the final certificates, the signing requests, and the private keys respectively. + -Note that this directory infrastructure will also be used in the subsequent process, xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-an-intermediate-certificate[Client Access: Intermediate Certificate Authorization]; where the contents of the `clients` directory will be created. +NOTE: The example xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-an-intermediate-certificate[Client Access: Intermediate Certificate Authorization] uses this directory structure. +It demonstrates creating the certificates that the clients need. -. Change directory to `root`. -Then, create a configuration file for the root certificate that is to be created. +. Change to the `root` directory and create a configuration file for the root certificate: + +[source, console] ---- cd root @@ -429,23 +391,32 @@ keyUsage = cRLSign, keyCertSign EOF ---- + -The `config` file has three sections. The first, `req`, specifies values to be passed to the `req` command, which is used to create and process certificate requests: use `man req` to obtain information on the values passed. -The second section, `cn_only`, provides specifications for the Common Name to be used in the certificate, including the maximum number of characters and the default name. -The third section, `ca_ext`, provides basic extensions that limit the capability of the certificate. -These include a value of `TRUE` for `CA`, indicating that the certificate will be able to provide signing authority for other certificates. -Additionally, the values for `keyUsage` are provided as `cRLSign`, indicating that the certificate's public key will be usable to verify signatures on _Certificate Revocation Lists_; and `keyCertSign`, indicating that the certificate's public key will be usable to verify signatures on other certificates. +The `config` file has three sections: ++ +* `[req]` specifies the values to pass to the `req` command. +This command creates and processes certificate requests. +To learn more about it and its arguments, use the command `man req`. +* `[cn_only]` provides specifications for the Common Name to used in the certificate, including the maximum number of characters and the default name. +* `[ca_ext]` provides basic extensions that limit the capability of the certificate. +Some of the settings in this section are: +** `basicConstraints CA:TRUE` makes the certificate capable of signing other certificates. +** `keyUsage = cRLSign, keyCertSign` has two effect. +The `cRLSign` value prevents the certificate's public key from being able to verify signatures on Certificate Revocation Lists. +And `keyCertSign` makes the certificate's public key able to verify signatures on other certificates. -. Create the root certificate, specifying the created `config` file. +. Create the root certificate, passing in the `config` file you just created: + +[source, console] ---- openssl req -config config -new -x509 -days 3650 -sha256 -newkey rsa:2048 \ --keyout ca.key -out ca.pem -subj '/C=UA/O=MyCompany/CN=RootCA' + -keyout ca.key -out ca.pem -subj '/C=UA/O=MyCompany/CN=RootCA' ---- + -This specifies that both the root certificate for the cluster and its private key be created. -The key is additionally specified to be encrypted. -In consequence, during execution, the following prompt is displayed: +This command creates both the root certificate for the cluster in a file named `ca.pem` file, and the private key in a file named `ca.key`. +The `-keyout` argument tells `openssl` to password protect the private key. +When executing the command, `openssl` prompts you for a pass phrase: + +[source, console] ---- Generating a 2048 bit RSA private key ....+++ @@ -454,19 +425,12 @@ writing new private key to 'ca.key' Enter PEM pass phrase: ---- + -This requires that a _pass phrase_ be entered, for inclusion of the key in command-line procedures, such as those used for certificate generation. -The phrase will be stored in the certificate, and prompted for whenever administrative access is attempted. -Enter an appropriate phrase: a second prompt then appears, requesting confirmation of the phrase. -Enter the phrase again, and the operation completes. -+ -The output file, `ca.pem` is the root certificate for the cluster, and is saved in the `root` folder. -(Note that in the steps that follow, other certificates named `ca.pem` are created in additional folders: these should not be confused with the certificate of the same name in `root`.) +Anyone trying to use the certificate's private key must enter this passphrase. -. Create an extensions file that will limit the capabilities of the _intermediate_ certificate that is to be created. -+ +. Create an extensions file to limit the capabilities of the intermediate certificate that you create in the next step: [#create-intermediate-extensions-file] -Enter the following: + +[source, console] ---- cat > int.ext <> temp.ext ---- + -This creates `temp.ext` as an extension file that will be used for one node only. -The file specifies the IP address specific to the node. -Note that in Couchbase Enterprise Server Version 7.2+, the node-name _must_ be correctly identified in the node certificate as a Subject Alternative Name. +The newly created `temp.ext` file adds the node's IP address as a Subject Alternative Name to the certificate. +In Couchbase Enterprise Server Version 7.2 and later, you must add a Subject Alternative Name to the certifcate which indentifies the node. +If the certificate's Subject Alternative Name does not match the node's identity in the cluster, Couchbase Server returns an error if you try to load the certificate. For information and options, see xref:learn:security/certificates.adoc#server-certificate-validation[Server Certificate Validation]. -. Create the node certificate for an individual node, specifying the unique extension file for the node, and specifying the intermediate certificate and key as the signing authority. +. Create the node certificate for the node by signing the certification request you just created using the intermediate certificate: + +[source, console] ---- openssl x509 -CA int.pem -CAkey int.key -CAcreateserial \ --CAserial serial.srl -days 365 -req -in reqs/couchbase.node.svc.csr \ --out issued/couchbase.node.svc.pem -extfile temp.ext + -CAserial serial.srl -days 365 -req -in reqs/couchbase.node.svc.csr \ + -out issued/couchbase.node.svc.pem -extfile temp.ext ---- + -Since this specifies that the certificate should be signed by the encrypted intermediate key, `int.key`, a prompt appears, requesting the appropriate pass phrase. -Enter the phrase against the prompt. +Because you're using the intermediate certificate in this signing request, `openssl` prompts you to enter the pass phrase for the intermediate certificate's private key. + -The node-certificate file `couchbase.node.svc.pem` is hereby saved in the `issued` folder. -The certificate bears the constraints specified in `temp.ext`, and is granted the authority of the intermediate certificate and key, which are `int.pem` and `int.key` respectively. +The command creates the node's certificate as the file `issued/couchbase.node.svc.pem` . [[check-validity]]Check that the node certificate is valid. The following use of the `openssl` command verifies the relationship between the root certificate, the intermediate certificate, and the node certificate. + +[source, console] ---- openssl verify -trusted ../root/ca.pem -untrusted int.pem \ -issued/couchbase.node.svc.pem + issued/couchbase.node.svc.pem ---- + -If the certificate is valid, the following output is displayed: +The command outputs the following if the certificate passes the validity check: + ---- issued/couchbase.node.svc.pem: OK ---- -. Prepare to deploy the certificate and private key for the node. -First, concatenate the node certificate and the intermediate certificate, to establish the chain of authority. -Then, rename the private key for the node. +. Prepare the node's certificate for upload by creating the `chain.pem` certificate file. +You create `chain.pem` by concatenating the node certificate and the intermediate certificate to establish the chain of authority. +Couchbase Server expects the node's certificate file to be named `chain.pem`. + +[source, console] ---- cat issued/couchbase.node.svc.pem int.pem > chain.pem +---- +. Create a copy of the node's private key named `pkey.key` for deployment to the node. +Couchbase Server expects the node's private key to have this filename. ++ +[source, console] +---- cp private/couchbase.node.svc.key pkey.key ---- -. Move the node certificate and node private key into the `inbox` for the current node. +. Move the node certificate and node private key into the `inbox` directory for the current node. + +[source, console] ---- -sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ # if needed +sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ sudo cp ./chain.pem /opt/couchbase/var/lib/couchbase/inbox/chain.pem sudo cp ./pkey.key /opt/couchbase/var/lib/couchbase/inbox/pkey.key ---- -. Ensure that all certificate and private key files in the `inbox` directory can be read by user `couchbase`. -This can be achieved by changing ownership of the files to `couchbase`, and setting `0600` permissions. - . Move the root certificate into the `inbox/CA` directory for the current node. + +[source, console] ---- -sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/CA/ # if needed +sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/CA/ cd ../root sudo cp ca.pem /opt/couchbase/var/lib/couchbase/inbox/CA/. ---- -. Upload the root certificate, thereby activating it for the entire cluster. +. Make all certificate and private key files in the `inbox` readable by the `couchbase` user. + +[source, console] ---- -curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs -u Administrator:password +sudo chown -R couchbase /opt/couchbase/var/lib/couchbase/inbox/* +sudo chmod -R 0700 /opt/couchbase/var/lib/couchbase/inbox/* ---- -. Upload the node certificate, specifying the established password for the private key. +. Upload the root certificate, activating it for the entire cluster. + +[source, console] ---- -curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate -u Administrator:password +curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs \ + -u Administrator:password ---- -+ -Note that when, as is typical, the cluster contains more than one node, the `/node/controller/reloadCertificate` command must be executed on each node, specifying the IP address of the node on which execution is occurring. -This concludes the certificate-deployment process. -The root certificate can be examined by means of Couchbase Web Console, as shown in xref:manage:manage-security/configure-server-certificates.adoc#see-root-certificate-with-couchbase-web-console[Step 13] of the previous example on this page. +. Upload the node certificate. ++ +[source, console] +---- +curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate \ + -u Administrator:password +---- For more information using the REST API to manage certificates, see xref:rest-api:rest-certificate-management.adoc[Certificate Management API]. [#intermediate-upload] -=== Deploying an Intermediate Certificate via Trust Store +=== Deploy an Intermediate Certificate via Peer's Trust Store -Proceed as follows: +The following example creates an intermediate certificate but does not concatenate it with the node's certificate. +After following these steps, any peer attempting to make a secure TLS connection to the node must have the intermediate certificate in its trust store. +These peers include clients making secure connections and other nodes in the Couchbase Server cluster. +Adding the intermediate certificate to the peer's trust store makes sure the peer can establish a chain of trust from the node's certificate to a CA that it trusts. -. Perform all steps listed in the section xref:manage:manage-security/configure-server-certificates.adoc#intermediate-concatenation[Representing Intermediate Certificates through Concatenation], above; up to and including the step xref:#check-validity[Check that the node certificate is valid]. +. Perform all steps listed in the section xref:manage:manage-security/configure-server-certificates.adoc#intermediate-concatenation[Deploy an Intermediate Certificate as Part of the Node's Chain] up to and including step #14, xref:#check-validity[Check that the node certificate is valid]. . Prepare to deploy the certificate and private key for the node, by renaming both: + @@ -657,15 +637,12 @@ cp private/couchbase.node.svc.key pkey.key . Move the renamed node certificate and private key into the `inbox` for the current node. + ---- -sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ # if needed +sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ sudo cp ./chain.pem /opt/couchbase/var/lib/couchbase/inbox/chain.pem sudo cp ./pkey.key /opt/couchbase/var/lib/couchbase/inbox/pkey.key ---- -. Ensure that all certificate and private key files in the `inbox` directory can be read by user `couchbase`. -This can be achieved by changing ownership of the files to `couchbase`, and setting `0600` permissions. - . Move the root certificate and the intermediate certificate into the `inbox/CA` directory for the current node. + ---- @@ -675,96 +652,216 @@ cd ../root sudo cp ca.pem /opt/couchbase/var/lib/couchbase/inbox/CA/. ---- +. Make sure that all certificate and private key files in the `inbox` directory can be read by user `couchbase`. ++ +[source, console] +---- +sudo chown -R couchbase /opt/couchbase/var/lib/couchbase/inbox/* +sudo chmod -R 0700 /opt/couchbase/var/lib/couchbase/inbox/* +---- + . Upload the root and intermediate certificates. + +[source, console] ---- -curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs -u Administrator:password +curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs \ + -u Administrator:password ---- -. Upload the node certificate, specifying the established password for the private key. +. Upload the node certificate. + +[source, console] ---- -curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate -u Administrator:password +curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate + -u Administrator:password ---- ++ +NOTE: When the cluster contains more than one node, you must repeat the call to `/node/controller/reloadCertificate` for each node. +Be sure to use the IP address of each node in the POST URL to have each node reload its certificates. +Also, copy the files to the node's inbox on its own filesystem. +The files must be on the node for the REST API call to work. -Note that when, as is typical, the cluster contains more than one node, the `/node/controller/reloadCertificate` command must be executed on each node, specifying the IP address of the node on which execution is occurring. +The node's certificate is now deployed. +Remember that it does not contain the intermediate certificate. +For a peer to identify the node, it must have a copy of the intermediate certificate in its trust store. +Without it, the peer cannot establish a chain of trust from the node to the root CA. +To make sure other nodes in the cluster can identify the node, add the intermediate certificate to the Couchbase Server's trust store. +For other clients, consult their documentation to determine how to add the intermediate certificate to their trust stores. -This concludes the certificate-deployment process. -The root certificate can be examined by means of Couchbase Web Console, as shown in xref:#see-root-certificate-with-couchbase-web-console[Step 13] of the previous example on this page. For more information using the REST API to manage certificates, see xref:rest-api:rest-certificate-management.adoc[Certificate Management API]. -=== Using an Encrypted, Private Node-Key +[#pkcs12] +== Deploy a Certificate and Private Key to a Node in a PKCS #12 File -The above examples use an _unencrypted_ private key, for the node. -If an _encrypted_ private node-key is used, a passphrase must be registered for it, so that the key can be securely retrieved and used when required. -See the reference page xref:rest-api/upload-retrieve-node-cert.adoc[Upload and Retrieve a Node Certificate]. +PKCS #12 format certificates let you bundle certificates, private keys, and other objects into a single file. +Couchbase Server supports using PKCS #12 files for deploying certificates, private keys, and certificate chains for nodes. +It does not support using them for other purposes, such as client or root certificates. -[#configure-client-access-advanced] -=== Configuring Client Access +Couchbase Server requires that the PKCS #12 file be in the node's `inbox` directory with the filename `couchbase.p12`. -Once the cluster has been protected by the deployment of root, intermediate, and node certificates described above, a _client_ certificate can be signed by a _client-intermediate_ certificate that itself inherits the authority of the root: this allows the client certificate to access the cluster. -Client-certificate preparation varies, depending on the type of client to be supported. -For steps to prepare a certificate supportive of Couchbase Server, see xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-an-intermediate-certificate[Client Access: Intermediate-Certificate Authorization]. -For steps to prepare a certificate supportive of a Java client, see xref:manage:manage-security/configure-client-certificates.adoc#java-client-access-intermediate-certificate-authorization[Java Client Access: Intermediate-Certificate Authorization]. +The following example demonstrates how to bundle the node's certificate and private key into a PKCS #12 file and deploy it on a node. -Note that access by means of a client certificate must be specifically enabled, on the cluster that is to be accessed: see xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client-Certificate Handling]. +. Follow steps 1 through 10 in the xref:#root-and-node-certificates[Create and Deploy Cluster and Node Certificates] example. +When you complete these steps you'll have certificates and private keys for the cluster and the node. -[#protection-of-multi-node-clusters] -== Protection of Multi-Node Clusters +. Bundle the node's certificate and private key into a single PKCS #12 file: ++ +[source, console] +---- +openssl pkcs12 -export -out couchbase.p12 -inkey private/couchbase.default.svc.key + -in public/couchbase.default.svc.pem +---- ++ +The arguments in this command are: ++ +-- +* `pkcs12` tells `openssl` you want to work with a PCKS #12 certificate. +* `-export` tells `openssl` you want to create a new certificate. +* `-out couchbase.p12` sets the output filename. +The file is saved in the current directory with the name Couchbase Server expects for a PKCS #12 certificate. +* `-inkey private/couchbase.default.svc.key` tells the command to import the node's private key from the file you created earlier. +It also has `openssl` password protect the private key. +* `-in public/couchbase.default.svc.pem` tells the command where to find the node's certificate. +-- ++ +The command prompts you to enter a password for the private key twice. -When the certificate-management procedures described above are used, as intended, for multi-node clusters, the following should be observed: +. If the node to which you're deploying the certificate does not have an inbox directory, create it. ++ +[source, console] +---- +sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ +---- -* Each CA certificate to be used by the cluster must be copied into an appropriately located `inbox/CA` directory on a cluster node, and must be loaded from there, using the call demonstrated above, and fully described in xref:rest-api:load-trusted.cas.adoc[Load Root Certificates]. +. Copy the PKCS #12 certificate to the node's inbox: ++ +[source, console] +---- +sudo cp couchbase.p12 /opt/couchbase/var/lib/couchbase/inbox/ +---- ++ +Make sure there are no other certificate files in the `inbox` directory. +If Couchbase Server finds both a `couchbase.p12` and `pkey.key` in the inbox directory, it cannot tell which file you intend to use for the certificate. +In this case, it returns an error when you try to upload the certificate to the node. + +. Deploy the root certificate. +Couchbase Server expects to find the root certificate in a subdirectory named `CA` in the `inbox` directory. +Create the subdirectory and then copy the root CA file: ++ +[source, console] +---- +sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/CA +sudo cp ./ca.pem /opt/couchbase/var/lib/couchbase/inbox/CA/. +---- + +. Make all files in the `inbox` directory readable by just the `couchbase` user: ++ +[source, console] +---- +sudo chown -R couchbase /opt/couchbase/var/lib/couchbase/inbox/* +sudo chmod -R 0700 /opt/couchbase/var/lib/couchbase/inbox/* +---- + +. Call the REST API to have Couchbase Server load the root certificate for the cluster: ++ +[source, console] +---- +curl -X POST http://10.143.192.102:8091/node/controller/loadTrustedCAs -u Administrator:password +---- ++ + +. Load the node certificate and its private key by calling the xref:rest-api:upload-retrieve-node-cert.adoc[reloadCertificate] REST API. +Because an earlier step password protected the private key, you must pass the password for it as an argument to the REST API call: ++ +[source, console] +---- +curl -X POST http://10.143.192.102:8091/node/controller/reloadCertificate \ + -u Administrator:password + -d '{"privateKeyPassphrase": {"type": "plain", "password": "private-key-password"}}' +---- ++ +The JSON value you pass to the command supplies the password for the private key in the PKCS #12 certificate as plain text. +Replace the `private-key-password` with the password you entered in step 2. ++ +IMPORTANT: This example sends the private key's password in plaintext for simplicity. +In a production environment, consider using a more secure method of sending this password. +See xref:rest-api:upload-retrieve-node-cert.adoc#json-passphrase-registration[JSON Passphrase Registration] + +Couchbase Server extracts the private key and certificate from the `couchbase.p12` file and activates them on the node. -* A separate `chain.pem` must be prepared for each node. -Each `chain.pem` should be generated from a new, unique private key (`pkey.key`); must be an appropriate concatenation of the node certificate with whatever intermediate certificates have formed its chain; and must have its own node's IP address specified as a `subjectAltName`. +This example has the node's certificate directly signed by the root certificate. +If instead you need to use one or more intermediate certificates to sign the node's certificate, you can choose to include them to establish a chain of trust. +You can include a chain of intermediate certificates by adding a `-chain` argument to the `openssl` command in step 2. +See OpenSSL's https://www.openssl.org/docs/manmaster/man1/openssl-pkcs12.htmlp[openssl-pkcs12^] documentation for documentation on `-chain` and other arguments. -* If created on the same system as all other keys and certificates, the `chain.pem` and `pkey.key` for each node must be independently transferred onto the node they are intended to protect. -An inbox must be created on that node, and the `chain.pem` and `pkey.key` files then moved there. -* The node certificate must be reloaded individually for each node in the cluster, after the `chain.pem` and `pkey.key` file have been moved into the node's inbox. -Each reload command must therefore specify the node's own IP address. +== Encrypted Node Private Keys + +You can choose to encrypt the private key for nodes when uploading them. +You must register the passphrase so that the key can be securely retrieved and used when required. +See xref:rest-api/upload-retrieve-node-cert.adoc[Upload and Retrieve a Node Certificate] for details. + +[#configure-client-access-advanced] +== Configuring Client Access + +Once you have configured root, intermediate, and node certificates for the cluster, you can create client certificates so clients can securely connect. +You can choose to create an intermediate client certificate that itself inherits the authority of the root. +Client-certificate preparation varies, depending on the type of client. +For steps to prepare a client certificate to support connections between Couchbase Server databases, see xref:manage:manage-security/configure-client-certificates.adoc#client-certificate-authorized-by-an-intermediate-certificate[Client Access: Intermediate-Certificate Authorization]. +For steps to prepare a certificate for a Java client, see xref:manage:manage-security/configure-client-certificates.adoc#java-client-access-intermediate-certificate-authorization[Java Client Access: Intermediate-Certificate Authorization]. + +NOTE: Client connections secured by client certificate must be enabled on the cluster. +See xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client-Certificate Handling]. + +[#using-an-externally-provided-root-certificate] +== Using an Externally Provided Root Certificate + +The examples in this page create a self-signed root certificate and use that certificate's private key to sign other certificates. +In production environments, you often want to use a node certificate signed by a well-known Certificate Authority. +In this case, the CA provides the root, intermediate, and node certificates for you. +The intermediate certificate is optional. [#adding-new-nodes] == Adding and Joining New Nodes -If a cluster uses _system-generated_ certificates, which Couchbase Server provides by default, no certificate-related work needs to be performed in order to add or join a new node to the cluster. -However, once a cluster is using _uploaded_ certificates, a node that is to be added or joined must itself be provisioned with conformant certificates, before addition or joining can be successfully performed: this means that the appropriate _chain_ file (containing the node certificate) and _private key_ must have been placed in the node's `inbox`, and the appropriate REST API then called. -From Couchbase Server Version 7.1, the new node is now always added or joined over an _encrypted_ connection. - -Note also that when a cluster is using uploaded certificates, and a new node is added or joined to a cluster, the operation is performed with reference to a particular node that is already a member of the cluster. -Since this _cluster node_ and this _new node_ must be able to connect with one another, each must trust the CA of the other. -Therefore: +When a cluster uses the default auto-generated certificates, you do not need to generate a new certificate for new nodes. +Once you configure the cluster to use custom certificates, you must generate a new certificate when adding or joining new nodes to the cluster. +In Couchbase Server always adds or joins new nodes over an encrypted connection. -* If the two nodes already have the same CA, connection and node-addition (or node-joining) can occur. +When a cluster using custom certificates adds or joins a new node to itself, the new node must interact with an existing node. +This interaction requires both the existing node and new node verify each other's identity using their chains of trust. +The easiest way to make sure the nodes can identify each other by signing them with the same root certificate or the same intermediate certificate. +Otherwise, make sure each node's trust store contain the intermediate or CA that signed the other node's certificate. -* If the two nodes do _not_ have the same CA, the CA of each must be loaded onto the other; after which, connection and node-addition (or node-joining) can occur. [#readding-a-previously-removed-node] -=== Re-Adding a Previously Removed Node +=== Re-Adding Node -When a node is removed from a cluster, its configuration is deleted. -If the removed node is subsequently re-added to the cluster, it is added as a new node, with a new definition of its configuration. -Consequently, the appropriate root certificate and chain certificate for the node must again be loaded. +When you remove a node from a cluster, Couchbase Server deletes its configuration including its certificates chains. +If you add the removed node back to the cluster, Couchbase Server adds it as a new node with a new configuration. +Therefore, you must make sure node has the appropriate root certificate and chain certificate. -For more information on node removal, see xref:learn:clusters-and-availability/removal.adoc[Removal]. +For more information about removing nodes, see xref:learn:clusters-and-availability/removal.adoc[Removal]. [#regenerating-default-certificates] == Regenerating Default Certificates -_Default_ certificates provided automatically by Couchbase Server — including the _root_ certificate and each of the _node_ certificates for the cluster — can be _regenerated_ at any time, by means of the REST API. -This means that the current node certificates and (if they have been uploaded) intermediate certificates are removed; and new, system-generated root and node certificates are made active for the node. +When it creates the cluster, Couchbase Server generates default certificates for the cluster and initial node. +It also generates certificates for additional nodes you add later. +You can have Couchbase Server regenerate the certificates using a the REST API call. +This call has Couchbase Server generate a new self-signed root certificate and add it to its trust store. +It then creates new node certificates signed by the new root certificate, overwriting existing node certificates. +Any old auto-generated and custom root certificates remain in the cluster's trust store. -Note that previously system-generated and uploaded root certificates remain in the trust store of the cluster, unless explicitly deleted. -For information on regenerating certificates, see xref:rest-api:rest-regenerate-all-certs.adoc[Regenerate All Certificates]. -For information on deleting root certifictes, see xref:rest-api:delete-trusted-cas.adoc[Delete Root Certificates]. +For information about regenerating certificates, see xref:rest-api:rest-regenerate-all-certs.adoc[Regenerate All Certificates]. +For information about deleting root certificates, see xref:rest-api:delete-trusted-cas.adoc[Delete Root Certificates]. [#further-information] == Further Information -For information on certificate-management by means of the REST API, see xref:cli:cbcli/couchbase-cli-ssl-manage.adoc[ssl-manage] and xref:rest-api:rest-certificate-management.adoc[Certificate Management API]. +For information about certificate-management using the REST API, see xref:cli:cbcli/couchbase-cli-ssl-manage.adoc[ssl-manage] and xref:rest-api:rest-certificate-management.adoc[Certificate Management API]. -For step-by-step instructions on creating _client_ certificates, see xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. +For step-by-step instructions on creating client certificates, see xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates]. -For an example of using the certificates and keys created on the current page and on xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates] to secure an _XDCR replication_, see xref:manage:manage-xdcr/enable-full-secure-replication.adoc#specify-full-xdcr-security-with-certificates[Specify Root and Client Certificates, and Client Private Key]. +For an example of using node and xref:manage:manage-security/configure-client-certificates.adoc[client certificates] to secure XDCR replication between clusters, see xref:manage:manage-xdcr/enable-full-secure-replication.adoc#specify-full-xdcr-security-with-certificates[Specify Root and Client Certificates, and Client Private Key]. diff --git a/modules/manage/pages/manage-security/manage-tls.adoc b/modules/manage/pages/manage-security/manage-tls.adoc index 50c0b7575c..f0d67306a2 100644 --- a/modules/manage/pages/manage-security/manage-tls.adoc +++ b/modules/manage/pages/manage-security/manage-tls.adoc @@ -24,15 +24,17 @@ These areas are described in detail in xref:learn:security/on-the-wire-security. [#security-settings] == On-the-Wire Security Settings -Three configurable, on-the-wire security settings are provided both globally and per service. -They are as follows: +You can set the following three options globally and on a per-service basis. +Settings at the service level override the global setting for the service. * `tlsMinVersion`. -Specifies the minimum accepted TLS version: the server will not accept client connections with protocols below the level of the established, minimum version. -The value can be `tlsv1`, `tlsv1.1`, `tlsv1.2` (the default), or `tlsv1.3`. -Note, however, that `tlsv1` and `tlsv1.1` are _deprecated_ in Couchbase Server Version 7.2. +Specifies the minimum accepted TLS version. +The server rejects client connections with protocols using a version earlier than the minimum version. +The value can be `tlsv1.2` (the default) or `tlsv1.3`. + -This parameter can be established both globally and per service. +NOTE: The values `tlsv1` and `tlsv1.1` were deprecated in Couchbase Server 7.2, and are no longer supported by Couchbase Server 7.6 and later. ++ +This parameter can set globally and per service. * `honorCipherOrder`. Specifies whether the service uses its own cipher-suite preference, rather than the client's. @@ -116,11 +118,11 @@ The Couchbase CLI allows cluster-wide on-the-wire security-settings to be retrie [#get-cluster-wide-settings-with-the-cli] === Get Cluster-Wide Settings, with the CLI -The _cluster-wide_ security configuration includes both _global_ and _per service_ settings. -The current configuration can be retrieved with the xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] command. -This is shown by the following example. -Note that the output is piped to the https://stedolan.github.io/jq[jq^] command, to optimise the output's readability: +The cluster-wide security configuration includes both global and per service settings. +You can view the current configuration using the xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] command. +The following example pipes this command's output to the https://stedolan.github.io/jq[jq^] command to make the output more readable: +[source, console] ---- /opt/couchbase/bin/couchbase-cli setting-security \ -c 10.144.210.101:8091 \ @@ -129,22 +131,38 @@ Note that the output is piped to the https://stedolan.github.io/jq[jq^] command, --get | jq '.' ---- -If successful, the command returns output such as the following: - +If successful, the command returns output similar to the following: +[source, json] ---- { "disableUIOverHttp": false, "disableUIOverHttps": false, "disableWWWAuthenticate": false, - "tlsMinVersion": "tlsv1", + "responseHeaders": [], + "tlsMinVersion": "tlsv1.2", "cipherSuites": [], "honorCipherOrder": true, + "allowNonLocalCACertUpload": false, + "allowedHosts": [ + "*" + ], + "passwordHashAlg": "argon2id", + "allowHashMigrationDuringAuth": false, + "scramSha1Enabled": true, + "scramSha256Enabled": true, + "scramSha512Enabled": true, + "argon2idTime": 3, + "argon2idMem": 8388608, + "pbkdf2HmacSha512Iterations": 10000, + "scramShaIterations": 15000, + "intCredsRotationInterval": 1800000, + "validateNodeCertSan": true, "data": { "supportedCipherSuites": [ "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", - . - . + . + . "TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256" ] }, @@ -152,8 +170,8 @@ If successful, the command returns output such as the following: "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", - . - . + . + . "TLS_CHACHA20_POLY1305_SHA256" ] }, @@ -161,8 +179,8 @@ If successful, the command returns output such as the following: "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", - . - . + . + . "TLS_CHACHA20_POLY1305_SHA256" ] }, @@ -170,8 +188,8 @@ If successful, the command returns output such as the following: "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", - . - . + . + . "TLS_CHACHA20_POLY1305_SHA256" ] }, @@ -179,8 +197,8 @@ If successful, the command returns output such as the following: "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", - . - . + . + . "TLS_CHACHA20_POLY1305_SHA256" ] }, @@ -188,28 +206,27 @@ If successful, the command returns output such as the following: "supportedCipherSuites": [ "TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", - . - . - "TLS_EMPTY_RENEGOTIATION_INFO_SCSV" + . + . + "TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256" ] }, "backup": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", - "TLS_RSA_WITH_AES_128_CBC_SHA", - . - . + . + . "TLS_CHACHA20_POLY1305_SHA256" ] }, "clusterManager": { "supportedCipherSuites": [ - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", - . - . - "TLS_RSA_WITH_3DES_EDE_CBC_SHA" + "TLS_AES_256_GCM_SHA384", + "TLS_AES_128_GCM_SHA256", + . + . + "TLS_RSA_WITH_RC4_128_MD5" ] } } @@ -217,9 +234,9 @@ If successful, the command returns output such as the following: The returned object contains attribute-value pairs that represent the current cluster-wide on-the-wire security configuration. -For information on the first three attributes shown in this example — `disableUIOverHttp`, `disableUIOverHttps`, and `disableWWWAuthenticate` — see the CLI reference page for xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security]; and the REST reference page xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security]. +For information about the first three attributes shown in this example--`disableUIOverHttp`, `disableUIOverHttps`, and `disableWWWAuthenticate`--see xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] and the REST reference page xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security]. -The `tlsMinVersion` is shown as set to `tlsv1`. +The `tlsMinVersion` is shown as set to the default `tlsv1.2`. The value of `honorCipherOrder` is the default, which is `true`. No custom cipher-suite list has been provided as the value of `cipherSuites`: accordingly, the array is empty. diff --git a/modules/manage/pages/manage-settings/configure-alerts.adoc b/modules/manage/pages/manage-settings/configure-alerts.adoc index 48c4618d82..b5596bf51f 100644 --- a/modules/manage/pages/manage-settings/configure-alerts.adoc +++ b/modules/manage/pages/manage-settings/configure-alerts.adoc @@ -8,14 +8,14 @@ [#configuring-email-alerts] == Configuring Alerts -Alerts can be dispatched automatically by Couchbase Server, in order to highlight specific issues and problems. -When an issue arises, one or both of the following can occur, based on user-configuration: +Alerts can be dispatched automatically by Couchbase Server, to highlight specific issues and problems. +When an issue arises one or both of the following can occur based on user configuration: * The alert is sent as an email by Couchbase Server to a configured SMTP server. From there, the email is forwarded to a configured list of email recipients. All cluster-nodes must have network access to the configured SMTP server, for the system to be fully effective. -* The alert appears as a pop-up, within the Couchbase Web Console of its recipient. +* The alert appears as a pop-up, within the Couchbase Server Web Console of its recipient. Only Full Administrators and Cluster Administrators can configure email alerts. Configuration can be performed with @@ -112,7 +112,7 @@ The listed alerts are as follows. [#table_alerts,cols="2,3,2"] |=== -| Alert | Description | Code +| Alert | Description | REST API Name | Node was auto-failed-over | The sending node has been failed over automatically. @@ -180,6 +180,15 @@ With no memory left for storing metadata, further requests to store data will al | The disk usage worker is stuck and unresponsive. | `disk_usage_analyzer_stuck` +| Certificate has expired +| A root, node, or XDCR security certificate has expired. +| `cert_expired` + +| Certificate will expire soon +| A root, node, or XDCR security certificate expires within a warning period. +The default warning period is 30 days. +| `cert_expires_soon` + | Memory usage threshold exceeded | System memory use as a percentage of total available memory has exceeded a threshold. Note that a warning-level alert is issued when system memory, as a percentage of total available memory, exceeds the _warning_ threshold (90% by default). @@ -259,7 +268,7 @@ This example demonstrates flags that specify mail-server password, sender, recip Emails settings are enabled with the `enabled` flag; and encryption is specified as off, by means of the `emailEncrypt` flag. A list of the alerts that can be sent is provided as the value of the `alerts` flag. A list of the pop-up alerts that can be sent is provided as the value of the `pop_up_alerts` flag. -See the *Code* column of the xref:manage:manage-settings/configure-alerts.adoc#available-alerts[Available Alerts] table, above, for additional event-codes. +See the Rest API Name column of the xref:manage:manage-settings/configure-alerts.adoc#available-alerts[Available Alerts] table for event codes. See xref:manage:manage-settings/configure-alerts.adoc#email-settings[Email Settings], above, for a description of available email settings. For more information on configuring alerts by means of the REST API, see xref:rest-api:rest-cluster-email-notifications.adoc[Setting Alerts]. diff --git a/modules/rest-api/pages/rest-cluster-email-notifications.adoc b/modules/rest-api/pages/rest-cluster-email-notifications.adoc index ff4ec35240..369d3f1e3a 100644 --- a/modules/rest-api/pages/rest-cluster-email-notifications.adoc +++ b/modules/rest-api/pages/rest-cluster-email-notifications.adoc @@ -30,7 +30,7 @@ When an issue arises, an alert is generated, and one or both of the following ca From there, the email is forwarded to a configured list of email recipients. All cluster-nodes must have network access to the configured SMTP server, for the system to be fully effective. -* The alert appears as a pop-up, within Couchbase Web Console. +* The alert appears as a pop-up, within Couchbase Server Web Console. To configure alerts, either the Full Admin or Cluster Admin role is required. @@ -46,10 +46,10 @@ The `POST /settings/alerts/sendTestEmail` method and URI configure dispatch of a == Curl Syntax ---- -curl -X GET -u http://:8091/settings/alerts +curl -X GET http://:8091/settings/alerts -u : -curl -X POST -u http://:8091/settings/alerts +curl -X POST http://:8091/settings/alerts -u : -d emailPass= -d sender= @@ -61,11 +61,12 @@ curl -X POST -u http://:8091/settings/alerts -d pop_up_alerts=<[alert-name]*> -d enabled=[ true | false ] -curl -X GET -u http://:8091/settings/alerts/limits +curl -X GET http://:8091/settings/alerts/limits -u : curl -X POST http:///settings/alerts/limits -u : + -d certExpirationDays = -d historyWarningThreshold= -d lowIndexerResidentPerc= -d maxDiskUsedPerc= @@ -135,6 +136,11 @@ Enables or disables alerts: the value can be `true` or `false` (the default). This parameter is optional. If alerts are enabled, any alert that appears in the list that is passed as the value of `alerts` or `pop_up_alerts` (see immediately below) will have an email and/or pop-up display generated as appropriate. +* `certExpirationDays`. +The number of days before a certificate's expiration date that Couchbase Server sends an alert. +Couchbase Server also sends an alert when a certificate expires. +See xref:learn:security/certificates.adoc#certificate-expiration[Certificate Expiration] for more information. + * `historyWarningThreshold`. Warns that the change history for one of the buckets is becoming full, across one or more vBuckets. (The size of the change history is administrator-specified for the whole bucket.) @@ -309,14 +315,18 @@ If successful, this returns `200 OK` and an object such as the following: ---- { + "certExpirationDays": 30, "historyWarningThreshold": 90, "lowIndexerResidentPerc": 10, "maxDiskUsedPerc": 90, "maxIndexerRamPerc": 75, "maxOverheadPerc": 50, - "memoryCriticalThreshold": 95, + "memcachedSystemConnectionWarningThreshold": 90, + "memcachedUserConnectionWarningThreshold": 90, + "memoryCriticalThreshold": 90, "memoryNoticeThreshold": -1, - "memoryWarningThreshold": 90 + "memoryWarningThreshold": 85, + "stuckRebalanceThresholdKV": "undefined" } ---- @@ -325,7 +335,7 @@ The `memoryWarningThreshold` can be reconfigured as follows: ---- curl -v -X POST http://localhost:8091/settings/alerts/limits \ --d "memoryWarningThreshold=85" \ +-d "memoryWarningThreshold=89" \ -u Administrator:password | jq '.' ---- @@ -333,14 +343,18 @@ If the call is successful, the following output is returned: ---- { + "certExpirationDays": 30, "historyWarningThreshold": 90, "lowIndexerResidentPerc": 10, "maxDiskUsedPerc": 90, "maxIndexerRamPerc": 75, "maxOverheadPerc": 50, - "memoryCriticalThreshold": 95, + "memcachedSystemConnectionWarningThreshold": 90, + "memcachedUserConnectionWarningThreshold": 90, + "memoryCriticalThreshold": 90, "memoryNoticeThreshold": -1, - "memoryWarningThreshold": 85 + "memoryWarningThreshold": 89, + "stuckRebalanceThresholdKV": "undefined" } ---- diff --git a/modules/rest-api/pages/rest-setting-security.adoc b/modules/rest-api/pages/rest-setting-security.adoc index e095bddfb6..4c3abfb275 100644 --- a/modules/rest-api/pages/rest-setting-security.adoc +++ b/modules/rest-api/pages/rest-setting-security.adoc @@ -38,7 +38,7 @@ curl -X POST -u : -d allowedHosts= -d allowNonLocalCACertUpload= -d clusterEncryptionLevel= - -d tlsMinVersion= + -d tlsMinVersion= -d honorCipherOrder= -d cipherSuites= -d [scramSha1Enabled|scramSha256Enabled|scramSha512Enabled]= @@ -102,11 +102,11 @@ Before applying `strict`, see xref:rest-api:rest-setting-security.adoc#enforcing * `tlsMinVersion`. Specifies the minimum TLS version accepted by the cluster. -Can be `tlsv1`, `tlsv1.1`, `tlsv1.2`, or `tlsv1.3`. -Note, however, that `tlsv1` and `tlsv1.1` are _deprecated_ in Couchbase Server Version 7.2. -The default is `tlsv1.2`. +Can be the default `tlsv1.2` or `tlsv1.3`. +It can be set either globally or per service. + -This parameter can be set either globally or per service. +NOTE: The settings `tlsv1` and `tlsv1.1` were deprecated in Couchbase Server Version 7.2 and removed in Coucbase Server 7.6. +The Couchbase Server upgrade process from pre-7.6 to 7.6 or later sets this value to `tlsv1.2` if it was set to a lower value. * `honorCipherOrder`. Specifies whether the server uses its own cipher-suite preference, rather than the client's. @@ -212,7 +212,7 @@ For example, a call that incorrectly specifies every significant parameter-value "errors": [ "honorCipherOrder - Accepted values are 'true' and 'false'.", "cipherSuites - Invalid format. Expecting a list of ciphers.", - "tlsMinVersion - Supported TLS versions are tlsv1.3, tlsv1.2, tlsv1.1, tlsv1", + "tlsMinVersion - Supported TLS versions are tlsv1.3, tlsv1.2.", "clusterEncryptionLevel - Cluster encryption level must be one of [\"control\",\"all\",\"strict\"]",, "disableUIOverHttps - Accepted values are 'true' and 'false'.", "disableUIOverHttp - Accepted values are 'true' and 'false'.", @@ -274,7 +274,7 @@ If the call is successful, and some explicit settings have been made by the admi "disableUIOverHttps": false, "disableWWWAuthenticate": false, "responseHeaders": [], - "tlsMinVersion": "tlsv1", + "tlsMinVersion": "tlsv1.2", "cipherSuites": [ "TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA" diff --git a/modules/rest-api/pages/upload-retrieve-node-cert.adoc b/modules/rest-api/pages/upload-retrieve-node-cert.adoc index 7e6c5c5ca9..5d975f7d58 100644 --- a/modules/rest-api/pages/upload-retrieve-node-cert.adoc +++ b/modules/rest-api/pages/upload-retrieve-node-cert.adoc @@ -186,7 +186,8 @@ If successful, the call returns `200 OK`, and an object whose fields specify war [#see-also] == See Also -Information on uploading and retrieving the cluster's root certificate with the REST API is provided in xref:rest-api:upload-retrieve-root-cert.adoc[Upload and Retrieve the Root Certificate]. +For information about uploading and retrieving the cluster's root certificate using the REST API, see xref:rest-api:load-trusted-cas.adoc[] and xref:rest-api:get-trusted-cas.adoc[]. + Information on certificate regeneration is provided in xref:rest-api:rest-regenerate-all-certs.adoc[Regenerate All Certificates]. A general introduction to certificates is provided in xref:learn:security/certificates.adoc[Certificates]. Routines for generating and deploying server and client certificates are provided in xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] and xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates], respectively.