diff --git a/Database-Encryption.md b/Database-Encryption.md index 0ede8f6a..c5cd85fc 100644 --- a/Database-Encryption.md +++ b/Database-Encryption.md @@ -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 +
+$ java ... -Dstorage.encryptionMethod=aes \
+      -Dstorage.encryptionKey="T1JJRU5UREJfSVNfQ09PTA=="
+
+ + +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. + +
+orientdb> CONFIG SET storage.encryptionKe T1JJRU5UREJfSVNfQ09PTA==
+orientdb> CREATE DATABASE plocal:/tmp/db/encrypted-db admin my_admin_password 
+          plocal document -encryption=aes
+
+ +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"); @@ -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 +
+orientdb> CONFIG SET storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==
+orientdb> ALTER CLUSTER Salary encryption aes
+
-### 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: +
+orientdb> CONFIG SET storage.encryptionKey T1JJRU5UREJfSVNfQ09PTA==
+orientdb> CONNECT plocal:/tmp/db/encrypted-db admin my_admin_password
+
+ +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. + diff --git a/Server-Security.md b/Server-Security.md index 1190f6cf..3613c105 100644 --- a/Server-Security.md +++ b/Server-Security.md @@ -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. | | | @@ -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:``| +|`database.passthrough`|Allows access to all managed databases.| + +For example, + +```xml + +``` + + + +## 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 + 
+   $  $ORIENTDB_HOME/bin/console.sh
 
-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> CONNECT remote:localhost/my_database root rootpassword
+
-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`) + 
+   orientdb> SELECT FROM OUser WHERE name = 'admin'
+
-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: + 
+     orientdb> CREATE CLASS OUser EXTENDS OIdentity
+
- ```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: + 
+     orinetdb> CREATE CLASS OIdentity
+
- ```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) + 
+   orientdb> SELECT FROM ORole WHERE name = 'admin'
+
-1. Now execute: + - In the event that the class `ORole` doesn't exist, create it: - ```sql - SELECT FROM ORole WHERE name = 'admin' - ``` + 
+     orientdb> CREATE CLASS ORole EXTENDS OIdentity
+
-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: + 
+     orientdb> INSERT INTO ORole SET name = 'admin', mode = 1, 
+               rules = { "database.bypassrestricted": 15 }
+
- ```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: + 
+     orientdb> INSERT INTO OUser SET name = 'admin', 
+               password = 'my-admin_password', status = 'ACTIVE', 
+               rules = ( SELECT FROM ORole WHERE name = 'admin' )
+
- ```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. diff --git a/Using-SSL-with-OrientDB.md b/Using-SSL-with-OrientDB.md index 23875bc5..d6592eb8 100644 --- a/Using-SSL-with-OrientDB.md +++ b/Using-SSL-with-OrientDB.md @@ -1,64 +1,64 @@ # SSL -See also: +Beginning with version 1.7, OrientDB provides support for securing its HTTP and BINARY protocols through SSL. For distributed SSL, see the HazelCast documentation. + +For more information on securing OrientDB, see the following pages: - [Database security](Database-Security.md) - [Server security](Server-Security.md) - [Database Encryption](Database-Encryption.md) -Starting from v1.7, OrientDB provides the ability to secure its HTTP and BINARY protocols using SSL (for Distributed SSL see the HazelCast documentation). - ## Setting up the Key and Trust Stores -OrientDB uses the JAVA Keytool to setup and manage certificates. This tutorial shows how to create key and trust stores that reference a self-signed cert. Use of CA-signed certs is outside the scope of this document. For more details on using the Java Keytool please visit . +In order to set up and manage certificates, OrientDB uses the Java Keytool. Using certificates signed by a Certificate Authority (CA) is beyond the scope of this tutorial. For more information on using the Java Keytool, see the [Documentation](http://docs.oracle.com/javase/7/docs/technotes/tools/index.html#security). +To create key and trust stores that reference a self-signed certificate, use the following guide: 1. Using Keytool, create a certificate for the server: - ``` - # keytool -genkey -alias server -keystore orientdb.ks \ - -keyalg RSA -keysize 2048 -validity 3650 - ``` + 
+   # keytool -genkey -alias server -keystore orientdb.ks \
+        -keyalg RSA -keysize 2048 -validity 3650
+
-1. Export the server's certificate so it can be shared with clients: +1. Export the server certificate to share it with client: - ``` - # keytool -export -alias server -keystore orientdb.ks \ - -file orientdb.cert - ``` + 
+   # keytool -export -alias server -keystore orientdb.ks \
+	      -file orientdb.cert
+
1. Create a certificate/keystore for the console/clients: - ``` - # keytool -genkey -alias console -keystore orientdb-console.ks \ - -keyalg RSA -keysize 2048 -validity 3650 - ``` + 
+   # keytool -genkey -alias console -keystore orientdb-console.ks \
+	      -keyalg RSA -keysize 2048 -validity 3650
+
-1. Create a trust-store for the client, and import the server's certificate. This establishes that the client "trusts" the server: +1. Create a trust-store for the client, then import the server certificate. - ``` - # keytool -import -alias server -keystore orientdb-console.ts \ - -file orientdb.cert - ``` + 
+   # keytool -import -alias server -keystore orientdb-console.ts \
+	      -file orientdb.cert
+
+ This establishes that the client trusts the server. ->**NOTE**: You will need to repeat steps 3 and 4 for each remote client VM you wish to connect to the server. Remember to change the alias, keystore and trust-store filenames accordingly. +You now have a self-signed certificate to use with OrientDB. Bear in mind that for each remote client JVM you want to connect to the server, you need to repeat steps three and four. Remember to change the alias, keystore and trust-store filenames accordingly. -## Configuring the Server +## Configuring OrientDB for SSL -The OrientDB server config (`$ORIENTDB_HOME/config/orientdb-server-config.xml`) does not enable SSL by default. To enable SSL on a protocol -listener you simply change the `socket` attribute of the `` from `default` to one of your configured `` definitions. -There are two default definitions named `ssl` and `https`. These should be sufficient for most uses cases, however more can be defined if you -want to secure different listeners with there own certificates or want custom socket factory implementations. When using the `ssl` implementation -keep in mind that the default port for OrientDB SSL is `2434` and that your port-range should be changed to `2434-2440`. +### Server Configuration -By default, the OrientDB Server looks for its keys and trust stores in `$ORIENTDB_HOME/config/cert`. This is configured using the `` parameters. Make sure that all of the key and trust stores created in the previous setup are in the correct directory and that the passwords used are also correct. +The server configuration file, `$ORIENTDB_HOME/config/orientdb-server-config.xml`, does not use SSL by default. To enable SSL on a protocol listener, you must change the `socket` attribute to the `` value from `default` to one of your configured `` definitions. -Note that paths are relative to `$ORIENTDB_HOME`. Absolute paths are supported. +There are two default definitions available: `ssl` and `https`. For most use cases this is sufficient, however you can define more if you want to secure different listeners with their own certificates or would like to use a custom factory implementations. When using the `ssl` implementation, bear in mind that the default port for OrientDB SSL is `2434`. You need to change your port range to `2434-2440`. -Example Configuration +By default, the OrientDB server looks for its keys and trust-stores in `$ORIENTDB_HOME/config/cert`. You can configure it using the `` parameters. Be sure that all the key and trust-stores created in the previous setup are in the correct directory and that the passwords used are correct. + +>**NOTE**: Paths are relative to `$ORIENTDB_HOME`. OrientDB also supports absolute paths. ```xml @@ -81,44 +81,45 @@ Example Configuration ``` -## Configuring the Console +### Console Configuration -To enable SSL for remote connections using the console, a few changes to the console script are required. +For remote connections using the console, you need to make a few changes to to `console.sh`, enable SSL: -1. Confirm that your `KEYSTORE`, `TRUSTSTORE` and repective `PASSWORD` variables are set correctly. -1. In the `SSL_OPTS` definition set the `client.ssl.enabled` system property to `true` +1. Confirm that your `KEYSTORE`, `TRUSTSTORE` and respective `PASSWORD` variables are correctly set. +1. In the `SSL_OPTS` definition, set `client.ssl.enabled` system property to `true`. -## Configuring Client +### Client Configuration -Configuring remote clients can be done using standard Java system property patterns. +To configure remote clients, use the standard Java system property patterns: -Properties: +- `client.ssl.enabled`: Use this to enable/disable SSL. The property accepts `true` or `false`. You only need to define this when using remote binary client connections. +- `javax.net.ssl.keyStore`: Define the path to the keystore. +- `javax.net.ssl.keyStorePassword`: Defines the password to the keystore. +- `javax.net.ssl.trustStore`: Defines the path to the trust-store. +- `javax.net.ssl.trustStorePassword`: Defines the password to the trust-store. -- `client.ssl.enabled`: Used to enable/disable SSL. Accepts `true` or `false`. Only needed when using remote binary client connections. -- `javax.net.ssl.keyStore`: Path to key store -- `javax.net.ssl.keyStorePassword`: Key store password -- `javax.net.ssl.trustStore`: Path to trust store -- `javax.net.ssl.trustStorePassword`: Trust store password +Use the third and fourth steps from [Setting up the Key and Trust Stores](Using-SSL-with-OrientDB.md#setting-up-the-key-and-trust-stores) section above to create the client certificates and server trust. The paths to the stores are client specific, but do not need to be the same as the server. -Use steps 3 and 4 from the "Setting up the Key and Trust Stores" section to create client certificates and trust of the server. Paths to the -stores will be client specific and do not need to be the same as the server. +Note, if you would like to use key and/ore trust-stores other than that of the default JVN, you need to define the following variables as well: -If you would like to use key and/or truststores other that the default JVM they should use instead: +- `client.ssl.keyStore`: Defines the path to the keystore. +- `client.ssl.keyStorePass`: Defines the keystore password. +- `client.ssl.trustStore`: Defines the path to the trust-store. +- `client.ssl.trustStorePass`: Defines the password to the trust-store. -- `client.ssl.keyStore`: Path to key store -- `client.ssl.keyStorePass`: Key store password -- `client.ssl.trustStore`: Path to trust store -- `client.ssl.trustStorePass`: Trust store password +Consider the following example, configuring SSL from the command-line through Java: -Example Java Command Line: +
+$ java -Dclient.ssl.enabled=false \
+      -Djavax.net.ssl.keyStore= \
+      -Djavax.net.ssl.keyStorePassword= \  
+      -Djavax.net.ssl.trustStore= \
+      -Djavax.net.ssl.trustStorePassword=
+
-``` -$ java -Dclient.ssl.enabled=false -Djavax.net.ssl.keyStore= -Djavax.net.ssl.keyStorePassword= \ - -Djavax.net.ssl.trustStore= -Djavax.net.ssl.trustStorePassword= -``` +As an alternative, you can define these variables through the Java API: -Example Java Implementation: ```java System.setProperty("client.ssl.enabled", <"true"|"false">); # This will only be needed for remote binary clients @@ -128,39 +129,37 @@ System.setProperty("javax.net.ssl.trustStore", ); System.setProperty("javax.net.ssl.trustStorePassword", ); ``` -If you want to verify/authenticate client certificates, you need to take a few extra steps on the server: - -1. Export the client's certificate so it can be shared with server: - - ``` - # keytool -export -alias \ - -keystore -file client_cert - ``` +To verify or authenticate client certificates, you need to take a few additional steps on the server: - Example using console: +1. Export the client certificate, so that you can share it with the server: - ``` - # keytool -export -alias console -keystore orientdb-console.ks \ - -file orientdb-console.cert - ``` + 
+   # keytool -export -alias  \
+         -keystore  -file client_cert
+
-2. Create a truststore for the server if one does not exist, and import the client's certificate. This establishes that the server "trusts" the client: + Alternatively, you can do this through the console: - ``` - # keytool -import -alias -keystore orientdb.ts \ - -file client_cert - ``` + 
+   # keytool -export -alias console -keystore orientdb-console.ks \
+         -file orientdb-console.cert
+
- Example using console: +1. If you do not have a trust-store for the server, create one and import the client certificate. This establishes that the server trusts the client: - ``` - # keytool -import -alias console -keystore orientdb.ts -file orientdb-console.cert - ``` + 
+   # keytool -import -alias  -keystore orientdb.ts \
+         -file client_cert
+
+ Alternatively, you can manage the same through the console: -In the server config make sure that client authentication is enabled for the and that the trust-store path and password are correct: + 
+   # keytool -import -alias console -keystore orientdb.ts \ 
+         -file orientdb-console.cert
+
-Example +In the server configuration file, ensure that you have client authentication enabled for the `` and that the trust-store path and password are correct: ```xml @@ -175,4 +174,6 @@ Example + ... + ```