diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/configuration/security-configuration.markdown b/Documentation/5.2/Raven.Documentation.Pages/server/configuration/security-configuration.markdown new file mode 100644 index 0000000000..af2a077b85 --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/server/configuration/security-configuration.markdown @@ -0,0 +1,298 @@ +# Configuration: Security +--- + +{NOTE: } + +* The following configuration keys allow you to control the desired level of security in a RavenDB server. + To learn more about RavenDB's security features, see this [security overview](../../server/security/overview). + +* In this page: + * Security.AuditLog: + [Security.AuditLog.FolderPath](../../server/configuration/security-configuration#security.auditlog.folderpath) + [Security.AuditLog.RetentionTimeInHours](../../server/configuration/security-configuration#security.auditlog.retentiontimeinhours) + * Security.Certificate: + [Security.Certificate.Path](../../server/configuration/security-configuration#security.certificate.path) + [Security.Certificate.Password](../../server/configuration/security-configuration#security.certificate.password) + [Security.Certificate.Exec](../../server/configuration/security-configuration#security.certificate.exec) + [Security.Certificate.Exec.Arguments](../../server/configuration/security-configuration#security.certificate.exec.arguments) + [Security.Certificate.Load.Exec](../../server/configuration/security-configuration#security.certificate.load.exec) + [Security.Certificate.Renew.Exec](../../server/configuration/security-configuration#security.certificate.renew.exec) + [Security.Certificate.Change.Exec](../../server/configuration/security-configuration#security.certificate.change.exec) + [Security.Certificate.Load.Exec.Arguments](../../server/configuration/security-configuration#security.certificate.load.exec.arguments) + [Security.Certificate.Renew.Exec.Arguments](../../server/configuration/security-configuration#security.certificate.renew.exec.arguments) + [Security.Certificate.Change.Exec.Arguments](../../server/configuration/security-configuration#security.certificate.change.exec.arguments) + [Security.Certificate.Exec.TimeoutInSec](../../server/configuration/security-configuration#security.certificate.exec.timeoutinsec) + [Security.Certificate.LetsEncrypt.Email](../../server/configuration/security-configuration#security.certificate.letsencrypt.email) + * Security.MasterKey: + [Security.MasterKey.Path](../../server/configuration/security-configuration#security.masterkey.path) + [Security.MasterKey.Exec](../../server/configuration/security-configuration#security.masterkey.exec) + [Security.MasterKey.Exec.Arguments](../../server/configuration/security-configuration#security.masterkey.exec.arguments) + [Security.MasterKey.Exec.TimeoutInSec](../../server/configuration/security-configuration#security.masterkey.exec.timeoutinsec) + * Certificate and issuer validation: + [Security.WellKnownIssuerHashes.Admin](../../server/configuration/security-configuration#security.wellknownissuerhashes.admin) + [Security.WellKnownIssuers.Admin](../../server/configuration/security-configuration#security.wellknownissuers.admin) + * Other: + [Security.UnsecuredAccessAllowed](../../server/configuration/security-configuration#security.unsecuredaccessallowed) + [Security.DoNotConsiderMemoryLockFailureAsCatastrophicError](../../server/configuration/security-configuration#security.donotconsidermemorylockfailureascatastrophicerror) + [Security.DisableHttpsRedirection](../../server/configuration/security-configuration#security.disablehttpsredirection) + [Security.WellKnownCertificates.Admin](../../server/configuration/security-configuration#security.wellknowncertificates.admin) + [Security.TlsCipherSuites](../../server/configuration/security-configuration#security.tlsciphersuites) + +{NOTE/} + +--- + +{PANEL: Security.AuditLog.FolderPath} + +The path to a folder where RavenDB will store the access audit logs. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.AuditLog.RetentionTimeInHours} + +How far back we should retain audit log entries. + +- **Type**: `int` +- **Default**: `365 * 24` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Path} + +The path to .pfx certificate file. If specified, RavenDB will use HTTPS/SSL for all network activities. +Certificate setting priority order: +1. Path +2. Executable + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Password} + +The (optional) password of the .pfx certificate file. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Exec} + +Deprecated in 4.2 and replaced with [Security.Certificate.Load.Exec](../../server/configuration/security-configuration#security.certificate.load.exec), see below. + +{PANEL/} + +{PANEL: Security.Certificate.Exec.Arguments} + +Deprecated in 4.2 and replaced with [Security.Certificate.Load.Exec.Arguments](../../server/configuration/security-configuration#security.certificate.load.exec.arguments), see below. + +{PANEL/} + +{PANEL: Security.Certificate.Load.Exec} + +A command or executable that provides the .pfx cluster certificate when invoked by RavenDB. If specified, RavenDB will use HTTPS/SSL for all network activities. +The `Security.Certificate.Path` setting takes precedence over this executable. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Renew.Exec} + +A command or executable that handles automatic cluster certificate renewals and passes the renewed .pfx certificate to the rest of the cluster. The +[leader node](../../server/clustering/rachis/cluster-topology#leader) will invoke this executable once every hour and if a new certificate is received, it +will be sent to the other nodes. The executable specified in `Security.Certificate.Change.Exec` will then be used to persist the certificate across the cluster. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Change.Exec} + +A command or executable that replaces the old cluster certificate with the renewed cluster certificate. After `Security.Certificate.Change.Exec` distributes the +new certificate, this executable persists it locally at each follower node. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Load.Exec.Arguments} + +The command line arguments for the 'Security.Certificate.Load.Exec' command or executable. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Renew.Exec.Arguments} + +The command line arguments for the 'Security.Certificate.Renew.Exec' command or executable. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Change.Exec.Arguments} + +The command line arguments for the 'Security.Certificate.Change.Exec' command or executable. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.Exec.TimeoutInSec} + +The number of seconds to wait for the certificate executables to exit. +Applies to: `Security.Certificate.Load.Exec`, `Security.Certificate.Renew.Exec`, and `Security.Certificate.Change.Exec`. + +- **Type**: `int` +- **Default**: `30` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.Certificate.LetsEncrypt.Email} + +The E-mail address associated with the Let's Encrypt certificate. Used for renewal requests. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.MasterKey.Path} + +The path of the (256-bit) Master Key. If specified, RavenDB will use this key to protect secrets. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.MasterKey.Exec} + +A command or executable to run which will provide a (256-bit) Master Key, If specified, RavenDB will use this key to protect secrets. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.MasterKey.Exec.Arguments} + +The command line arguments for the 'Security.MasterKey.Exec' command or executable. + +- **Type**: `string` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.MasterKey.Exec.TimeoutInSec} + +The number of seconds to wait for the Master Key executable to exit. + +- **Type**: `int` +- **Default**: `30` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.UnsecuredAccessAllowed} + +If authentication is disabled, set the address range type for which server access is unsecured (`None | Local | PrivateNetwork | PublicNetwork`). + +- **Type**: `flags` +- **Default**: `Local` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.DoNotConsiderMemoryLockFailureAsCatastrophicError} + +Determines whether RavenDB will consider memory lock error to be catastrophic. This is used with encrypted databases to ensure that temporary buffers are never written to disk and are locked to memory. Setting this to true is not recommended and should be done only after a proper security analysis has been performed. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide or per database + +{WARNING Use with caution. /} + +{PANEL/} + +{PANEL: Security.DisableHttpsRedirection} + +Disable automatic redirection when listening to HTTPS. By default, when using port 443, RavenDB redirects all incoming HTTP traffic on port 80 to HTTPS on port 443. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.WellKnownCertificates.Admin} + +Allow to specify well known certificate thumbprints that will be trusted by the server as cluster admins. + +- **Type**: `strings separated by ;` +- **Example**: `297430d6d2ce259772e4eccf97863a4dfe6b048c;e6a3b45b062d509b3382282d196efe97d5956ccb` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.WellKnownIssuerHashes.Admin} + +OBSOLETE. +This is no longer supported or used. +Use [Security.WellKnownIssuers.Admin](../../server/configuration/security-configuration#security.wellknownissuers.admin) instead. + +{PANEL/} + +{PANEL: Security.WellKnownIssuers.Admin} + +Specify well-known issuer certificates in Base64 format or provide file paths to the certificate files. +This will be used to validate a new client certificate when the issuer's certificate changes. + +- **Type**: `string[]` or `string with values separated by ;` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} + +{PANEL: Security.TlsCipherSuites} + +{DANGER: For experts, use with caution} +Defines a list of supported TLS Cipher Suites. Values must be semicolon separated. +{DANGER/} + +- **Type**: `TlsCipherSuite[]` +- **Example**: `TLS_RSA_WITH_RC4_128_MD5;TLS_RSA_WITH_RC4_128_SHA` +- **Default**: `null` +- **Scope**: Server-wide only + +{PANEL/} diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/export_cluster_certificates.png b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/export_cluster_certificates.png new file mode 100644 index 0000000000..c30b07a6fa Binary files /dev/null and b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/export_cluster_certificates.png differ diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/renew_server_certificate.png b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/renew_server_certificate.png new file mode 100644 index 0000000000..e26270f2a3 Binary files /dev/null and b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/renew_server_certificate.png differ diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/upload-client-certificate.png b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/upload-client-certificate.png new file mode 100644 index 0000000000..da88edd677 Binary files /dev/null and b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/images/upload-client-certificate.png differ diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/solve-cluster-certificate-renewal-issue.markdown b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/solve-cluster-certificate-renewal-issue.markdown new file mode 100644 index 0000000000..e54191340a --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/server/security/authentication/solve-cluster-certificate-renewal-issue.markdown @@ -0,0 +1,150 @@ +# Let's Encrypt: Solve Certificate Renewal Issue + +* If you have External Replication or ETL to another cluster, or if you use + your own Let's Encrypt certificates as client certificates, the next certificate + renewal may cause permission issues that need to be handled manually. + +* Find [whether this issue is relevant for you](../../../server/security/authentication/solve-cluster-certificate-renewal-issue#current-situation) + and if so, [how to handle it](../../../server/security/authentication/solve-cluster-certificate-renewal-issue#solutions). + +* **In this page**: + * [Errors Relevant To This Issue](../../../server/security/authentication/solve-cluster-certificate-renewal-issue#errors-relevant-to-this-issue) + * [Background And Current Situation](../../../server/security/authentication/solve-cluster-certificate-renewal-issue#background-and-current-situation) + * [Solutions](../../../server/security/authentication/solve-cluster-certificate-renewal-issue#solutions) + +## Errors Relevant To This Issue + +If your current cluster certificate is operative, you will encounter +the errors we discuss here only when an attempt is made to renew the certificate. + +When the cluster certificate is renewed, authentication errors will appear +as **Studio alerts** and/or **responses to client requests**. + +* The errors will also appear in the logs. + ``` + Raven.Server.Documents.ETL.Providers.Raven.RavenEtl, Failed to load transformed data for 'ETL Script', EXCEPTION: Raven.Client.Exceptions.Security.AuthorizationException: Forbidden access to db1@https://a.some.one.ravendb.cloud, does not have permission to access it or is unknown. Method: GET, Request: https://a.some.one.ravendb.cloud/topology?name=db1&first-topology-update + {"Type":"InvalidAuth","Message":"The supplied client certificate 'CN=\*.some.one.ravendb.cloud(Thumbprint: A632C1DBD145B2102CB70D254B7EC1C813444766)' is unknown to the server but has a known Public Key Pinning Hash. Will not use it to authenticate because the issuer is unknown. To fix this, the admin can register the pinning hash of the \*issuer\* certificate: 'jQJTbIh0grw0/1TkHSumWb+Fs0Ggogr621gT3PvPKG0=' in the 'Security.WellKnownIssuer.Admin' configuration entry."} + ``` + + The Audit Log will contain the following entry: + ``` + Information, AuthenticateCertificate, Audit, Connection from with certificate 'CN=*.some.one.ravendb.cloud (A632C1DBD145B2102CB70D254B7EC1C813444766)' which is not registered in the cluster. + Tried to allow the connection implicitly based on the client certificate's Public Key Pinning Hash but the client certificate was signed by an unknown issuer - closing the connection. + To fix this, the admin can register the pinning hash of the *issuer* certificate: 'jQJTbIh0grw0/1TkHSumWb+Fs0Ggogr621gT3PvPKG0=' in the 'Security.WellKnownIssuers.Admin' configuration entry. + Alternatively, the admin can register the actual certificate ( 'A632C1DBD145B2102CB70D254B7EC1C813444766') explicitly in the cluster. + ``` + +{PANEL: Background and Current Situation} + +### Background + +* **Original Problem** + RavenDB versions preceding 4.2 presented the following administration problem when + ETL or External Replication was defined between two secured RavenDB clusters: + The destination cluster trusts (explicitly) the source cluster's certificate. + Once the source cluster renewes its certificate, the destination cluster would + no longer trust it because the thumbprint has changed. + To solve this, the admin had to access the destination cluster and manually specify + that it can trust the new source certificate. + +* **Original Solution** + To solve this problem, we introduced [Implicit Trust](../../../server/security/authentication/certificate-renewal-and-rotation#implicit-trust-by-public-key-pinning-hash) + by using the certificate's **Public Key Pinning Hash**. + Now, if the source cluster renews its certificate **by using the same private key and + issuer**, the new certificate will have the same Public Key Pinning Hash, and the + destination cluster will be able to trust the new certificate. + It will also be registered (implicitly) for future connections. + +* **What you gain** + Using this feature means that you can drastically reduce the amount of work + an admin has to perform in a multi-cluster topology and gain a system that + is set-up once and just keeps working, **as long as you keep using the same + private key and issuer**. + +--- + +### Current Situation + +In September 2020, Let's Encrypt changed their certificate issuer to support full ECDSA +certificate chains. You can [read about it here](https://letsencrypt.org/2020/09/17/new-root-and-intermediates.html). + +As a result, RavenDB users that use the Public Key Pinning Hash solution need to +take a few manual steps. + +This is relevant for you - + +1. If you use RavenDB ETL or perform External Replication between two + RavenDB clusters. + * If you use RavenDB Cloud where certificates are renewed automatically. + * If you used our Setup Wizard with Let's Encrypt, and certificates are + renewed automatically. + * If you used your own Let's Encrypt **cluster** certificate, and you + renew it yourself with the same private key. +2. If you created your own Let's Encrypt **client** certificates, and you renew + them using the same private key. + +{PANEL/} + +{PANEL: Solutions} + +### Solution 1: + +Register the pinning hash of the old issuer in the destination cluster. In settings.json, +on every node of the destination cluster add the following: + +{CODE-BLOCK:JSON} +"Security.WellKnownIssuers.Admin": "jQJTbIh0grw0/1TkHSumWb+Fs0Ggogr621gT3PvPKG0=" +{CODE-BLOCK/} + +The hash in the example is the Public Key Pinning Hash of the Let's Encrypt X3 intermediate +certificate authority which was previously used to sign Let's Encrypt certificates. + +This solution is stronger, it ensures a smooth transparent transition when the source cluster +certificate will renew itself and the issuer will actually change. The advantage here is that +there is no downtime. + +The disadvantage is that an admin needs to access the machines themselves. They need to edit +the settings.json file on all nodes and restart the RavenDB service (node-by-node for no downtime). + +--- + +###Solution 2: + +1. In the case of ETL or External Replication, go to the source cluster and renew the Let's Encrypt + cluster certificate. Then export it and register it in the destination cluster. + + * Click `Renew` on the server certificate in one of the nodes of the source cluster. + ![Figure 1. Renew Server Certificate](images/renew_server_certificate.png) + * Export the new cluster certificate: + ![Figure 2. Export Cluster Certificate](images/export_cluster_certificates.png) + * Use the destination cluster's Studio to upload the exported pfx file as a client certificate. + ![Figure 3. Upload Client Certificat](images/upload-client-certificate.png) + + +2. In case you are using your own Let's Encrypt client certificates, simply renew them + (on your own) and re-register them in the certificate view in the Studio ([Upload client + certificate](../../../studio/database/tasks/import-data/import-from-ravendb#step-#1:-prepare-servers-for-the-import-process-(secure-4.x-servers-only))). + +This solution is easier and doesn't require access to the machines themselves, just an admin +certificate. The disadvantage is a short downtime in the service, because you must renew the +certificate first and only then you may export it and upload to the destination cluster. +This can cause some delay in the ETL or Replication service. + +{PANEL/} + +## Related articles + +### Security + +- [Overview](../../../server/security/overview) +- [Certificate Management](../../../server/security/authentication/certificate-management) +- [Common Errors and FAQ](../../../server/security/common-errors-and-faq) +- [Implicit Trust by Public Key Pinning Hash](../../../server/security/authentication/certificate-renewal-and-rotation#implicit-trust-by-public-key-pinning-hash) + +### Client API + +- [Setting up Authentication and Authorization](../../../client-api/setting-up-authentication-and-authorization) + +### Installation + +- [Secure Setup with a Let's Encrypt Certificate](../../../start/installation/setup-wizard#secure-setup-with-a-let)