diff --git a/docs/server/security/common-errors-and-faq.mdx b/docs/server/security/common-errors-and-faq.mdx index 34f9f0cabf..028614f09e 100644 --- a/docs/server/security/common-errors-and-faq.mdx +++ b/docs/server/security/common-errors-and-faq.mdx @@ -11,13 +11,15 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Security: Common Errors & FAQ * This article explains some of the common security configuration errors and how to handle them. -* In this page +* In this article: * [Setup Wizard Issues](../../server/security/common-errors-and-faq.mdx#setup-wizard-issues) * [Changing Configurations and Renewals Issues](../../server/security/common-errors-and-faq.mdx#changing-configurations-and-renewals-issues) * [Authentication Issues](../../server/security/common-errors-and-faq.mdx#authentication-issues) @@ -25,30 +27,31 @@ import LanguageContent from "@site/src/components/LanguageContent"; -## Setup Wizard Issues + * [Server cannot bind to the provided private IP address](../../server/security/common-errors-and-faq.mdx#server-cannot-bind-to-the-provided-private-ip-address) * [Ports are blocked by the firewall](../../server/security/common-errors-and-faq.mdx#ports-are-blocked-by-the-firewall) * [DNS is cached locally](../../server/security/common-errors-and-faq.mdx#dns-is-cached-locally) * [Long DNS propagation time](../../server/security/common-errors-and-faq.mdx#long-dns-propagation-time) * [If I already have the Zip file, can I avoid repeating the setup process?](../../server/security/common-errors-and-faq.mdx#if-i-already-have-the-zip-file-can-i-avoid-repeating-the-setup-process) + + + ### Server cannot bind to the provided private IP address If the IP/port is not accessible on your machine, you'll get the following error. - - -{`System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> +```plain +System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.ravendb.community:4433 ---> System.InvalidOperationException: Failed to start webhost on node 'A'. The specified ip address might not be reachable due to network issues. It can happen if the ip is external (behind a firewall, docker). If this is the case, try going back to the previous screen and add the same ip as an external ip. -Settings file: D:\\temp\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\temp\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.0.65:4433. ---> Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.Internal.Networking.UvException: Error -4092 EACCES permission denied -`} - - +``` +
This can be caused by two different reasons: @@ -56,32 +59,39 @@ This can be caused by two different reasons: 2. You are running behind a firewall (VM, docker...) and accidentally provided the external IP address during setup. Make sure you provide the private IP address in the "IP Address / Hostname" field as seen in [this example](../../start/installation/setup-wizard/configure-node-addresses.mdx#behind-a-firewall-or-load-balancer). + + + + + ### Ports are blocked by the firewall When configuring a VM in Azure, [AWS](../../start/installation/setup-examples/aws-windows-vm.mdx) or any other provider, you should define firewall rules to allow both the **HTTP** and **TCP** ports you have chosen during setup. This should be done both inside the VM operating system **and** in the web dashboard or management console. If ports are blocked you'll get the following error. - - -{`Setting up RavenDB in Let's Encrypt security mode failed. + +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.development.run:443 ---> System.InvalidOperationException: Client failed to contact webhost listening to 'https://a.example.development.run:443'. Are you blocked by a firewall? Make sure the port is open. -Settings file: D:\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.1.4:443. -`} - - +``` + + + + + ### DNS is cached locally Most networks cache DNS records. In some environments you can get an error such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.onenode.development.run ---> @@ -90,20 +100,23 @@ Expected to get these ips: 127.0.0.1 while the actual result was: 10.0.0.65 If we try resolving through google's api (https://dns.google.com), it works well. Try to clear your local/network DNS cache or wait a few minutes and try again. Another temporary solution is to configure your local network connection to use google's DNS server (8.8.8.8). -`} - - +``` +
This error probably means that the DNS is cached. You can wait a few minutes or reset the network DNS cache, but in many cases, the easiest solution is to [temporarily switch your DNS server to 8.8.8.8](https://developers.google.com/speed/public-dns/docs/using) You can click the Try Again button to restart the validation process of the Setup Wizard. + + + + + ### Long DNS propagation time If you are trying to modify existing DNS records, for example running the Setup Wizard again for the same domain name, you may encounter errors such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> @@ -112,12 +125,16 @@ System.InvalidOperationException: Tried to resolve 'a.example.development.run' u Expected to get these ips: 127.0.0.1 while google's actual result was: 10.0.0.65 Please wait a while until DNS propagation is finished and try again. If you are trying to update existing DNS records, it might take hours to update because of DNS caching. If the issue persists, contact RavenDB's support. -`} - - +``` +
If this happens, there is nothing you can do except wait for DNS propagation. When it's updated on dns.google.com click the `Try Again` button. You can keep track of your RavenDB clusters and their associated DNS records at the [Customer's Portal](https://customers.ravendb.net). + + + + + ### If I already have the Zip file, can I avoid repeating the setup process? Yes. @@ -126,16 +143,20 @@ Download a fresh copy of RavenDB and run the setup wizard. Then choose `Continue This will use the existing Zip file and the same configuration and certificate which were previously chosen. When building a cluster, repeat this step with nodes B, C, and so on. + + - -## Changing Configurations and Renewals Issues + * [After installing with Let's Encrypt, can I change the DNS records?](../../server/security/common-errors-and-faq.mdx#after-installing-with-lets-encrypt-can-i-change-the-dns-records) * [Can I change the (private) IP address RavenDB binds to?](../../server/security/common-errors-and-faq.mdx#can-i-change-the-private-ip-address-ravendb-binds-to) * [The Let's Encrypt certificate is about to expire but doesn't renew automatically](../../server/security/common-errors-and-faq.mdx#the-lets-encrypt-certificate-is-about-to-expire-but-doesnt-renew-automatically) * [What should I do when my license expires?](../../server/security/common-errors-and-faq.mdx#what-should-i-do-when-my-license-expires) * [Let's Encrypt certificate permission errors after renewal](../../server/security/common-errors-and-faq.mdx#lets-encrypt-certificate-permission-errors-after-renewal) + + + ### After installing with Let's Encrypt, can I change the DNS records? Yes. @@ -145,31 +166,38 @@ Yes. If you supply different IP addresses then the wizard will update the DNS records of your domain. If you use a new domain or if you add/remove nodes in the new configuration then the wizard will also fetch a new certificate. + + + + + ### Can I change the (private) IP address RavenDB binds to? Yes. Open the [settings.json](../configuration/configuration-options.mdx#json) file located in the RavenDB Server installation folder, change the `ServerUrl` setting and restart the server. + + + + + ### The Let's Encrypt certificate is about to expire but doesn't renew automatically If you are getting the following error you must update the RavenDB server. - - -{`Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: +```plain +Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: Your license is associated with the following domains: ravendb.community but the PublicServerUrl configuration setting is: Raven.Server.Config.Settings.UriSetting.There is a mismatch, therefore cannot automatically renew the Lets Encrypt certificate. Please contact support. -`} - - +``` +
If it's not the same error as above, please open [settings.json](../configuration/configuration-options.mdx#json) in your Server installation and make sure you have all of the fields defined properly. Take a look at the following example: - - -{`\{ +```json +{ "DataDir": "RavenData", "License.Eula.Accepted": true, "Security.Certificate.LetsEncrypt.Email": "your-email@example.com", @@ -180,10 +208,9 @@ and make sure you have all of the fields defined properly. Take a look at the fo "ExternalIp": "35.130.249.162", "PublicServerUrl": "https://a.aws.development.run", "PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888" -\} -`} - - +} +``` +
Things to check: @@ -204,6 +231,11 @@ Things to check: you can contact support. * Make sure to supply the server logs with your ticket. When running in a cluster, please provide the logs from all nodes. * If your logs are turned off, open `Manage Server`->`Admin Logs` in the Studio, and keep them open while you click the `Renew` button in the certificate view. + + + + + ### What should I do when my license expires? * When your license expires the Studio is blocked. @@ -212,6 +244,11 @@ Things to check: and doesn't comply with the [EULA terms](https://ravendb.net/terms). * __Renew your license__ as described in this [Renew License](../../licensing/renew-license.mdx) tutorial. + + + + + ### Let's Encrypt certificate permission errors after renewal If you have External Replication or ETL to another cluster, @@ -220,9 +257,11 @@ the next certificate renewal may cause permission issues that need to be handled Learn how to handle this issue [here](../../server/security/authentication/solve-cluster-certificate-renewal-issue.mdx). + + -## Authentication Issues + * [Authentication Error Occurred using Edge](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-edge) * [Authentication Error Occurred using Chrome](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome) @@ -232,8 +271,12 @@ Learn how to handle this issue [here](../../server/security/authentication/solve * [Getting the full error using PowerShell](../../server/security/common-errors-and-faq.mdx#getting-the-full-error-using-powershell) * [Not using TLS](../../server/security/common-errors-and-faq.mdx#not-using-tls) * [How to regain access to a server when you have physical access but no client certificate](../../server/security/common-errors-and-faq.mdx#how-to-regain-access-to-a-server-when-you-have-physical-access-but-no-client-certificate) +* ["Could not create SSL/TLS secure channel" error under an IIS webhost](../../server/security/common-errors-and-faq.mdx#could-not-create-ssltls-secure-channel-error-under-an-iis-webhost) * [Certificate is not recognized when setting up on Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services) * [Automatic cluster certificate renewal following migration to 4.2](../../server/security/common-errors-and-faq.mdx#automatic-cluster-certificate-renewal-following-migration-to-42) + + + ### Authentication Error Occurred using Edge You cannot access Studio using Edge, though during @@ -243,13 +286,11 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or opening an incognito tab and pasting the server URL into the address bar. @@ -265,6 +306,9 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + +--- + #### If your browser runs under Windows 7 or Windows Server 2008 or older: The first thing to try would be installing the **ADMIN** certificate to the OS @@ -275,15 +319,17 @@ If the issue persists, please also visit the and follow method 3 (**Configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL handshake process**) to set the following registry entry to false: - - -{`HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\SecurityProviders\\SCHANNEL +```plain +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL Value name: SendTrustedIssuerList Value type: REG_DWORD Value data: 0 (False) -`} - - +``` + + + + + ### Authentication Error Occurred using Chrome You cannot access Studio using Chrome, though during @@ -293,29 +339,27 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or open an incognito tab (Ctrl+Shift+N) and paste the server URL into the address bar. 2. If clearing the cache didn't help, manually register the client certificate. - * Chrome versions **earlier than 105** look for certificatees registered **with the OS**. + * Chrome versions **earlier than 105** look for certificates registered **with the OS**. Windows users can register a certificate with the OS by double-clicking its .pfx file and repeatedly clicking `next` for the default settings (or providing custom settings). Linux users can import the certificate directly to the browser. - * Chrome versions **105 and on** look for certificatees registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). + * Chrome versions **105 and on** look for certificates registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). A failure to locate the certificate may be the result of registering it with the OS rather than with the browser. - This failure typically occures when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) - are used rather than with let's encrypt certificates issued during setup, since - let's encrypt certificates are automatically installed in the Chrome root store. + This failure typically occurs when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) + are used rather than with Let's Encrypt certificates issued during setup, since + Let's Encrypt certificates are automatically installed in the Chrome root store. - To import a certificate to chrome's root store use the browser's settings: + To import a certificate to Chrome's root store use the browser's settings: **Settings** > **Privacy and Security** > **Security** > **Manage device certificates** When a "Certificates" window opens, click **Import** and select your PFX certificate. ![Import Certificate](./assets/import-certificate.png) @@ -326,6 +370,11 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + + + + + ### RavenDB is running as a service in Windows and Chrome doesn't use the client certificate from the OS store Your RavenDB service may run under a certain user, for which the certificate was installed, while you @@ -336,36 +385,42 @@ looks for the certificate not at the OS root but at the Chrome root store. To solve these issues: Using a user that the service is available for, install or import the certificate PFX [as described above](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome). + + + + + ### Authentication Error Occurred in Firefox You cannot access the Studio using Firefox even though you have finished the setup wizard successfully and you also checked the box saying "Automatically register the admin client certificate in this (local) OS". ![Figure 2. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
Firefox doesn't use the OS certificate store like Chrome or Edge. Please import the certificate manually (In Firefox, "Settings" -> "Privacy and Security" -> scroll down to Security and click "View Certificates" -> "Import"). Then close **all instances** of the browser and restart it. ![Figure 3. Firefox Import](./assets/2.png) + + + + + ### Cannot Import the Client Certificate to Firefox You're trying to import the client certificate received from RavenDB to Firefox but get the following error: ![Figure 3. Unknown Reasons](./assets/3.png) - - -{`The PKCS#12 operation failed for unknown reasons. -`} - - +```plain +The PKCS#12 operation failed for unknown reasons. +``` +
Firefox fails to import a certificate that is not password protected. To overcome this issue, use the RavenDB CLI to [generate a password protected certificate](../../server/administration/cli.mdx#generateclientcert). @@ -377,7 +432,7 @@ You can try to generate a new password-protected certificate using the RavenDB C If it didn't help, you can use any other client certificate you have that works with Firefox (even if it wasn't generated by RavenDB) and have RavenDB trust it. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). -You can also generate your own self-signed client certificate by using OpenSSL or Powershell. +You can also generate your own self-signed client certificate by using OpenSSL or PowerShell. This is a known issue which has been reported many times to Mozilla. @@ -386,75 +441,127 @@ Some references: [Bugzilla: #1049435](https://bugzilla.mozilla.org/show_bug.cgi?id=1049435) [Bugzilla: #458161](https://bugzilla.mozilla.org/show_bug.cgi?id=458161) [mozilla.dev.tech.crypto issue](https://groups.google.com/forum/?fromgroups=#!topic/mozilla.dev.tech.crypto/RiIeY-R5Q4Y) + + + + + ### Getting the full error using PowerShell You can use PowerShell to make requests using the REST API. If you are having trouble using certificates, take a look at this example which prints the full error (replace the server URL and the `/certificates/whoami` endpoint with yours). - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -$cert = Get-PfxCertificate -FilePath C:\\secrets\\admin.client.certificate.example.pfx +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$cert = Get-PfxCertificate -FilePath C:\secrets\admin.client.certificate.example.pfx -try \{ +try { $response = Invoke-WebRequest https://a.example.development.run:8080/certificates/whoami -Certificate $cert -\} -catch \{ - if ($_.Exception.Response -ne $null) \{ +} +catch { + if ($_.Exception.Response -ne $null) { Write-Host $_.Exception.Message $stream = $_.Exception.Response.GetResponseStream() $reader = New-Object System.IO.StreamReader($stream) Write-Host $reader.ReadToEnd() - \} + } Write-Error $_.Exception -\} -`} - - +} +``` + + + + + ### Not using TLS The RavenDB clients use TLS 1.2 by default. If you want to use other clients please make sure to use the TLS security protocol version 1.2 or 1.3. - - - -{`{ +Bad Request (400) sample response: + +```json +{ "Url":"/admin/secrets/generate", "Type":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException", "Message":"RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'.", "Error":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException: RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'. - at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServer.cs:line 570 - at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 168 - at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 89 + at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServer.cs:line 570 + at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 168 + at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 89 --- End of stack trace from previous location where exception was thrown --- at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) - at System.Runtime.CompilerServices.TaskAwaiter\`1.GetResult() - at System.Runtime.CompilerServices.ValueTaskAwaiter\`1.GetResult() - at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServerStartup.cs:line 159" + at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult() + at System.Runtime.CompilerServices.ValueTaskAwaiter`1.GetResult() + at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServerStartup.cs:line 159" } -`} - - - +``` +
In PowerShell it can be solved like this: - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -`} - - +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +``` + + + + + ### How to regain access to a server when you have physical access but no client certificate -An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli#generateclientcert If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. +An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli.mdx#generateclientcert). If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. Use either the [generateClientCert](../../server/administration/cli.mdx#generateclientcert) command, or (if you already have a certificate) the [trustClientCert](../../server/administration/cli.mdx#trustclientcert) command. Another way to gain access for an existing certificate is to add the [Security.WellKnownCertificates.Admin](../../server/configuration/security-configuration.mdx#securitywellknowncertificatesadmin) configuration to `settings.json` with your existing certificate's thumbprint. In this case, a server restart is required. + + + + + +### "Could not create SSL/TLS secure channel" error under an IIS webhost + +Custom code that connects to RavenDB from an IIS-hosted application can fail with the +following error, even though the same code works when run directly (for example, from a +unit test): + +``` +The request was aborted: Could not create SSL/TLS secure channel. +``` +
+ +This message is generic and does not reveal the real cause. +The underlying error is `Keyset does not exist`: the IIS worker process runs under a +restricted identity (`IIS_IUSRS`, or the application pool identity `IIS AppPool\`) +that has no read access to the private key of the client certificate. +Run directly, the same code loads the certificate under your own user account, which does +have that access. + +To fix this, grant the IIS identity read access to the certificate's private key: + +1. Open the Local Computer certificate store by running `certlm.msc` as an administrator. +2. Under `Personal` > `Certificates`, right-click your client certificate and select + `All Tasks` > `Manage Private Keys`. +3. Add the IIS identity (`IIS_IUSRS`, or `IIS AppPool\` when the pool uses its own + identity) and grant it `Read` permission. + + + +Microsoft documents the same `Manage Private Keys` dialog, in the context of a SQL Server +service account, in [Encrypt connections to SQL Server by importing a certificate](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-sql-server-encryption). + +As an alternative, you can load the certificate into the machine key store programmatically +with the `MachineKeySet` flag, as shown for [Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services). + + + + + + + ### Certificate is not recognized when setting up on Azure App Services You may have gotten an error message like: @@ -462,18 +569,21 @@ You may have gotten an error message like: ``` The credentials supplied to the package were not recognized (The SSL connection could not be established, see inner exception.) ``` +
1) In the app settings of your Azure App Services application, add the `WEBSITE_LOAD_USER_PROFILE = 1` option. 2) Another solution is to use the `MachineKeySet` flag during certificate creation: - - -{`[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", +```csharp +[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", (string)null, X509KeyStorageFlags.MachineKeySet); -`} - - +``` + + + + + ### Automatic cluster certificate renewal following migration to 4.2 `Security.Certificate.Exec` was deprecated in 4.2 and replaced by `Security.Certificate.Load.Exec`. You can use your old `Security.Certificate.Exec` @@ -482,22 +592,22 @@ for automatically persisting the certificate to the whole cluster. If you have y you still need to place empty scripts in the `Security.Certificate.Renew.Exec` and `Security.Certificate.Change.Exec` paths or an exception will be thrown. + + -## Encryption Issues + ### Insufficient Memory Exception - - -{`Memory exception occurred: System.InsufficientMemoryException: +```plain +Memory exception occurred: System.InsufficientMemoryException: Failed to increase the min working set size so we can lock 4,294,967,296 for -D:\\stackoverflow\\RavenData\\Databases\\SO\\Indexes\\Auto_Questions_ByBody\\Temp\\compression.0000000000.buffers. +D:\stackoverflow\RavenData\Databases\SO\Indexes\Auto_Questions_ByBody\Temp\compression.0000000000.buffers. With encrypted databases we lock some memory in order to avoid leaking secrets to disk. Treating this as a catastrophic error and aborting the current operation. -`} - - +``` +
When encryption is turned on, RavenDB locks memory in order to avoid leaking secrets to disk. Read more [here](../../server/security/encryption/encryption-at-rest.mdx#locking-memory). @@ -506,14 +616,13 @@ You can change this behavior but it's not recommended and should be done only af If such a catastrophic error occurs in **Windows**, RavenDB will try to recover automatically by increasing the size of the minimum working set and retrying the operation. In **Linux**, it is the admin's responsibility to configure higher limits manually using: - - -{`sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] -`} - - + +```bash +sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] +``` +
To figure out what the new limit should be, look at the exception thrown by RavenDB, which includes this size. For persistent and service-level configuration, see [Linux: Setting memlock when using encrypted database](../kb/linux-setting-memlock.mdx). - + diff --git a/versioned_docs/version-6.2/server/security/common-errors-and-faq.mdx b/versioned_docs/version-6.2/server/security/common-errors-and-faq.mdx index 35f1d89b34..10437324c3 100644 --- a/versioned_docs/version-6.2/server/security/common-errors-and-faq.mdx +++ b/versioned_docs/version-6.2/server/security/common-errors-and-faq.mdx @@ -10,13 +10,15 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Security: Common Errors & FAQ * This article explains some of the common security configuration errors and how to handle them. -* In this page +* In this article: * [Setup Wizard Issues](../../server/security/common-errors-and-faq.mdx#setup-wizard-issues) * [Changing Configurations and Renewals Issues](../../server/security/common-errors-and-faq.mdx#changing-configurations-and-renewals-issues) * [Authentication Issues](../../server/security/common-errors-and-faq.mdx#authentication-issues) @@ -24,30 +26,31 @@ import LanguageContent from "@site/src/components/LanguageContent"; -## Setup Wizard Issues + * [Server cannot bind to the provided private IP address](../../server/security/common-errors-and-faq.mdx#server-cannot-bind-to-the-provided-private-ip-address) * [Ports are blocked by the firewall](../../server/security/common-errors-and-faq.mdx#ports-are-blocked-by-the-firewall) * [DNS is cached locally](../../server/security/common-errors-and-faq.mdx#dns-is-cached-locally) * [Long DNS propagation time](../../server/security/common-errors-and-faq.mdx#long-dns-propagation-time) * [If I already have the Zip file, can I avoid repeating the setup process?](../../server/security/common-errors-and-faq.mdx#if-i-already-have-the-zip-file-can-i-avoid-repeating-the-setup-process) + + + ### Server cannot bind to the provided private IP address If the IP/port is not accessible on your machine, you'll get the following error. - - -{`System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> +```plain +System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.ravendb.community:4433 ---> System.InvalidOperationException: Failed to start webhost on node 'A'. The specified ip address might not be reachable due to network issues. It can happen if the ip is external (behind a firewall, docker). If this is the case, try going back to the previous screen and add the same ip as an external ip. -Settings file: D:\\temp\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\temp\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.0.65:4433. ---> Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.Internal.Networking.UvException: Error -4092 EACCES permission denied -`} - - +``` +
This can be caused by two different reasons: @@ -55,32 +58,39 @@ This can be caused by two different reasons: 2. You are running behind a firewall (VM, docker...) and accidentally provided the external IP address during setup. Make sure you provide the private IP address in the "IP Address / Hostname" field as seen in [this example](../../start/installation/setup-wizard/configure-node-addresses.mdx#behind-a-firewall-or-load-balancer). + + + + + ### Ports are blocked by the firewall When configuring a VM in Azure, [AWS](../../start/installation/setup-examples/aws-windows-vm.mdx) or any other provider, you should define firewall rules to allow both the **HTTP** and **TCP** ports you have chosen during setup. This should be done both inside the VM operating system **and** in the web dashboard or management console. If ports are blocked you'll get the following error. - - -{`Setting up RavenDB in Let's Encrypt security mode failed. + +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.development.run:443 ---> System.InvalidOperationException: Client failed to contact webhost listening to 'https://a.example.development.run:443'. Are you blocked by a firewall? Make sure the port is open. -Settings file: D:\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.1.4:443. -`} - - +``` + + + + + ### DNS is cached locally Most networks cache DNS records. In some environments you can get an error such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.onenode.development.run ---> @@ -89,20 +99,23 @@ Expected to get these ips: 127.0.0.1 while the actual result was: 10.0.0.65 If we try resolving through google's api (https://dns.google.com), it works well. Try to clear your local/network DNS cache or wait a few minutes and try again. Another temporary solution is to configure your local network connection to use google's DNS server (8.8.8.8). -`} - - +``` +
This error probably means that the DNS is cached. You can wait a few minutes or reset the network DNS cache, but in many cases, the easiest solution is to [temporarily switch your DNS server to 8.8.8.8](https://developers.google.com/speed/public-dns/docs/using) You can click the Try Again button to restart the validation process of the Setup Wizard. + + + + + ### Long DNS propagation time If you are trying to modify existing DNS records, for example running the Setup Wizard again for the same domain name, you may encounter errors such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> @@ -111,12 +124,16 @@ System.InvalidOperationException: Tried to resolve 'a.example.development.run' u Expected to get these ips: 127.0.0.1 while google's actual result was: 10.0.0.65 Please wait a while until DNS propagation is finished and try again. If you are trying to update existing DNS records, it might take hours to update because of DNS caching. If the issue persists, contact RavenDB's support. -`} - - +``` +
If this happens, there is nothing you can do except wait for DNS propagation. When it's updated on dns.google.com click the `Try Again` button. You can keep track of your RavenDB clusters and their associated DNS records at the [Customer's Portal](https://customers.ravendb.net). + + + + + ### If I already have the Zip file, can I avoid repeating the setup process? Yes. @@ -125,16 +142,20 @@ Download a fresh copy of RavenDB and run the setup wizard. Then choose `Continue This will use the existing Zip file and the same configuration and certificate which were previously chosen. When building a cluster, repeat this step with nodes B, C, and so on. + + - -## Changing Configurations and Renewals Issues + * [After installing with Let's Encrypt, can I change the DNS records?](../../server/security/common-errors-and-faq.mdx#after-installing-with-lets-encrypt-can-i-change-the-dns-records) * [Can I change the (private) IP address RavenDB binds to?](../../server/security/common-errors-and-faq.mdx#can-i-change-the-private-ip-address-ravendb-binds-to) * [The Let's Encrypt certificate is about to expire but doesn't renew automatically](../../server/security/common-errors-and-faq.mdx#the-lets-encrypt-certificate-is-about-to-expire-but-doesnt-renew-automatically) * [What should I do when my license expires?](../../server/security/common-errors-and-faq.mdx#what-should-i-do-when-my-license-expires) * [Let's Encrypt certificate permission errors after renewal](../../server/security/common-errors-and-faq.mdx#lets-encrypt-certificate-permission-errors-after-renewal) + + + ### After installing with Let's Encrypt, can I change the DNS records? Yes. @@ -144,31 +165,38 @@ Yes. If you supply different IP addresses then the wizard will update the DNS records of your domain. If you use a new domain or if you add/remove nodes in the new configuration then the wizard will also fetch a new certificate. + + + + + ### Can I change the (private) IP address RavenDB binds to? Yes. Open the [settings.json](../configuration/configuration-options.mdx#json) file located in the RavenDB Server installation folder, change the `ServerUrl` setting and restart the server. + + + + + ### The Let's Encrypt certificate is about to expire but doesn't renew automatically If you are getting the following error you must update the RavenDB server. - - -{`Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: +```plain +Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: Your license is associated with the following domains: ravendb.community but the PublicServerUrl configuration setting is: Raven.Server.Config.Settings.UriSetting.There is a mismatch, therefore cannot automatically renew the Lets Encrypt certificate. Please contact support. -`} - - +``` +
If it's not the same error as above, please open [settings.json](../configuration/configuration-options.mdx#json) in your Server installation and make sure you have all of the fields defined properly. Take a look at the following example: - - -{`\{ +```json +{ "DataDir": "RavenData", "License.Eula.Accepted": true, "Security.Certificate.LetsEncrypt.Email": "your-email@example.com", @@ -179,10 +207,9 @@ and make sure you have all of the fields defined properly. Take a look at the fo "ExternalIp": "35.130.249.162", "PublicServerUrl": "https://a.aws.development.run", "PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888" -\} -`} - - +} +``` +
Things to check: @@ -203,6 +230,11 @@ Things to check: you can contact support. * Make sure to supply the server logs with your ticket. When running in a cluster, please provide the logs from all nodes. * If your logs are turned off, open `Manage Server`->`Admin Logs` in the Studio, and keep them open while you click the `Renew` button in the certificate view. + + + + + ### What should I do when my license expires? * When your license expires the Studio is blocked. @@ -211,6 +243,11 @@ Things to check: and doesn't comply with the [EULA terms](https://ravendb.net/terms). * __Renew your license__ as described in this [Renew License](../../start/licensing/renew-license.mdx) tutorial. + + + + + ### Let's Encrypt certificate permission errors after renewal If you have External Replication or ETL to another cluster, @@ -219,9 +256,11 @@ the next certificate renewal may cause permission issues that need to be handled Learn how to handle this issue [here](../../server/security/authentication/solve-cluster-certificate-renewal-issue.mdx). + + -## Authentication Issues + * [Authentication Error Occurred using Edge](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-edge) * [Authentication Error Occurred using Chrome](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome) @@ -231,8 +270,12 @@ Learn how to handle this issue [here](../../server/security/authentication/solve * [Getting the full error using PowerShell](../../server/security/common-errors-and-faq.mdx#getting-the-full-error-using-powershell) * [Not using TLS](../../server/security/common-errors-and-faq.mdx#not-using-tls) * [How to regain access to a server when you have physical access but no client certificate](../../server/security/common-errors-and-faq.mdx#how-to-regain-access-to-a-server-when-you-have-physical-access-but-no-client-certificate) +* ["Could not create SSL/TLS secure channel" error under an IIS webhost](../../server/security/common-errors-and-faq.mdx#could-not-create-ssltls-secure-channel-error-under-an-iis-webhost) * [Certificate is not recognized when setting up on Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services) * [Automatic cluster certificate renewal following migration to 4.2](../../server/security/common-errors-and-faq.mdx#automatic-cluster-certificate-renewal-following-migration-to-42) + + + ### Authentication Error Occurred using Edge You cannot access Studio using Edge, though during @@ -242,13 +285,11 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or opening an incognito tab and pasting the server URL into the address bar. @@ -264,6 +305,9 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + +--- + #### If your browser runs under Windows 7 or Windows Server 2008 or older: The first thing to try would be installing the **ADMIN** certificate to the OS @@ -274,15 +318,17 @@ If the issue persists, please also visit the and follow method 3 (**Configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL handshake process**) to set the following registry entry to false: - - -{`HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\SecurityProviders\\SCHANNEL +```plain +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL Value name: SendTrustedIssuerList Value type: REG_DWORD Value data: 0 (False) -`} - - +``` + + + + + ### Authentication Error Occurred using Chrome You cannot access Studio using Chrome, though during @@ -292,29 +338,27 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or open an incognito tab (Ctrl+Shift+N) and paste the server URL into the address bar. 2. If clearing the cache didn't help, manually register the client certificate. - * Chrome versions **earlier than 105** look for certificatees registered **with the OS**. + * Chrome versions **earlier than 105** look for certificates registered **with the OS**. Windows users can register a certificate with the OS by double-clicking its .pfx file and repeatedly clicking `next` for the default settings (or providing custom settings). Linux users can import the certificate directly to the browser. - * Chrome versions **105 and on** look for certificatees registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). + * Chrome versions **105 and on** look for certificates registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). A failure to locate the certificate may be the result of registering it with the OS rather than with the browser. - This failure typically occures when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) - are used rather than with let's encrypt certificates issued during setup, since - let's encrypt certificates are automatically installed in the Chrome root store. + This failure typically occurs when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) + are used rather than with Let's Encrypt certificates issued during setup, since + Let's Encrypt certificates are automatically installed in the Chrome root store. - To import a certificate to chrome's root store use the browser's settings: + To import a certificate to Chrome's root store use the browser's settings: **Settings** > **Privacy and Security** > **Security** > **Manage device certificates** When a "Certificates" window opens, click **Import** and select your PFX certificate. ![Import Certificate](./assets/import-certificate.png) @@ -325,6 +369,11 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + + + + + ### RavenDB is running as a service in Windows and Chrome doesn't use the client certificate from the OS store Your RavenDB service may run under a certain user, for which the certificate was installed, while you @@ -335,36 +384,42 @@ looks for the certificate not at the OS root but at the Chrome root store. To solve these issues: Using a user that the service is available for, install or import the certificate PFX [as described above](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome). + + + + + ### Authentication Error Occurred in Firefox You cannot access the Studio using Firefox even though you have finished the setup wizard successfully and you also checked the box saying "Automatically register the admin client certificate in this (local) OS". ![Figure 2. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
Firefox doesn't use the OS certificate store like Chrome or Edge. Please import the certificate manually (In Firefox, "Settings" -> "Privacy and Security" -> scroll down to Security and click "View Certificates" -> "Import"). Then close **all instances** of the browser and restart it. ![Figure 3. Firefox Import](./assets/2.png) + + + + + ### Cannot Import the Client Certificate to Firefox You're trying to import the client certificate received from RavenDB to Firefox but get the following error: ![Figure 3. Unknown Reasons](./assets/3.png) - - -{`The PKCS#12 operation failed for unknown reasons. -`} - - +```plain +The PKCS#12 operation failed for unknown reasons. +``` +
Firefox fails to import a certificate that is not password protected. To overcome this issue, use the RavenDB CLI to [generate a password protected certificate](../../server/administration/cli.mdx#generateclientcert). @@ -376,7 +431,7 @@ You can try to generate a new password-protected certificate using the RavenDB C If it didn't help, you can use any other client certificate you have that works with Firefox (even if it wasn't generated by RavenDB) and have RavenDB trust it. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). -You can also generate your own self-signed client certificate by using OpenSSL or Powershell. +You can also generate your own self-signed client certificate by using OpenSSL or PowerShell. This is a known issue which has been reported many times to Mozilla. @@ -385,75 +440,127 @@ Some references: [Bugzilla: #1049435](https://bugzilla.mozilla.org/show_bug.cgi?id=1049435) [Bugzilla: #458161](https://bugzilla.mozilla.org/show_bug.cgi?id=458161) [mozilla.dev.tech.crypto issue](https://groups.google.com/forum/?fromgroups=#!topic/mozilla.dev.tech.crypto/RiIeY-R5Q4Y) + + + + + ### Getting the full error using PowerShell You can use PowerShell to make requests using the REST API. If you are having trouble using certificates, take a look at this example which prints the full error (replace the server URL and the `/certificates/whoami` endpoint with yours). - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -$cert = Get-PfxCertificate -FilePath C:\\secrets\\admin.client.certificate.example.pfx +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$cert = Get-PfxCertificate -FilePath C:\secrets\admin.client.certificate.example.pfx -try \{ +try { $response = Invoke-WebRequest https://a.example.development.run:8080/certificates/whoami -Certificate $cert -\} -catch \{ - if ($_.Exception.Response -ne $null) \{ +} +catch { + if ($_.Exception.Response -ne $null) { Write-Host $_.Exception.Message $stream = $_.Exception.Response.GetResponseStream() $reader = New-Object System.IO.StreamReader($stream) Write-Host $reader.ReadToEnd() - \} + } Write-Error $_.Exception -\} -`} - - +} +``` + + + + + ### Not using TLS The RavenDB clients use TLS 1.2 by default. If you want to use other clients please make sure to use the TLS security protocol version 1.2 or 1.3. - - - -{`{ +Bad Request (400) sample response: + +```json +{ "Url":"/admin/secrets/generate", "Type":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException", "Message":"RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'.", "Error":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException: RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'. - at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServer.cs:line 570 - at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 168 - at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 89 + at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServer.cs:line 570 + at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 168 + at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 89 --- End of stack trace from previous location where exception was thrown --- at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) - at System.Runtime.CompilerServices.TaskAwaiter\`1.GetResult() - at System.Runtime.CompilerServices.ValueTaskAwaiter\`1.GetResult() - at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServerStartup.cs:line 159" + at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult() + at System.Runtime.CompilerServices.ValueTaskAwaiter`1.GetResult() + at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServerStartup.cs:line 159" } -`} - - - +``` +
In PowerShell it can be solved like this: - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -`} - - +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +``` + + + + + ### How to regain access to a server when you have physical access but no client certificate -An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli#generateclientcert If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. +An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli.mdx#generateclientcert). If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. Use either the [generateClientCert](../../server/administration/cli.mdx#generateclientcert) command, or (if you already have a certificate) the [trustClientCert](../../server/administration/cli.mdx#trustclientcert) command. Another way to gain access for an existing certificate is to add the [Security.WellKnownCertificates.Admin](../../server/configuration/security-configuration.mdx#securitywellknowncertificatesadmin) configuration to `settings.json` with your existing certificate's thumbprint. In this case, a server restart is required. + + + + + +### "Could not create SSL/TLS secure channel" error under an IIS webhost + +Custom code that connects to RavenDB from an IIS-hosted application can fail with the +following error, even though the same code works when run directly (for example, from a +unit test): + +``` +The request was aborted: Could not create SSL/TLS secure channel. +``` +
+ +This message is generic and does not reveal the real cause. +The underlying error is `Keyset does not exist`: the IIS worker process runs under a +restricted identity (`IIS_IUSRS`, or the application pool identity `IIS AppPool\`) +that has no read access to the private key of the client certificate. +Run directly, the same code loads the certificate under your own user account, which does +have that access. + +To fix this, grant the IIS identity read access to the certificate's private key: + +1. Open the Local Computer certificate store by running `certlm.msc` as an administrator. +2. Under `Personal` > `Certificates`, right-click your client certificate and select + `All Tasks` > `Manage Private Keys`. +3. Add the IIS identity (`IIS_IUSRS`, or `IIS AppPool\` when the pool uses its own + identity) and grant it `Read` permission. + + + +Microsoft documents the same `Manage Private Keys` dialog, in the context of a SQL Server +service account, in [Encrypt connections to SQL Server by importing a certificate](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-sql-server-encryption). + +As an alternative, you can load the certificate into the machine key store programmatically +with the `MachineKeySet` flag, as shown for [Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services). + + + + + + + ### Certificate is not recognized when setting up on Azure App Services You may have gotten an error message like: @@ -461,18 +568,21 @@ You may have gotten an error message like: ``` The credentials supplied to the package were not recognized (The SSL connection could not be established, see inner exception.) ``` +
1) In the app settings of your Azure App Services application, add the `WEBSITE_LOAD_USER_PROFILE = 1` option. 2) Another solution is to use the `MachineKeySet` flag during certificate creation: - - -{`[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", +```csharp +[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", (string)null, X509KeyStorageFlags.MachineKeySet); -`} - - +``` + + + + + ### Automatic cluster certificate renewal following migration to 4.2 `Security.Certificate.Exec` was deprecated in 4.2 and replaced by `Security.Certificate.Load.Exec`. You can use your old `Security.Certificate.Exec` @@ -481,22 +591,22 @@ for automatically persisting the certificate to the whole cluster. If you have y you still need to place empty scripts in the `Security.Certificate.Renew.Exec` and `Security.Certificate.Change.Exec` paths or an exception will be thrown. + + -## Encryption Issues + ### Insufficient Memory Exception - - -{`Memory exception occurred: System.InsufficientMemoryException: +```plain +Memory exception occurred: System.InsufficientMemoryException: Failed to increase the min working set size so we can lock 4,294,967,296 for -D:\\stackoverflow\\RavenData\\Databases\\SO\\Indexes\\Auto_Questions_ByBody\\Temp\\compression.0000000000.buffers. +D:\stackoverflow\RavenData\Databases\SO\Indexes\Auto_Questions_ByBody\Temp\compression.0000000000.buffers. With encrypted databases we lock some memory in order to avoid leaking secrets to disk. Treating this as a catastrophic error and aborting the current operation. -`} - - +``` +
When encryption is turned on, RavenDB locks memory in order to avoid leaking secrets to disk. Read more [here](../../server/security/encryption/encryption-at-rest.mdx#locking-memory). @@ -505,14 +615,13 @@ You can change this behavior but it's not recommended and should be done only af If such a catastrophic error occurs in **Windows**, RavenDB will try to recover automatically by increasing the size of the minimum working set and retrying the operation. In **Linux**, it is the admin's responsibility to configure higher limits manually using: - - -{`sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] -`} - - + +```bash +sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] +``` +
To figure out what the new limit should be, look at the exception thrown by RavenDB, which includes this size. For persistent and service-level configuration, see [Linux: Setting memlock when using encrypted database](../kb/linux-setting-memlock.mdx). - + diff --git a/versioned_docs/version-7.0/server/security/common-errors-and-faq.mdx b/versioned_docs/version-7.0/server/security/common-errors-and-faq.mdx index 35f1d89b34..10437324c3 100644 --- a/versioned_docs/version-7.0/server/security/common-errors-and-faq.mdx +++ b/versioned_docs/version-7.0/server/security/common-errors-and-faq.mdx @@ -10,13 +10,15 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Security: Common Errors & FAQ * This article explains some of the common security configuration errors and how to handle them. -* In this page +* In this article: * [Setup Wizard Issues](../../server/security/common-errors-and-faq.mdx#setup-wizard-issues) * [Changing Configurations and Renewals Issues](../../server/security/common-errors-and-faq.mdx#changing-configurations-and-renewals-issues) * [Authentication Issues](../../server/security/common-errors-and-faq.mdx#authentication-issues) @@ -24,30 +26,31 @@ import LanguageContent from "@site/src/components/LanguageContent"; -## Setup Wizard Issues + * [Server cannot bind to the provided private IP address](../../server/security/common-errors-and-faq.mdx#server-cannot-bind-to-the-provided-private-ip-address) * [Ports are blocked by the firewall](../../server/security/common-errors-and-faq.mdx#ports-are-blocked-by-the-firewall) * [DNS is cached locally](../../server/security/common-errors-and-faq.mdx#dns-is-cached-locally) * [Long DNS propagation time](../../server/security/common-errors-and-faq.mdx#long-dns-propagation-time) * [If I already have the Zip file, can I avoid repeating the setup process?](../../server/security/common-errors-and-faq.mdx#if-i-already-have-the-zip-file-can-i-avoid-repeating-the-setup-process) + + + ### Server cannot bind to the provided private IP address If the IP/port is not accessible on your machine, you'll get the following error. - - -{`System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> +```plain +System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.ravendb.community:4433 ---> System.InvalidOperationException: Failed to start webhost on node 'A'. The specified ip address might not be reachable due to network issues. It can happen if the ip is external (behind a firewall, docker). If this is the case, try going back to the previous screen and add the same ip as an external ip. -Settings file: D:\\temp\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\temp\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.0.65:4433. ---> Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.Internal.Networking.UvException: Error -4092 EACCES permission denied -`} - - +``` +
This can be caused by two different reasons: @@ -55,32 +58,39 @@ This can be caused by two different reasons: 2. You are running behind a firewall (VM, docker...) and accidentally provided the external IP address during setup. Make sure you provide the private IP address in the "IP Address / Hostname" field as seen in [this example](../../start/installation/setup-wizard/configure-node-addresses.mdx#behind-a-firewall-or-load-balancer). + + + + + ### Ports are blocked by the firewall When configuring a VM in Azure, [AWS](../../start/installation/setup-examples/aws-windows-vm.mdx) or any other provider, you should define firewall rules to allow both the **HTTP** and **TCP** ports you have chosen during setup. This should be done both inside the VM operating system **and** in the web dashboard or management console. If ports are blocked you'll get the following error. - - -{`Setting up RavenDB in Let's Encrypt security mode failed. + +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.development.run:443 ---> System.InvalidOperationException: Client failed to contact webhost listening to 'https://a.example.development.run:443'. Are you blocked by a firewall? Make sure the port is open. -Settings file: D:\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.1.4:443. -`} - - +``` + + + + + ### DNS is cached locally Most networks cache DNS records. In some environments you can get an error such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.onenode.development.run ---> @@ -89,20 +99,23 @@ Expected to get these ips: 127.0.0.1 while the actual result was: 10.0.0.65 If we try resolving through google's api (https://dns.google.com), it works well. Try to clear your local/network DNS cache or wait a few minutes and try again. Another temporary solution is to configure your local network connection to use google's DNS server (8.8.8.8). -`} - - +``` +
This error probably means that the DNS is cached. You can wait a few minutes or reset the network DNS cache, but in many cases, the easiest solution is to [temporarily switch your DNS server to 8.8.8.8](https://developers.google.com/speed/public-dns/docs/using) You can click the Try Again button to restart the validation process of the Setup Wizard. + + + + + ### Long DNS propagation time If you are trying to modify existing DNS records, for example running the Setup Wizard again for the same domain name, you may encounter errors such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> @@ -111,12 +124,16 @@ System.InvalidOperationException: Tried to resolve 'a.example.development.run' u Expected to get these ips: 127.0.0.1 while google's actual result was: 10.0.0.65 Please wait a while until DNS propagation is finished and try again. If you are trying to update existing DNS records, it might take hours to update because of DNS caching. If the issue persists, contact RavenDB's support. -`} - - +``` +
If this happens, there is nothing you can do except wait for DNS propagation. When it's updated on dns.google.com click the `Try Again` button. You can keep track of your RavenDB clusters and their associated DNS records at the [Customer's Portal](https://customers.ravendb.net). + + + + + ### If I already have the Zip file, can I avoid repeating the setup process? Yes. @@ -125,16 +142,20 @@ Download a fresh copy of RavenDB and run the setup wizard. Then choose `Continue This will use the existing Zip file and the same configuration and certificate which were previously chosen. When building a cluster, repeat this step with nodes B, C, and so on. + + - -## Changing Configurations and Renewals Issues + * [After installing with Let's Encrypt, can I change the DNS records?](../../server/security/common-errors-and-faq.mdx#after-installing-with-lets-encrypt-can-i-change-the-dns-records) * [Can I change the (private) IP address RavenDB binds to?](../../server/security/common-errors-and-faq.mdx#can-i-change-the-private-ip-address-ravendb-binds-to) * [The Let's Encrypt certificate is about to expire but doesn't renew automatically](../../server/security/common-errors-and-faq.mdx#the-lets-encrypt-certificate-is-about-to-expire-but-doesnt-renew-automatically) * [What should I do when my license expires?](../../server/security/common-errors-and-faq.mdx#what-should-i-do-when-my-license-expires) * [Let's Encrypt certificate permission errors after renewal](../../server/security/common-errors-and-faq.mdx#lets-encrypt-certificate-permission-errors-after-renewal) + + + ### After installing with Let's Encrypt, can I change the DNS records? Yes. @@ -144,31 +165,38 @@ Yes. If you supply different IP addresses then the wizard will update the DNS records of your domain. If you use a new domain or if you add/remove nodes in the new configuration then the wizard will also fetch a new certificate. + + + + + ### Can I change the (private) IP address RavenDB binds to? Yes. Open the [settings.json](../configuration/configuration-options.mdx#json) file located in the RavenDB Server installation folder, change the `ServerUrl` setting and restart the server. + + + + + ### The Let's Encrypt certificate is about to expire but doesn't renew automatically If you are getting the following error you must update the RavenDB server. - - -{`Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: +```plain +Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: Your license is associated with the following domains: ravendb.community but the PublicServerUrl configuration setting is: Raven.Server.Config.Settings.UriSetting.There is a mismatch, therefore cannot automatically renew the Lets Encrypt certificate. Please contact support. -`} - - +``` +
If it's not the same error as above, please open [settings.json](../configuration/configuration-options.mdx#json) in your Server installation and make sure you have all of the fields defined properly. Take a look at the following example: - - -{`\{ +```json +{ "DataDir": "RavenData", "License.Eula.Accepted": true, "Security.Certificate.LetsEncrypt.Email": "your-email@example.com", @@ -179,10 +207,9 @@ and make sure you have all of the fields defined properly. Take a look at the fo "ExternalIp": "35.130.249.162", "PublicServerUrl": "https://a.aws.development.run", "PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888" -\} -`} - - +} +``` +
Things to check: @@ -203,6 +230,11 @@ Things to check: you can contact support. * Make sure to supply the server logs with your ticket. When running in a cluster, please provide the logs from all nodes. * If your logs are turned off, open `Manage Server`->`Admin Logs` in the Studio, and keep them open while you click the `Renew` button in the certificate view. + + + + + ### What should I do when my license expires? * When your license expires the Studio is blocked. @@ -211,6 +243,11 @@ Things to check: and doesn't comply with the [EULA terms](https://ravendb.net/terms). * __Renew your license__ as described in this [Renew License](../../start/licensing/renew-license.mdx) tutorial. + + + + + ### Let's Encrypt certificate permission errors after renewal If you have External Replication or ETL to another cluster, @@ -219,9 +256,11 @@ the next certificate renewal may cause permission issues that need to be handled Learn how to handle this issue [here](../../server/security/authentication/solve-cluster-certificate-renewal-issue.mdx). + + -## Authentication Issues + * [Authentication Error Occurred using Edge](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-edge) * [Authentication Error Occurred using Chrome](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome) @@ -231,8 +270,12 @@ Learn how to handle this issue [here](../../server/security/authentication/solve * [Getting the full error using PowerShell](../../server/security/common-errors-and-faq.mdx#getting-the-full-error-using-powershell) * [Not using TLS](../../server/security/common-errors-and-faq.mdx#not-using-tls) * [How to regain access to a server when you have physical access but no client certificate](../../server/security/common-errors-and-faq.mdx#how-to-regain-access-to-a-server-when-you-have-physical-access-but-no-client-certificate) +* ["Could not create SSL/TLS secure channel" error under an IIS webhost](../../server/security/common-errors-and-faq.mdx#could-not-create-ssltls-secure-channel-error-under-an-iis-webhost) * [Certificate is not recognized when setting up on Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services) * [Automatic cluster certificate renewal following migration to 4.2](../../server/security/common-errors-and-faq.mdx#automatic-cluster-certificate-renewal-following-migration-to-42) + + + ### Authentication Error Occurred using Edge You cannot access Studio using Edge, though during @@ -242,13 +285,11 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or opening an incognito tab and pasting the server URL into the address bar. @@ -264,6 +305,9 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + +--- + #### If your browser runs under Windows 7 or Windows Server 2008 or older: The first thing to try would be installing the **ADMIN** certificate to the OS @@ -274,15 +318,17 @@ If the issue persists, please also visit the and follow method 3 (**Configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL handshake process**) to set the following registry entry to false: - - -{`HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\SecurityProviders\\SCHANNEL +```plain +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL Value name: SendTrustedIssuerList Value type: REG_DWORD Value data: 0 (False) -`} - - +``` + + + + + ### Authentication Error Occurred using Chrome You cannot access Studio using Chrome, though during @@ -292,29 +338,27 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or open an incognito tab (Ctrl+Shift+N) and paste the server URL into the address bar. 2. If clearing the cache didn't help, manually register the client certificate. - * Chrome versions **earlier than 105** look for certificatees registered **with the OS**. + * Chrome versions **earlier than 105** look for certificates registered **with the OS**. Windows users can register a certificate with the OS by double-clicking its .pfx file and repeatedly clicking `next` for the default settings (or providing custom settings). Linux users can import the certificate directly to the browser. - * Chrome versions **105 and on** look for certificatees registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). + * Chrome versions **105 and on** look for certificates registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). A failure to locate the certificate may be the result of registering it with the OS rather than with the browser. - This failure typically occures when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) - are used rather than with let's encrypt certificates issued during setup, since - let's encrypt certificates are automatically installed in the Chrome root store. + This failure typically occurs when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) + are used rather than with Let's Encrypt certificates issued during setup, since + Let's Encrypt certificates are automatically installed in the Chrome root store. - To import a certificate to chrome's root store use the browser's settings: + To import a certificate to Chrome's root store use the browser's settings: **Settings** > **Privacy and Security** > **Security** > **Manage device certificates** When a "Certificates" window opens, click **Import** and select your PFX certificate. ![Import Certificate](./assets/import-certificate.png) @@ -325,6 +369,11 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + + + + + ### RavenDB is running as a service in Windows and Chrome doesn't use the client certificate from the OS store Your RavenDB service may run under a certain user, for which the certificate was installed, while you @@ -335,36 +384,42 @@ looks for the certificate not at the OS root but at the Chrome root store. To solve these issues: Using a user that the service is available for, install or import the certificate PFX [as described above](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome). + + + + + ### Authentication Error Occurred in Firefox You cannot access the Studio using Firefox even though you have finished the setup wizard successfully and you also checked the box saying "Automatically register the admin client certificate in this (local) OS". ![Figure 2. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
Firefox doesn't use the OS certificate store like Chrome or Edge. Please import the certificate manually (In Firefox, "Settings" -> "Privacy and Security" -> scroll down to Security and click "View Certificates" -> "Import"). Then close **all instances** of the browser and restart it. ![Figure 3. Firefox Import](./assets/2.png) + + + + + ### Cannot Import the Client Certificate to Firefox You're trying to import the client certificate received from RavenDB to Firefox but get the following error: ![Figure 3. Unknown Reasons](./assets/3.png) - - -{`The PKCS#12 operation failed for unknown reasons. -`} - - +```plain +The PKCS#12 operation failed for unknown reasons. +``` +
Firefox fails to import a certificate that is not password protected. To overcome this issue, use the RavenDB CLI to [generate a password protected certificate](../../server/administration/cli.mdx#generateclientcert). @@ -376,7 +431,7 @@ You can try to generate a new password-protected certificate using the RavenDB C If it didn't help, you can use any other client certificate you have that works with Firefox (even if it wasn't generated by RavenDB) and have RavenDB trust it. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). -You can also generate your own self-signed client certificate by using OpenSSL or Powershell. +You can also generate your own self-signed client certificate by using OpenSSL or PowerShell. This is a known issue which has been reported many times to Mozilla. @@ -385,75 +440,127 @@ Some references: [Bugzilla: #1049435](https://bugzilla.mozilla.org/show_bug.cgi?id=1049435) [Bugzilla: #458161](https://bugzilla.mozilla.org/show_bug.cgi?id=458161) [mozilla.dev.tech.crypto issue](https://groups.google.com/forum/?fromgroups=#!topic/mozilla.dev.tech.crypto/RiIeY-R5Q4Y) + + + + + ### Getting the full error using PowerShell You can use PowerShell to make requests using the REST API. If you are having trouble using certificates, take a look at this example which prints the full error (replace the server URL and the `/certificates/whoami` endpoint with yours). - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -$cert = Get-PfxCertificate -FilePath C:\\secrets\\admin.client.certificate.example.pfx +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$cert = Get-PfxCertificate -FilePath C:\secrets\admin.client.certificate.example.pfx -try \{ +try { $response = Invoke-WebRequest https://a.example.development.run:8080/certificates/whoami -Certificate $cert -\} -catch \{ - if ($_.Exception.Response -ne $null) \{ +} +catch { + if ($_.Exception.Response -ne $null) { Write-Host $_.Exception.Message $stream = $_.Exception.Response.GetResponseStream() $reader = New-Object System.IO.StreamReader($stream) Write-Host $reader.ReadToEnd() - \} + } Write-Error $_.Exception -\} -`} - - +} +``` + + + + + ### Not using TLS The RavenDB clients use TLS 1.2 by default. If you want to use other clients please make sure to use the TLS security protocol version 1.2 or 1.3. - - - -{`{ +Bad Request (400) sample response: + +```json +{ "Url":"/admin/secrets/generate", "Type":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException", "Message":"RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'.", "Error":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException: RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'. - at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServer.cs:line 570 - at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 168 - at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 89 + at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServer.cs:line 570 + at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 168 + at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 89 --- End of stack trace from previous location where exception was thrown --- at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) - at System.Runtime.CompilerServices.TaskAwaiter\`1.GetResult() - at System.Runtime.CompilerServices.ValueTaskAwaiter\`1.GetResult() - at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServerStartup.cs:line 159" + at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult() + at System.Runtime.CompilerServices.ValueTaskAwaiter`1.GetResult() + at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServerStartup.cs:line 159" } -`} - - - +``` +
In PowerShell it can be solved like this: - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -`} - - +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +``` + + + + + ### How to regain access to a server when you have physical access but no client certificate -An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli#generateclientcert If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. +An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli.mdx#generateclientcert). If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. Use either the [generateClientCert](../../server/administration/cli.mdx#generateclientcert) command, or (if you already have a certificate) the [trustClientCert](../../server/administration/cli.mdx#trustclientcert) command. Another way to gain access for an existing certificate is to add the [Security.WellKnownCertificates.Admin](../../server/configuration/security-configuration.mdx#securitywellknowncertificatesadmin) configuration to `settings.json` with your existing certificate's thumbprint. In this case, a server restart is required. + + + + + +### "Could not create SSL/TLS secure channel" error under an IIS webhost + +Custom code that connects to RavenDB from an IIS-hosted application can fail with the +following error, even though the same code works when run directly (for example, from a +unit test): + +``` +The request was aborted: Could not create SSL/TLS secure channel. +``` +
+ +This message is generic and does not reveal the real cause. +The underlying error is `Keyset does not exist`: the IIS worker process runs under a +restricted identity (`IIS_IUSRS`, or the application pool identity `IIS AppPool\`) +that has no read access to the private key of the client certificate. +Run directly, the same code loads the certificate under your own user account, which does +have that access. + +To fix this, grant the IIS identity read access to the certificate's private key: + +1. Open the Local Computer certificate store by running `certlm.msc` as an administrator. +2. Under `Personal` > `Certificates`, right-click your client certificate and select + `All Tasks` > `Manage Private Keys`. +3. Add the IIS identity (`IIS_IUSRS`, or `IIS AppPool\` when the pool uses its own + identity) and grant it `Read` permission. + + + +Microsoft documents the same `Manage Private Keys` dialog, in the context of a SQL Server +service account, in [Encrypt connections to SQL Server by importing a certificate](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-sql-server-encryption). + +As an alternative, you can load the certificate into the machine key store programmatically +with the `MachineKeySet` flag, as shown for [Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services). + + + + + + + ### Certificate is not recognized when setting up on Azure App Services You may have gotten an error message like: @@ -461,18 +568,21 @@ You may have gotten an error message like: ``` The credentials supplied to the package were not recognized (The SSL connection could not be established, see inner exception.) ``` +
1) In the app settings of your Azure App Services application, add the `WEBSITE_LOAD_USER_PROFILE = 1` option. 2) Another solution is to use the `MachineKeySet` flag during certificate creation: - - -{`[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", +```csharp +[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", (string)null, X509KeyStorageFlags.MachineKeySet); -`} - - +``` + + + + + ### Automatic cluster certificate renewal following migration to 4.2 `Security.Certificate.Exec` was deprecated in 4.2 and replaced by `Security.Certificate.Load.Exec`. You can use your old `Security.Certificate.Exec` @@ -481,22 +591,22 @@ for automatically persisting the certificate to the whole cluster. If you have y you still need to place empty scripts in the `Security.Certificate.Renew.Exec` and `Security.Certificate.Change.Exec` paths or an exception will be thrown. + + -## Encryption Issues + ### Insufficient Memory Exception - - -{`Memory exception occurred: System.InsufficientMemoryException: +```plain +Memory exception occurred: System.InsufficientMemoryException: Failed to increase the min working set size so we can lock 4,294,967,296 for -D:\\stackoverflow\\RavenData\\Databases\\SO\\Indexes\\Auto_Questions_ByBody\\Temp\\compression.0000000000.buffers. +D:\stackoverflow\RavenData\Databases\SO\Indexes\Auto_Questions_ByBody\Temp\compression.0000000000.buffers. With encrypted databases we lock some memory in order to avoid leaking secrets to disk. Treating this as a catastrophic error and aborting the current operation. -`} - - +``` +
When encryption is turned on, RavenDB locks memory in order to avoid leaking secrets to disk. Read more [here](../../server/security/encryption/encryption-at-rest.mdx#locking-memory). @@ -505,14 +615,13 @@ You can change this behavior but it's not recommended and should be done only af If such a catastrophic error occurs in **Windows**, RavenDB will try to recover automatically by increasing the size of the minimum working set and retrying the operation. In **Linux**, it is the admin's responsibility to configure higher limits manually using: - - -{`sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] -`} - - + +```bash +sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] +``` +
To figure out what the new limit should be, look at the exception thrown by RavenDB, which includes this size. For persistent and service-level configuration, see [Linux: Setting memlock when using encrypted database](../kb/linux-setting-memlock.mdx). - + diff --git a/versioned_docs/version-7.1/server/security/common-errors-and-faq.mdx b/versioned_docs/version-7.1/server/security/common-errors-and-faq.mdx index 2e4510052f..10437324c3 100644 --- a/versioned_docs/version-7.1/server/security/common-errors-and-faq.mdx +++ b/versioned_docs/version-7.1/server/security/common-errors-and-faq.mdx @@ -10,13 +10,15 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Security: Common Errors & FAQ * This article explains some of the common security configuration errors and how to handle them. -* In this page +* In this article: * [Setup Wizard Issues](../../server/security/common-errors-and-faq.mdx#setup-wizard-issues) * [Changing Configurations and Renewals Issues](../../server/security/common-errors-and-faq.mdx#changing-configurations-and-renewals-issues) * [Authentication Issues](../../server/security/common-errors-and-faq.mdx#authentication-issues) @@ -24,30 +26,31 @@ import LanguageContent from "@site/src/components/LanguageContent"; -## Setup Wizard Issues + * [Server cannot bind to the provided private IP address](../../server/security/common-errors-and-faq.mdx#server-cannot-bind-to-the-provided-private-ip-address) * [Ports are blocked by the firewall](../../server/security/common-errors-and-faq.mdx#ports-are-blocked-by-the-firewall) * [DNS is cached locally](../../server/security/common-errors-and-faq.mdx#dns-is-cached-locally) * [Long DNS propagation time](../../server/security/common-errors-and-faq.mdx#long-dns-propagation-time) * [If I already have the Zip file, can I avoid repeating the setup process?](../../server/security/common-errors-and-faq.mdx#if-i-already-have-the-zip-file-can-i-avoid-repeating-the-setup-process) + + + ### Server cannot bind to the provided private IP address If the IP/port is not accessible on your machine, you'll get the following error. - - -{`System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> +```plain +System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.ravendb.community:4433 ---> System.InvalidOperationException: Failed to start webhost on node 'A'. The specified ip address might not be reachable due to network issues. It can happen if the ip is external (behind a firewall, docker). If this is the case, try going back to the previous screen and add the same ip as an external ip. -Settings file: D:\\temp\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\temp\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.0.65:4433. ---> Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.Internal.Networking.UvException: Error -4092 EACCES permission denied -`} - - +``` +
This can be caused by two different reasons: @@ -55,32 +58,39 @@ This can be caused by two different reasons: 2. You are running behind a firewall (VM, docker...) and accidentally provided the external IP address during setup. Make sure you provide the private IP address in the "IP Address / Hostname" field as seen in [this example](../../start/installation/setup-wizard/configure-node-addresses.mdx#behind-a-firewall-or-load-balancer). + + + + + ### Ports are blocked by the firewall When configuring a VM in Azure, [AWS](../../start/installation/setup-examples/aws-windows-vm.mdx) or any other provider, you should define firewall rules to allow both the **HTTP** and **TCP** ports you have chosen during setup. This should be done both inside the VM operating system **and** in the web dashboard or management console. If ports are blocked you'll get the following error. - - -{`Setting up RavenDB in Let's Encrypt security mode failed. + +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.example.development.run:443 ---> System.InvalidOperationException: Client failed to contact webhost listening to 'https://a.example.development.run:443'. Are you blocked by a firewall? Make sure the port is open. -Settings file: D:\\RavenDB-4.0.0-windows-x64\\Server\\settings.json. +Settings file: D:\RavenDB-4.0.0-windows-x64\Server\settings.json. IP addresses: 10.0.1.4:443. -`} - - +``` + + + + + ### DNS is cached locally Most networks cache DNS records. In some environments you can get an error such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.onenode.development.run ---> @@ -89,20 +99,23 @@ Expected to get these ips: 127.0.0.1 while the actual result was: 10.0.0.65 If we try resolving through google's api (https://dns.google.com), it works well. Try to clear your local/network DNS cache or wait a few minutes and try again. Another temporary solution is to configure your local network connection to use google's DNS server (8.8.8.8). -`} - - +``` +
This error probably means that the DNS is cached. You can wait a few minutes or reset the network DNS cache, but in many cases, the easiest solution is to [temporarily switch your DNS server to 8.8.8.8](https://developers.google.com/speed/public-dns/docs/using) You can click the Try Again button to restart the validation process of the Setup Wizard. + + + + + ### Long DNS propagation time If you are trying to modify existing DNS records, for example running the Setup Wizard again for the same domain name, you may encounter errors such as this: - - -{`Setting up RavenDB in Let's Encrypt security mode failed. +```plain +Setting up RavenDB in Let's Encrypt security mode failed. System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. ---> System.InvalidOperationException: Validation failed. ---> @@ -111,12 +124,16 @@ System.InvalidOperationException: Tried to resolve 'a.example.development.run' u Expected to get these ips: 127.0.0.1 while google's actual result was: 10.0.0.65 Please wait a while until DNS propagation is finished and try again. If you are trying to update existing DNS records, it might take hours to update because of DNS caching. If the issue persists, contact RavenDB's support. -`} - - +``` +
If this happens, there is nothing you can do except wait for DNS propagation. When it's updated on dns.google.com click the `Try Again` button. You can keep track of your RavenDB clusters and their associated DNS records at the [Customer's Portal](https://customers.ravendb.net). + + + + + ### If I already have the Zip file, can I avoid repeating the setup process? Yes. @@ -125,16 +142,20 @@ Download a fresh copy of RavenDB and run the setup wizard. Then choose `Continue This will use the existing Zip file and the same configuration and certificate which were previously chosen. When building a cluster, repeat this step with nodes B, C, and so on. + + - -## Changing Configurations and Renewals Issues + * [After installing with Let's Encrypt, can I change the DNS records?](../../server/security/common-errors-and-faq.mdx#after-installing-with-lets-encrypt-can-i-change-the-dns-records) * [Can I change the (private) IP address RavenDB binds to?](../../server/security/common-errors-and-faq.mdx#can-i-change-the-private-ip-address-ravendb-binds-to) * [The Let's Encrypt certificate is about to expire but doesn't renew automatically](../../server/security/common-errors-and-faq.mdx#the-lets-encrypt-certificate-is-about-to-expire-but-doesnt-renew-automatically) * [What should I do when my license expires?](../../server/security/common-errors-and-faq.mdx#what-should-i-do-when-my-license-expires) * [Let's Encrypt certificate permission errors after renewal](../../server/security/common-errors-and-faq.mdx#lets-encrypt-certificate-permission-errors-after-renewal) + + + ### After installing with Let's Encrypt, can I change the DNS records? Yes. @@ -144,31 +165,38 @@ Yes. If you supply different IP addresses then the wizard will update the DNS records of your domain. If you use a new domain or if you add/remove nodes in the new configuration then the wizard will also fetch a new certificate. + + + + + ### Can I change the (private) IP address RavenDB binds to? Yes. Open the [settings.json](../configuration/configuration-options.mdx#json) file located in the RavenDB Server installation folder, change the `ServerUrl` setting and restart the server. + + + + + ### The Let's Encrypt certificate is about to expire but doesn't renew automatically If you are getting the following error you must update the RavenDB server. - - -{`Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: +```plain +Failed to update certificate from Lets Encrypt, EXCEPTION: System.InvalidOperationException: Your license is associated with the following domains: ravendb.community but the PublicServerUrl configuration setting is: Raven.Server.Config.Settings.UriSetting.There is a mismatch, therefore cannot automatically renew the Lets Encrypt certificate. Please contact support. -`} - - +``` +
If it's not the same error as above, please open [settings.json](../configuration/configuration-options.mdx#json) in your Server installation and make sure you have all of the fields defined properly. Take a look at the following example: - - -{`\{ +```json +{ "DataDir": "RavenData", "License.Eula.Accepted": true, "Security.Certificate.LetsEncrypt.Email": "your-email@example.com", @@ -179,10 +207,9 @@ and make sure you have all of the fields defined properly. Take a look at the fo "ExternalIp": "35.130.249.162", "PublicServerUrl": "https://a.aws.development.run", "PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888" -\} -`} - - +} +``` +
Things to check: @@ -203,6 +230,11 @@ Things to check: you can contact support. * Make sure to supply the server logs with your ticket. When running in a cluster, please provide the logs from all nodes. * If your logs are turned off, open `Manage Server`->`Admin Logs` in the Studio, and keep them open while you click the `Renew` button in the certificate view. + + + + + ### What should I do when my license expires? * When your license expires the Studio is blocked. @@ -211,6 +243,11 @@ Things to check: and doesn't comply with the [EULA terms](https://ravendb.net/terms). * __Renew your license__ as described in this [Renew License](../../start/licensing/renew-license.mdx) tutorial. + + + + + ### Let's Encrypt certificate permission errors after renewal If you have External Replication or ETL to another cluster, @@ -219,9 +256,11 @@ the next certificate renewal may cause permission issues that need to be handled Learn how to handle this issue [here](../../server/security/authentication/solve-cluster-certificate-renewal-issue.mdx). + + -## Authentication Issues + * [Authentication Error Occurred using Edge](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-edge) * [Authentication Error Occurred using Chrome](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome) @@ -231,8 +270,12 @@ Learn how to handle this issue [here](../../server/security/authentication/solve * [Getting the full error using PowerShell](../../server/security/common-errors-and-faq.mdx#getting-the-full-error-using-powershell) * [Not using TLS](../../server/security/common-errors-and-faq.mdx#not-using-tls) * [How to regain access to a server when you have physical access but no client certificate](../../server/security/common-errors-and-faq.mdx#how-to-regain-access-to-a-server-when-you-have-physical-access-but-no-client-certificate) +* ["Could not create SSL/TLS secure channel" error under an IIS webhost](../../server/security/common-errors-and-faq.mdx#could-not-create-ssltls-secure-channel-error-under-an-iis-webhost) * [Certificate is not recognized when setting up on Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services) * [Automatic cluster certificate renewal following migration to 4.2](../../server/security/common-errors-and-faq.mdx#automatic-cluster-certificate-renewal-following-migration-to-42) + + + ### Authentication Error Occurred using Edge You cannot access Studio using Edge, though during @@ -242,13 +285,11 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or opening an incognito tab and pasting the server URL into the address bar. @@ -264,9 +305,12 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + +--- + #### If your browser runs under Windows 7 or Windows Server 2008 or older: -The first thing to try would be installing the **ADMIN** certificate to the OS +The first thing to try would be installing the **ADMIN** certificate to the OS where your server is running, closing **all instances** of the browser and restarting it. If the issue persists, please also visit the @@ -274,15 +318,17 @@ If the issue persists, please also visit the and follow method 3 (**Configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL handshake process**) to set the following registry entry to false: - - -{`HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\SecurityProviders\\SCHANNEL +```plain +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL Value name: SendTrustedIssuerList Value type: REG_DWORD Value data: 0 (False) -`} - - +``` + + + + + ### Authentication Error Occurred using Chrome You cannot access Studio using Chrome, though during @@ -292,29 +338,27 @@ and the setup wizard ended successfully. ![Figure 1. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
1. Try closing **all instances** of the browser and restarting it, or open an incognito tab (Ctrl+Shift+N) and paste the server URL into the address bar. 2. If clearing the cache didn't help, manually register the client certificate. - * Chrome versions **earlier than 105** look for certificatees registered **with the OS**. + * Chrome versions **earlier than 105** look for certificates registered **with the OS**. Windows users can register a certificate with the OS by double-clicking its .pfx file and repeatedly clicking `next` for the default settings (or providing custom settings). Linux users can import the certificate directly to the browser. - * Chrome versions **105 and on** look for certificatees registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). + * Chrome versions **105 and on** look for certificates registered with the browser's [root store](https://blog.chromium.org/2022/09/announcing-launch-of-chrome-root-program.html). A failure to locate the certificate may be the result of registering it with the OS rather than with the browser. - This failure typically occures when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) - are used rather than with let's encrypt certificates issued during setup, since - let's encrypt certificates are automatically installed in the Chrome root store. + This failure typically occurs when [self-signed certificates](../../server/security/authentication/certificate-configuration.mdx) + are used rather than with Let's Encrypt certificates issued during setup, since + Let's Encrypt certificates are automatically installed in the Chrome root store. - To import a certificate to chrome's root store use the browser's settings: + To import a certificate to Chrome's root store use the browser's settings: **Settings** > **Privacy and Security** > **Security** > **Manage device certificates** When a "Certificates" window opens, click **Import** and select your PFX certificate. ![Import Certificate](./assets/import-certificate.png) @@ -325,6 +369,11 @@ This server requires client certificate for authentication, but none was provide 4. In case none of the above works, you can use your own certificate and have RavenDB trust it. You can use any client certificate that works under your OS and browser, even if it wasn't generated by RavenDB. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). + + + + + ### RavenDB is running as a service in Windows and Chrome doesn't use the client certificate from the OS store Your RavenDB service may run under a certain user, for which the certificate was installed, while you @@ -335,36 +384,42 @@ looks for the certificate not at the OS root but at the Chrome root store. To solve these issues: Using a user that the service is available for, install or import the certificate PFX [as described above](../../server/security/common-errors-and-faq.mdx#authentication-error-occurred-using-chrome). + + + + + ### Authentication Error Occurred in Firefox You cannot access the Studio using Firefox even though you have finished the setup wizard successfully and you also checked the box saying "Automatically register the admin client certificate in this (local) OS". ![Figure 2. Authentication Error](./assets/1.png) - - -{`There were problems authenticating the request: +```plain +There were problems authenticating the request: This server requires client certificate for authentication, but none was provided by the client. -`} - - +``` +
Firefox doesn't use the OS certificate store like Chrome or Edge. Please import the certificate manually (In Firefox, "Settings" -> "Privacy and Security" -> scroll down to Security and click "View Certificates" -> "Import"). Then close **all instances** of the browser and restart it. ![Figure 3. Firefox Import](./assets/2.png) + + + + + ### Cannot Import the Client Certificate to Firefox You're trying to import the client certificate received from RavenDB to Firefox but get the following error: ![Figure 3. Unknown Reasons](./assets/3.png) - - -{`The PKCS#12 operation failed for unknown reasons. -`} - - +```plain +The PKCS#12 operation failed for unknown reasons. +``` +
Firefox fails to import a certificate that is not password protected. To overcome this issue, use the RavenDB CLI to [generate a password protected certificate](../../server/administration/cli.mdx#generateclientcert). @@ -376,7 +431,7 @@ You can try to generate a new password-protected certificate using the RavenDB C If it didn't help, you can use any other client certificate you have that works with Firefox (even if it wasn't generated by RavenDB) and have RavenDB trust it. See [trusting an existing certificate](../../server/administration/cli.mdx#trustclientcert). -You can also generate your own self-signed client certificate by using OpenSSL or Powershell. +You can also generate your own self-signed client certificate by using OpenSSL or PowerShell. This is a known issue which has been reported many times to Mozilla. @@ -385,75 +440,127 @@ Some references: [Bugzilla: #1049435](https://bugzilla.mozilla.org/show_bug.cgi?id=1049435) [Bugzilla: #458161](https://bugzilla.mozilla.org/show_bug.cgi?id=458161) [mozilla.dev.tech.crypto issue](https://groups.google.com/forum/?fromgroups=#!topic/mozilla.dev.tech.crypto/RiIeY-R5Q4Y) + + + + + ### Getting the full error using PowerShell You can use PowerShell to make requests using the REST API. If you are having trouble using certificates, take a look at this example which prints the full error (replace the server URL and the `/certificates/whoami` endpoint with yours). - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -$cert = Get-PfxCertificate -FilePath C:\\secrets\\admin.client.certificate.example.pfx +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$cert = Get-PfxCertificate -FilePath C:\secrets\admin.client.certificate.example.pfx -try \{ +try { $response = Invoke-WebRequest https://a.example.development.run:8080/certificates/whoami -Certificate $cert -\} -catch \{ - if ($_.Exception.Response -ne $null) \{ +} +catch { + if ($_.Exception.Response -ne $null) { Write-Host $_.Exception.Message $stream = $_.Exception.Response.GetResponseStream() $reader = New-Object System.IO.StreamReader($stream) Write-Host $reader.ReadToEnd() - \} + } Write-Error $_.Exception -\} -`} - - +} +``` + + + + + ### Not using TLS The RavenDB clients use TLS 1.2 by default. If you want to use other clients please make sure to use the TLS security protocol version 1.2 or 1.3. - - - -{`{ +Bad Request (400) sample response: + +```json +{ "Url":"/admin/secrets/generate", "Type":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException", "Message":"RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'.", "Error":"Raven.Client.Exceptions.Security.InsufficientTransportLayerProtectionException: RavenDB requires clients to connect using TLS 1.2, but the client used: 'Tls'. - at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServer.cs:line 570 - at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 168 - at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\Routing\\\\RequestRouter.cs:line 89 + at Raven.Server.RavenServer.AuthenticateConnection.ThrowException() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServer.cs:line 570 + at Raven.Server.Routing.RequestRouter.TryAuthorize(RouteInformation route, HttpContext context, DocumentDatabase database) in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 168 + at Raven.Server.Routing.RequestRouter.d__6.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\Routing\\RequestRouter.cs:line 89 --- End of stack trace from previous location where exception was thrown --- at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) - at System.Runtime.CompilerServices.TaskAwaiter\`1.GetResult() - at System.Runtime.CompilerServices.ValueTaskAwaiter\`1.GetResult() - at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\\\Builds\\\\RavenDB-Stable-4.0\\\\src\\\\Raven.Server\\\\RavenServerStartup.cs:line 159" + at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult() + at System.Runtime.CompilerServices.ValueTaskAwaiter`1.GetResult() + at Raven.Server.RavenServerStartup.d__11.MoveNext() in C:\\Builds\\RavenDB-Stable-4.0\\src\\Raven.Server\\RavenServerStartup.cs:line 159" } -`} - - - +``` +
In PowerShell it can be solved like this: - - -{`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 -`} - - +```powershell +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +``` + + + + + ### How to regain access to a server when you have physical access but no client certificate -An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli#generateclientcert If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. +An admin client certificate can be generated through the [RavenDB CLI](../../server/administration/cli.mdx#generateclientcert). If RavenDB runs as a console application, the CLI is just there. When running as a service, please use the `rvn admin-channel`. Use either the [generateClientCert](../../server/administration/cli.mdx#generateclientcert) command, or (if you already have a certificate) the [trustClientCert](../../server/administration/cli.mdx#trustclientcert) command. Another way to gain access for an existing certificate is to add the [Security.WellKnownCertificates.Admin](../../server/configuration/security-configuration.mdx#securitywellknowncertificatesadmin) configuration to `settings.json` with your existing certificate's thumbprint. In this case, a server restart is required. + + + + + +### "Could not create SSL/TLS secure channel" error under an IIS webhost + +Custom code that connects to RavenDB from an IIS-hosted application can fail with the +following error, even though the same code works when run directly (for example, from a +unit test): + +``` +The request was aborted: Could not create SSL/TLS secure channel. +``` +
+ +This message is generic and does not reveal the real cause. +The underlying error is `Keyset does not exist`: the IIS worker process runs under a +restricted identity (`IIS_IUSRS`, or the application pool identity `IIS AppPool\`) +that has no read access to the private key of the client certificate. +Run directly, the same code loads the certificate under your own user account, which does +have that access. + +To fix this, grant the IIS identity read access to the certificate's private key: + +1. Open the Local Computer certificate store by running `certlm.msc` as an administrator. +2. Under `Personal` > `Certificates`, right-click your client certificate and select + `All Tasks` > `Manage Private Keys`. +3. Add the IIS identity (`IIS_IUSRS`, or `IIS AppPool\` when the pool uses its own + identity) and grant it `Read` permission. + + + +Microsoft documents the same `Manage Private Keys` dialog, in the context of a SQL Server +service account, in [Encrypt connections to SQL Server by importing a certificate](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-sql-server-encryption). + +As an alternative, you can load the certificate into the machine key store programmatically +with the `MachineKeySet` flag, as shown for [Azure App Services](../../server/security/common-errors-and-faq.mdx#certificate-is-not-recognized-when-setting-up-on-azure-app-services). + + + + + + + ### Certificate is not recognized when setting up on Azure App Services You may have gotten an error message like: @@ -461,18 +568,21 @@ You may have gotten an error message like: ``` The credentials supplied to the package were not recognized (The SSL connection could not be established, see inner exception.) ``` +
1) In the app settings of your Azure App Services application, add the `WEBSITE_LOAD_USER_PROFILE = 1` option. 2) Another solution is to use the `MachineKeySet` flag during certificate creation: - - -{`[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", +```csharp +[DocumentStore].Certificate = new X509Certificate2("[path to your pfx file]", (string)null, X509KeyStorageFlags.MachineKeySet); -`} - - +``` + + + + + ### Automatic cluster certificate renewal following migration to 4.2 `Security.Certificate.Exec` was deprecated in 4.2 and replaced by `Security.Certificate.Load.Exec`. You can use your old `Security.Certificate.Exec` @@ -481,22 +591,22 @@ for automatically persisting the certificate to the whole cluster. If you have y you still need to place empty scripts in the `Security.Certificate.Renew.Exec` and `Security.Certificate.Change.Exec` paths or an exception will be thrown. + + -## Encryption Issues + ### Insufficient Memory Exception - - -{`Memory exception occurred: System.InsufficientMemoryException: +```plain +Memory exception occurred: System.InsufficientMemoryException: Failed to increase the min working set size so we can lock 4,294,967,296 for -D:\\stackoverflow\\RavenData\\Databases\\SO\\Indexes\\Auto_Questions_ByBody\\Temp\\compression.0000000000.buffers. +D:\stackoverflow\RavenData\Databases\SO\Indexes\Auto_Questions_ByBody\Temp\compression.0000000000.buffers. With encrypted databases we lock some memory in order to avoid leaking secrets to disk. Treating this as a catastrophic error and aborting the current operation. -`} - - +``` +
When encryption is turned on, RavenDB locks memory in order to avoid leaking secrets to disk. Read more [here](../../server/security/encryption/encryption-at-rest.mdx#locking-memory). @@ -505,14 +615,13 @@ You can change this behavior but it's not recommended and should be done only af If such a catastrophic error occurs in **Windows**, RavenDB will try to recover automatically by increasing the size of the minimum working set and retrying the operation. In **Linux**, it is the admin's responsibility to configure higher limits manually using: - - -{`sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] -`} - - + +```bash +sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes] +``` +
To figure out what the new limit should be, look at the exception thrown by RavenDB, which includes this size. For persistent and service-level configuration, see [Linux: Setting memlock when using encrypted database](../kb/linux-setting-memlock.mdx). - +