Skip to content

Commit

Permalink
Updates to Security chapter.
Browse files Browse the repository at this point in the history
  • Loading branch information
@kennethpjdyer
kennethpjdyer committed Nov 26, 2015
1 parent b515578 commit 48a3b14
Show file tree
Hide file tree
Showing 3 changed files with 210 additions and 174 deletions.
98 changes: 53 additions & 45 deletions Database-Encryption.md
View file
Original file line number Diff line number Diff line change
@@ -1,43 +1,49 @@
# Database Encryption

(Since 2.2 - Status: Beta, will be final with 2.2 GA)
Beginning with version 2.2, OrientDB can encrypt records on disk. This prevents unauthorized users from accessing database content or even from bypassing OrientDB security. OrientDB does not save the encryption key to the database. You must provide it at run-time. In the event that you lose the encryption key, the database, (or at least the parts of the database you have encrypted), you lose access to its content.

See also:
- [Database security](Database-Security.md)
- [Server security](Server-Security.md)
- [Secure SSL connections](Using-SSL-with-OrientDB.md)
> **NOTE**: As of 2.2 this feature is in beta. It will be final with 2.2 GA.
Starting from v2.2, OrientDB can encrypt the records on disk. This denies anybody from accessing to the database content, even bypassing the OrientDB security system. The encryption key is not saved in database but must be provided at run-time. If the encryption key is lost, the database, or the encrypted portion, can't be read anymore.
Encryption works through the encryption interface. It acts at the cluster (collection) level. OrientDB supports two algorithms for encryption:

Encryption uses the "encryption" interface and act at cluster (collection) level. The supported algorithms are:
- `aes` that uses [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
- `des` that uses [DES](https://en.wikipedia.org/wiki/Data_Encryption_Standard)
- `aes` algorithm, which uses [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
- `des` algorithm, which uses [DES](https://en.wikipedia.org/wiki/Data_Encryption_Standard)

**AES** algorithm is preferable to DES because it's stronger.
The AES algorithm is preferable to DES, given that it's stronger.

OrientDB encryption works at database level. Having multiple databases with different encryptions under the same Server (or JVM OrientDB is running embedded) is allowed. For this reason encryption settings are per-database. However you can use the global configuration to use the same encryption rules to all the database open in the same JVM. Example of global configuration via Java API:
Encryption in OrientDB operates at the database-level. You can have multiple databases, each with different encryption interfaces, running under the same server, (or, JVM, in the event that you run OrientDB embedded). That said, you can use global configurations to define the same encryption rules for all databases open in the same JVM. For instance, you can define rules through the Java API:

```java
OGlobalConfiguration.STORAGE_ENCRYPTION_METHOD.setValue("aes");
OGlobalConfiguration.STORAGE_ENCRYPTION_KEY.setValue("T1JJRU5UREJfSVNfQ09PTA==");
```
And at startup by passing these settings as JVM arguments:

```
java ... -Dstorage.encryptionMethod=aes -Dstorage.encryptionKey="T1JJRU5UREJfSVNfQ09PTA=="
```
You can enable this at startup by passing these settings as JVM arguments:

## Create an encrypted database
### Create via Console
<pre>
$ <code class="lang-sh userinput">java ... -Dstorage.encryptionMethod=aes \
-Dstorage.encryptionKey="T1JJRU5UREJfSVNfQ09PTA=="</code>
</pre>


For more information on security in OrientDB, see the following pages:
- [Database security](Database-Security.md)
- [Server security](Server-Security.md)
- [Secure SSL connections](Using-SSL-with-OrientDB.md)

To create an encypted database, use the -encryption option on [create database command](Console-Command-Create-Database.md). before that set the encryption key by storing it as console's configuration value with name `storage.encryptionKey`. Example:
```
orientdb> config set storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==
orientdb> create database plocal:/tmp/db/encrypted admin admin plocal document -encryption=aes
```

### Create via Java API
To create a new database with AES algorithm, set the encryption algorithm and the encryption key as database properties:

## Creating Encrypted Databases

You can create an encrypted database using either the console or through the Java API. To create an encrypted database, use the `-encryption` option through the [`CREATE DATABASE`](Console-Command-Create-Database.md) command. However, before you do so, you must set the encryption key by defining the `storage.encryptionKey` value through the [`CONFIG`](Console-Command-Config.md) command.

<pre>
orientdb> <code class="lang-sql userinput">CONFIG SET storage.encryptionKe T1JJRU5UREJfSVNfQ09PTA==</code>
orientdb> <code class="lang-sql userinput">CREATE DATABASE plocal:/tmp/db/encrypted-db admin my_admin_password
plocal document -encryption=aes</code>
</pre>

To create an encrypted database through the Java API, define the encryption algorithm and then set the encryption key as database properties:

```java
ODatabaseDocumentTx db = new ODatabaseDocumentTx("plocal:/tmp/db/encrypted");
Expand All @@ -46,43 +52,45 @@ db.setProperty(OGlobalConfiguration.STORAGE_ENCRYPTION_KEY.getKey(), "T1JJRU5URE
db.create();
```

In this way the entire database will be encrypted on disk. The encryption key is never stored inside the database, but must be provided at run-time.
Whether you use the console or the Java API, these commands encrypt the entire database on disk. OrientDB does not store the encryption key within the database. You must provide it at run-time.

## Encrypting Clusters

## Encrypt only certain clusters
In addition to the entire database, you can also only encrypt certain clusters on the database. To do so, set the encryption to the default of `nothing` when you create the database, then configure the encryption per cluster through the [`ALTER CLUSTER`](SQL-Alter-Cluster.md) command.

To encrypt only a few clusters, set the encryption to "nothing" (default) and configure the encryption per cluster through the [`alter cluster`](SQL-Alter-Cluster.md) command:
To encrypt the cluster through the Java API, create the database, then alter the cluster to use encryption:

```java
ODatabaseDocumentTx db = new ODatabaseDocumentTx("plocal:/tmp/db/encrypted");
db.setProperty(OGlobalConfiguration.STORAGE_ENCRYPTION_KEY.getKey(), "T1JJRU5UREJfSVNfQ09PTA==");
db.create();
db.command(new OCommandSQL("alter cluster Salary encryption aes")).execute();
db.command(new OCommandSQL("ALTER CLUSTER Salary encryption aes")).execute();
```

Note that the key is the same for the entire database. You cannot use different keys per cluster. If the encryption/encryption setting is applied on an non empty cluster, then an error is raised.
Bear in mind that the key remains the same for the entire database. You cannot use different keys per cluster. If you attempt to apply encryption or an encryption setting on a cluster that is not empty, it raises an error.

If you're using the console, remember to set the encryption key `storage.encryptionKey` before setting the encryption. Example:
```
orientdb> config set storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==
orientdb> alter cluster Salary encryption aes
```
To accomplish the same through the console, set the encryption key through `storage.encryptionKey` then define the encryption algorithm for the cluster:

## Open an encrypted database
<pre>
orientdb> <code class="lang-sql userinput">CONFIG SET storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==</code>
orientdb> <code class="lang-sql userinput">ALTER CLUSTER Salary encryption aes</code>
</pre>

### Open via Console
## Opening Encrypted Databases

If you're using the console, remember to set the encryption key `storage.encryptionKey` before opening the database. Example:
```
orientdb> config set storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==
orientdb> connect plocal:/tmp/db/encrypted admin admin
```
You can access an encrypted database through either the console or the Java API. To do so through the console, set the encryption key with `storage.encryptionKey` then open the database.

### Open via Java API
Since the encryption setting are stored with the database, it's not necessary to specify the encryption algorithm at open time, but only the encryption key. Example:
<pre>
orientdb> <code class="lang-sql userinput">CONFIG SET storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==</code>
orientdb> <code class="lang-sql userinput">CONNECT plocal:/tmp/db/encrypted-db admin my_admin_password</code>
</pre>

When opening through the Java API, given that the encryption settings are stored with the database, you do not need to define the encryption algorithm when you open the database, just the encryption key.

```java
db.setProperty(OGlobalConfiguration.STORAGE_ENCRYPTION_KEY.getKey(), "T1JJRU5UREJfSVNfQ09PTA==");
db.open("admin", "admin");
db.open("admin", "my_admin_password");
```

If on database open, a null or invalid key is passed, then a `OSecurityException` exception is thrown.
In the event that you pass a null or invalid key when you open the database, OrientDB raises an `OSecurityException` exception.

123 changes: 75 additions & 48 deletions Server-Security.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ For more information on security in Orientdb, see:

## Configuration

To restrict untrusted users from gaining access to the OrientDB server, add a new user or change the password in the server configuration file. Protect the file `config/orientdb-server-config.xml` by disabling write access.
While the default users and passwords are fine while you are setting your system up, it would be inadvisable to leave them in production. To help restrict untrusted users from accessing the OrientDB server, add a new user and change the passwords in the `config/orientdb-server-config.xml` server configuration file.

Additionally, it is advisable that you also disable read access on the configuration file, to prevent users from viewing the passwords. Even if passwords are hashed, there are many techniques available to crack the hash or otherwise guess the real password.
To restrict unauthorized users from giving themselves privileges on the OrientDB server, disable write-access to the configuration file. To help prevent them from viewing passwords, disable read-access as well. Note that even if the passwords are hashed, there are many techniques available to crack the hash or otherwise guess the real password.


| | |
Expand All @@ -36,78 +36,105 @@ Additionally, it is advisable that you also disable read access on the configura

## Managing Users

Starting from OrientDB 2.2, the console is able to manage server users thanks to the following commands:
- [`list server users`](Console-Command-List-Server-Users.md), to display all the users
- [`set server user`](Console-Command-Set-Server-User.md), to create or modify a user
- [`drop server user`](Console-Command-Drop-Server-User.md), to drop a user
Beginning with version 2.2, the OrientDB console provides a series of commands for managing users:

## Server's resources
- [`LIST SERVER USERS`](Console-Command-List-Server-Users.md): Displays all users.
- [`SET SERVER USER`](Console-Command-Set-Server-User.md): Creates or modifies a user.
- [`DROP SERVER USER`](Console-Command-Drop-Server-User.md): Drops a user.


## Server Resources

Each user can declare which resources have access. The wildcard `*` grants access to any resource. By default, the user `root` has all privileges, so it can access all the managed databases.

This section contains all the available server's resources. Each user can declare which resources have access. The wildcard `*` means any resources. The `root`server user, by default, has all the privileges, so it can access all the managed databases.

| Resources | Description |
|-----------|-------------|
|`server.info`|Retrieves the server information and statistics|
|`server.listDatabases`|Lists the available databases on the server|
|`server.info`|Retrieves server information and statistics.|
|`server.listDatabases`|Lists available databases on the server.|
|`database.create`|Creates a new database in the server|
|`database.drop`|Drops a database|
|`database.passthrough`|Starting from 1.0rc7 the server's user can access all the managed databases if it has the resource `database.passthrough` defined. Example:`<user name="replicator" password="repl" resources="database.passthrough" />`|
|`database.passthrough`|Allows access to all managed databases.|

For example,

```xml
<user name="replicator" password="repl" resources="database.passthrough"/>
```



## Securing Connections with SSL

Beginning with version 1.7, you can further improve security on your OrientDB server by securing connections with SSL. For more information on implementing this, see [Using SSL](Using-SSL-with-OrientDB.md).


## Restoring the User admin

In the event that something happens and you drop the class `OUser` or the user `admin`, you can use the following procedure to restore the user to your database.

1. Ensure that the database is in the OrientDB server database directory, `$ORIENTDB_HOME/database/ folder`.

1. Launch the console or studio and log into the database with the user `root`.

## SSL Secure connections
<pre>
$ <code class="lang-sh userinput"> $ORIENTDB_HOME/bin/console.sh</code>

Starting from v1.7, OrientDB supports [secure SSL connections](Using-SSL-with-OrientDB.md).
OrientDB console v.X.X.X (build 0) www.orientdb.com
Type 'HELP' to display all the commands supported.
Installing extensions for GREMLIN language v.X.X.X

## Restore admin user
orientdb> <code class="lang-sql userinput">CONNECT remote:localhost/my_database root rootpassword</code>
</pre>

If the class `OUser` has been dropped or the `admin` user has been deleted, you can follow this procedure to restore your database:
1. Check that the class `OUser` exists:

1. Ensure the database is under the OrientDB Server's databases directory (`$ORIENTDB_HOME/databases/ folder`)
<pre>
orientdb> <code class="lang-sql userinput">SELECT FROM OUser WHERE name = 'admin'</code>
</pre>

1. Open the Console or Studio and login into the database using `root` and the password contained in the file `$ORIENTDB_HOME/config/orientdb-server-config.xml`
- In the event that this command fails because the class `OUser` doesn't exist, create it:

1. Execute this query:
<pre>
orientdb> <code class="lang-sql userinput">CREATE CLASS OUser EXTENDS OIdentity</code>
</pre>

```sql
SELECT FROM OUser WHERE name = 'admin'
```
- In the event that this command fails because the class `OIdentity doesn't exist, create it first:

1. If the class OUser doesn't exist, create it by executing:
<pre>
orinetdb> <code class="lang-sql userinput">CREATE CLASS OIdentity</code>
</pre>

```sql
CREATE CLASS OUser EXTENDS OIdentity
```
Then repeat the above command, creating the class `OUser`

1. If the class `OIdentity` doesn't exist, create it by executing:
1. Check that the class `ORole` exists.

```sql
CREATE CLASS OIdentity
```
And then retry to create the class `OUser` (5)
<pre>
orientdb> <code class="lang-sql userinput">SELECT FROM ORole WHERE name = 'admin'</code>
</pre>

1. Now execute:
- In the event that the class `ORole` doesn't exist, create it:

```sql
SELECT FROM ORole WHERE name = 'admin'
```
<pre>
orientdb> <code class="lang-sql userinput">CREATE CLASS ORole EXTENDS OIdentity</code>
</pre>

1. If the class `ORole` doesn't exist, create it by executing:
1. In the event that the user or role `admin` doesn't exist, run the following commands:

```sql
CREATE CLASS ORole EXTENDS OIdentity
```
- In the event that the role `admin` doesn't exist, create it:

1. If the role `admin` doesn't exist, create it by executing the following command:
<pre>
orientdb> <code class="lang-sql userinput">INSERT INTO ORole SET name = 'admin', mode = 1,
rules = { "database.bypassrestricted": 15 }</code>
</pre>

```sql
INSERT INTO ORole SET name = 'admin', mode = 1, rules = {"database.bypassrestricted":15}
```
- In the event that the user `admin` doesn't exist, create it:

1. If the user `admin` doesn't exist, create it by executing the following command:
<pre>
orientdb> <code class="lang-sql userinput">INSERT INTO OUser SET name = 'admin',
password = 'my-admin_password', status = 'ACTIVE',
rules = ( SELECT FROM ORole WHERE name = 'admin' )</code>
</pre>

```sql
INSERT INTO OUser SET name = 'admin', password = 'admin', status = 'ACTIVE',
roles = (select from ORole where name = 'admin')
```
The user `admin` is now active again on your database.

Now your `admin` user is active again.
Loading

0 comments on commit 48a3b14

Please sign in to comment.