Skip to content

Commit

Permalink
Grammar check.
Browse files Browse the repository at this point in the history
  • Loading branch information
davidbh committed Nov 21, 2018
1 parent 613103e commit 923e5cf
Show file tree
Hide file tree
Showing 4 changed files with 66 additions and 66 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,6 @@ To ensure database exists before creating it we can use the following example

{NOTE Creation of a database requires admin certificate /}

## Related articles
## Related Articles
- [Distributed Database](../../../server/clustering/distribution/distributed-database)
- [Create Database via Studio](../../../studio/server/databases/create-new-database/general-flow)
Original file line number Diff line number Diff line change
Expand Up @@ -120,17 +120,17 @@ 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#json) and make sure you have all the field defined properly. Take a look at the following example:

{CODE-BLOCK:JSON}
{
"DataDir": "RavenData",
"License.Eula.Accepted": true,
"Security.Certificate.LetsEncrypt.Email": "[email protected]",
"Setup.Mode": "LetsEncrypt",
"Security.Certificate.Path": "cluster.server.certificate.aws.pfx",
"ServerUrl": "https://172.31.30.163",
"ServerUrl.Tcp": "tcp://172.31.30.163:38888",
"ExternalIp": "35.130.249.162",
"PublicServerUrl": "https://a.aws.development.run",
"PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888"
{
"DataDir": "RavenData",
"License.Eula.Accepted": true,
"Security.Certificate.LetsEncrypt.Email": "[email protected]",
"Setup.Mode": "LetsEncrypt",
"Security.Certificate.Path": "cluster.server.certificate.aws.pfx",
"ServerUrl": "https://172.31.30.163",
"ServerUrl.Tcp": "tcp://172.31.30.163:38888",
"ExternalIp": "35.130.249.162",
"PublicServerUrl": "https://a.aws.development.run",
"PublicServerUrl.Tcp": "tcp://a.aws.development.run:38888"
}
{CODE-BLOCK/}
Things to check:
Expand Down Expand Up @@ -305,11 +305,11 @@ Memory exception occurred: System.InsufficientMemoryException: Failed to increas

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#locking-memory).

By default RavenDB treats this error as catastrophic and will not continue the operation.
By default, RavenDB treats this error as catastrophic and will not continue the operation.
You can change this behavior but it's not recommended and should be done only after a proper security analysis is performed, see the [Security Configuration Section](../../server/configuration/security-configuration#security.donotconsidermemorylockfailureascatastrophicerror).

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 responibility to configure higher limits manually using:
In **Linux**, it is the admin's responsibility to configure higher limits manually using:
{CODE-BLOCK:plain}
sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes]
{CODE-BLOCK/}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

Encryption at rest is implemented at the storage layer, using Daniel J. Bernstein's `XChaCha20-Poly1305` authenticated encryption algorithm.

## What does it mean?
## What Does it Mean?

In [Voron](../../../server/storage/storage-engine), the storage engine behind RavenDB, data is stored in memory mapped files. This includes documents, indexes, attachments and transactions which are written to the journal.

If your disk is stolen or lost, an attacker will have full access to the raw data files and without encryption turned on, the data can be read with very little effort.
If your disk is stolen or lost, an attacker will have full access to the raw data files and without encryption turned on the data can be read with very little effort.

On the other hand, when encryption is turned on - the raw data is encrypted and unreadable without possession of the secret key.
On the other hand, when encryption is turned on the raw data is encrypted and unreadable without possession of the secret key.

In RavenDB, encryption is done at the lowest possible layer, the storage engine. It is fully transparent to other levels of the server, making it super easy to use.

## How does it work?
## How Does it Work?

As long as the database is idle and there are no requests to serve, everything is kept encrypted in the data files.

Expand All @@ -21,13 +21,13 @@ Once a request is made, RavenDB will start a transaction (either read or write)
{DANGER: Important things to be aware of:}
1. RavenDB makes sure that **no data is written to disk as plain text**. It will always be encrypted.
2. Indexed fields (the actual data) will reside in memory as plain text.
3. Data of the current transaction will reside in memory as plain text, and only for the duration of the transaction. When the transaction ends, the used memory is safely zeroed.
3. Data of the current transaction will reside in memory as plain text and only for the duration of the transaction. When the transaction ends, the used memory is safely zeroed.
4. Loading documents from the database (using the Studio, the Client API, REST API) means that they will be decrypted to plain text on the server and then sent to the client (securely) by HTTPS. Once the data is received on the client side it is no longer encrypted. RavenDB does not provide encryption on the client side.
{DANGER/}

{NOTE Due to the overhead of the encryption algorithm, performance can be slightly decreased. However, it doesn't affect the ACID properties of RavenDB which remains both transactional and secured./}
{NOTE Due to the overhead of the encryption algorithm, performance can be slightly decreased. However, it doesn't affect the ACID properties of RavenDB which remains both transactional and secure./}

## Locking memory
## Locking Memory

RavenDB uses memory-mapped files to keep its data. During normal operations, a process's memory regions may be paged by the OS to a file on disk when RAM has become scarce.

Expand All @@ -41,7 +41,7 @@ The downside to this approach is that if we run out of physical RAM RavenDB won'
You can change this behavior but it's not recommended and should be done only after a proper security analysis is performed, see the [Security Configuration Section](../../../server/configuration/security-configuration#security.donotconsidermemorylockfailureascatastrophicerror).

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 responibility to configure higher limits manually using:
In **Linux**, it is the admin's responsibility to configure higher limits manually using:
{CODE-BLOCK:plain}
sudo prlimit --pid [process-id] --memlock=[new-limit-in-bytes]
{CODE-BLOCK/}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,43 +1,43 @@
# Authentication : Certificate Renewal & Rotation

X.509 certificates have expiration dates and must be renewed once in a while.

When using the Setup Wizard to obtain a Let's Encrypt certificate, you don't have to worry about this. Read about [Automatic Let's Encrypt Renewals in RavenDB](../../../server/security/authentication/lets-encrypt-certificates).

If you provided your own certificate to RavenDB, it is **your responsibility** to renew it.

Once you have a new valid certificate for your server/cluster you need to make RavenDB use it instead of the currently loaded certificate. Replacing a certificate in the cluster is a distributed operation which requires all the nodes to confirm the replacement. The actual update will happen when all nodes of the cluster confirm the replacement or when there are 3 days left for expiration.

You can also ignore these limits and replace the certificates immediately but beware of this option. Nodes which didn't confirm the replacement, will not be able to re-join the cluster and will have to be setup manually. This means the new certificate will have to be placed manually in that node.

To manually replace the server certificate you can either edit [settings.json](../../configuration/configuration-options#json) with a new certificate path and restart the server or you can overwrite the existing certificate file and the server will pick it up within one hour without requiring a restart.

{DANGER The new certificate must contain all of the cluster domain names in the CN or ASN properties of the certificate. Otherwise you will get an authentication error because SSL/TLS requires the domain in the certificate to match with the actual domain being used. /}

## Replace the Cluster Certificate using the Studio

Access the certificate view, click on `Cluster certificate` -> `Replace cluster certificate` and upload the new certificate PFX file.

This will start the certificate replacement process.

When running as a cluster the replacement process is a distributed operation. It involves sending the new certificate to all nodes, and requires all nodes to confirm receipt and replacement of the certificate.

Only when all nodes have confirmed, the cluster will start using this new certificate.

If a node is not responding during the replacement, the operation will not complete until one of the following happens:

* The node will come back online. It should pick up the replacement command and join the replacement process automatically.

* There are only 3 days left for the expiration of the certificate. In this case, the cluster will complete the operation without the node which is down. When bringing that node up, the certificate must be replaced manually.

* `Replace immediately` is chosen. In this case, the cluster will complete the operation without the node which is down. When bringing that node up, the certificate must be replaced manually.

During the process you will receive alerts in the studio and in the logs indicating the status of the operation and any errors if they occur. The alerts are displayed for each node independently.

## Replace the Cluster Certificate using Powershell

Here is a little example of using the REST API directly with powershell to replace the cluster certificate:

# Authentication : Certificate Renewal & Rotation

X.509 certificates have expiration dates and must be renewed once in a while.

When using the Setup Wizard to obtain a Let's Encrypt certificate, you don't have to worry about this. Read about [Automatic Let's Encrypt Renewals in RavenDB](../../../server/security/authentication/lets-encrypt-certificates).

If you provided your own certificate to RavenDB, it is **your responsibility** to renew it.

Once you have a new valid certificate for your server/cluster you need to make RavenDB use it instead of the currently loaded certificate. Replacing a certificate in the cluster is a distributed operation which requires all the nodes to confirm the replacement. The actual update will happen when all nodes of the cluster confirm the replacement or when there are 3 days left for expiration.

You can also ignore these limits and replace the certificates immediately but beware of this option. Nodes which didn't confirm the replacement, will not be able to re-join the cluster and will have to be setup manually. This means the new certificate will have to be placed manually in that node.

To manually replace the server certificate you can either edit [settings.json](../../configuration/configuration-options#json) with a new certificate path and restart the server or you can overwrite the existing certificate file and the server will pick it up within one hour without requiring a restart.

{DANGER The new certificate must contain all of the cluster domain names in the CN or ASN properties of the certificate. Otherwise you will get an authentication error because SSL/TLS requires the domain in the certificate to match with the actual domain being used. /}

## Replace the Cluster Certificate Using the Studio

Access the certificate view, click on `Cluster certificate` -> `Replace cluster certificate` and upload the new certificate PFX file.

This will start the certificate replacement process.

When running as a cluster, the replacement process is a distributed operation. It involves sending the new certificate to all nodes, and requires all nodes to confirm receipt and replacement of the certificate.

Only when all nodes have confirmed, the cluster will start using this new certificate.

If a node is not responding during the replacement, the operation will not complete until one of the following happens:

* The node will come back online. It should pick up the replacement command and join the replacement process automatically.

* There are only 3 days left for the expiration of the certificate. In this case, the cluster will complete the operation without the node which is down. When bringing that node up, the certificate must be replaced manually.

* `Replace immediately` is chosen. In this case, the cluster will complete the operation without the node which is down. When bringing that node up, the certificate must be replaced manually.

During the process you will receive alerts in the studio and in the logs indicating the status of the operation and any errors if they occur. The alerts are displayed for each node independently.

## Replace the Cluster Certificate Using Powershell

Here is a little example of using the REST API directly with powershell to replace the cluster certificate:

{CODE-BLOCK:powershell}
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Expand All @@ -53,10 +53,10 @@ $payload = @{
} | ConvertTo-Json

$response = Invoke-WebRequest https://b.raven.development.run:8080/admin/certificates/replace-cluster-cert -Certificate $clientCert -Method POST -Body $payload -ContentType "application/json"
{CODE-BLOCK/}


## Related articles
{CODE-BLOCK/}


## Related Articles

### Security

Expand Down

0 comments on commit 923e5cf

Please sign in to comment.