CINXE.COM

<!doctype html> <html lang="en"> <head> <title>Encryption | Ebean</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="shortcut icon" href="/images/favicon.ico"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Source+Sans+Pro|Ubuntu&display=swap"> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous"> <link rel="stylesheet" href="/css/reset3.css"> <link rel="stylesheet" href="/css/site3.css"> <link rel="stylesheet" href="/css/pygments3.css"> </head> <body> <div id="main"> <div id="banner"> <header> <nav id="top"> <h1 id="breadcrumb"> <a class="nav-logo" href="/"><img src="/images/logo-200.png" height="35"></a>  <a href="/docs">Documentation</a> / <a href="/docs/features/">Features</a> / Encryption </h1> <ul> <li><a onclick="toggleTheme();" title="switch dark light theme"></a></li> </ul> </nav> </header> </div> <div class="grid grid-docs"> <aside> <nav class="side"> <ul> <li class="nav0 "> <a href="/docs/getting-started">Getting started</a> </li> <li class="nav0 "> <a href="/docs/intro">Introduction</a> </li> <li class="nav0 active"> <a class="active" href="/docs">Documentation</a> <ul> <li class="nav1 "> <a href="/docs/best-practice">Best practice</a> </li> <li class="nav1 "> <a href="/docs/query">Query</a> </li> <li class="nav1 "> <a href="/docs/persist">Persist</a> </li> <li class="nav1 "> <a href="/docs/transactions">Transactions</a> </li> <li class="nav1 "> <a href="/docs/mapping">Mapping</a> </li> <li class="nav1 "> <a href="/docs/ddl-generation">DDL & Migrations</a> </li> <li class="nav1 "> <a href="/docs/logging">Logging</a> </li> <li class="nav1 "> <a href="/docs/testing">Testing</a> </li> <li class="nav1 "> <a href="/docs/read-replicas">Read Replicas</a> </li> <li class="nav1 "> <a href="/docs/database">Database platforms</a> </li> <li class="nav1 "> <a href="/docs/multi-database">Multiple databases</a> </li> <li class="nav1 "> <a href="/docs/kotlin">Kotlin</a> </li> <li><a href="/docs/tuning">Tuning</a></li> <li class="nav1 active"> <a class="active" href="/docs/features">Features</a> <ul class="nav"> <li > <a href="/docs/features/l2cache">L2 Cache</a> </li> <li > <a href="/docs/features/elasticsearch">Elasticsearch</a> </li> <li > <a href="/docs/features/json-in-db">@DbJson</a> </li> <li > <a href="/docs/features/softdelete">Soft Delete</a> </li> <li class="active"> <a class="active" href="/docs/features/encryption">Encryption</a> <ul class="nav nav-scroll"> <li > <a href="#client-encryption">Client side</a> </li> <li > <a href="#db-encryption">Database side</a> </li> <li > <a href="#types">Supported types</a> </li> <li > <a href="#limitations">Limitations</a> </li> <li > <a href="#configuration">Configuration</a> </li> <li > <a href="#internals">Internals</a> </li> </ul> </li> <li > <a href="/docs/features/who">@WhoModified / @WhoCreated</a> </li> <li > <a href="/docs/features/history">SQL2011 History</a> </li> <li > <a href="/docs/features/changelog">ChangeLog</a> </li> <li > <a href="/docs/features/readauditing">Read auditing</a> </li> <li > <a href="/docs/features/eventlistening">Event Listening</a> </li> </ul> </li> </ul> </li> <li class="nav0 "> <a href="/support">Getting help</a> </li> <li class="nav0 "> <a target="_blank" href="/apidoc/13">API Javadoc</a> </li> <li class="nav0 "> <a href="/videos">Videos</a> </li> <li class="nav0 "> <a href="/docs/upgrading">Upgrading</a> </li> <li class="nav0 "> <a href="/releases">Releases</a> </li> </ul> </nav> </aside> <article> <form action="https://www.google.com/search" method="get" class="inline-form"> <input type="hidden" name="as_sitesearch" value="ebean.io"> <div id="page-search"> <div class="input-group"> <input class="frm" name="q" id="searchinput" type="text" placeholder="Search... (press 's' to focus)" data-placeholder-focus="Search... (use '↑', '↓' and '⏎' to select results)" data-placeholder-blur="Search... (press 's' to focus)" autocomplete="off"> <div class="input-group-btn"> <button class="frm" type="submit"></button> </div> </div> <div id="page-search-results" style="display: none;"> <ul id="search-results-container" class="search-results"><li class=" active"><a href="/docs" title="Docs">Docs Documentation </a></li><li class="">And 101 more...</li></ul> </div> </div> </form> <h2 id="encryption">Encryption</h2> Ebean has support for transparent Encryption/Decryption of specific properties. We make mark the properties we want encrypted with <code>@Encrypted</code> and these properties will be automatically encrypted and decrypted as needed. Encryption/decryption can occur either on the client/application side or by the database. When we use database encryption then we can use these properties in queries as part of the <code>where</code> and <code>order by</code> clause. Effectively the encryption of the property is fully transparent to the application. When we use client/application side encryption/decryption then we should only use the EQ (equal to) operator in the <code>where</code> clause. <h2 id="client-encryption">Client/Application encryption</h2> When using client/application encryption the properties are encrypted/decrypted by a Java function - an implementation of the <code>io.ebean.config.Encryptor</code> interface. The default implementation uses AES 128 bit based implementation and we can also configure Ebean to use another implementation. Properties encrypted with client/application encryption should ONLY be used with EQ (equal to) operator in <code>where</code> clauses - other operators should not be used with client side encrypted properties. <div class="syntax java"><div class="highlight"><pre>package io.ebean.config; /** * Used for Java side encryption of properties when DB encryption is not used. * * By default this is used on non-varchar types such as Blobs. */ public interface Encryptor { /** * Encrypt the data using the key. */ byte[] encrypt(byte[] data, EncryptKey key); /** * Decrypt the data using the key. */ byte[] decrypt(byte[] data, EncryptKey key); /** * Encrypt the formatted string value using a key. */ byte[] encryptString(String formattedValue, EncryptKey key); /** * Decrypt the data returning a formatted string value using a key. */ String decryptString(byte[] data, EncryptKey key); } </pre></div> </div> <h2 id="db-encryption">Database encryption</h2> When using Database side encryption/decryption we use database stored procedures to encrypt and decrypt the properties. For example with Postgres Ebean uses <code>pgp_sym_encrypt()</code> and <code>pgp_sym_decrypt()</code>. <h4>Database encryption functions</h4> The default DB encryption decryption functions used for each platform are: <ul> <li>Postgres, YugabyteDB - pgp_sym_decrypt(), pgp_sym_encrypt()</li> <li>MySql, MariaDB - aes_encrypt(), aes_decrypt()</li> <li>SQL Server - DecryptByPassPhrase(), EncryptByPassPhrase()</li> <li>Oracle - requires dbms_crypto and uses custom functions for encryption and decryption</li> <li>H2 - encrypt() and decrypt() with 'AES' option</li> </ul> <h2 id="types">Supported types</h2> The following are the types supported by database encryption. Any type not supported by database encryption will use client/application encryption. <ul> <li>Enum (if based on VARCHAR)</li> <li>String (VARCHAR, CHAR, CLOB, LONGVARCHAR)</li> <li>Date types - LocalDate, Date, Joda LocalDate</li> <li>Timestamp types - Timestamp, Instant, OffsetDateTime, ZonedDateTime</li> </ul> Important: The following types are currently not supported: <ul> <li>primitive types</li> <li>Timestamps</li> </ul> <h2 id="encryptKeyManager">EncryptKeyManager</h2> Whenever a property is encrypted or decrypted a "Key" must be used. Ebean will internally ask the EncryptKeyManager for a key given the table and column name. We must supply an implementation of the EncryptKeyManager. <div class="syntax java"><div class="highlight"><pre>package io.ebean.config; /** * Determine keys used for encryption and decryption. */ @FunctionalInterface public interface EncryptKeyManager { /** * Initialise the EncryptKeyManager. * * This gives the EncryptKeyManager the opportunity to get keys etc. */ default void initialise() {} /** * Return the key used to encrypt and decrypt a property mapping to the given * table and column. */ EncryptKey getEncryptKey(String tableName, String columnName); } </pre></div> </div> <h2 id="encrypted">@Encrypted</h2> Mark a property to be encrypted with the <code>@Encrypted</code> annotation. By default the property will be <code>dbEncryption = true</code> and we explicitly set that false for client/application side encryption. <div class="syntax java"><div class="highlight"><pre>// use database side encryption @Encrypted String name; // use client side encryption (not db functions) @Encrypted(dbEncryption=false) String description; </pre></div> </div> <h4>Example</h4> <div class="syntax java"><div class="highlight"><pre>// Use @Encrypted annotation to mark the encrypted properties @Entity @Table(name="patient") public class Patient { @Id long id; // database side encryption @Encrypted String name; // client side encryption @Lob @Encrypted(dbEncryption=false) String description; @Encrypted LocalDate dob; ... </pre></div> </div> <h2 id="limitations">Limitations</h2> <ul> <li> Properties using Java client encryption should only use EQ (equal to) operator in WHERE clauses </li> <li> DB Encryption support built in for H2, Postgres, YugabyteDB, MySql, MariaDB, Sql Server and Oracle. </li> <li> We can not use Encryption with positioned (1,2,3...) parameters. We must use named parameters or the criteria api to define queries. </li> </ul> <h3>Examples:</h3> <div class="syntax java"><div class="highlight"><pre>List<Patient> list = new QPatient() .name.eq("Rob") .findList(); </pre></div> </div> Results in the following Postgres SQL: <div class="syntax sql"><div class="highlight"><pre>select t0.id, pgp_sym_decrypt(t0.name,?) from patient t0 where pgp_sym_decrypt(t0.name,?) = ? </pre></div> </div> <h2 id="configuration">Configuration</h2> Specify the EncryptKeyManager implementation in the ebean.properties file like below: <div class="syntax properties"><div class="highlight"><pre>ebean.encryptKeyManager=org.example.BasicEncyptKeyManager </pre></div> </div> Programmatically configure using DatabaseConfig. <div class="syntax java"><div class="highlight"><pre>DatabaseConfig config = DatabaseConfig(); ... EncryptKeyManager keyManager = ...; config.setEncryptKeyManager(keyManager); ... Database database = DatabaseFactory.create(config); </pre></div> </div> An example EncryptKeyManager is: <div class="syntax java"><div class="highlight"><pre>package org.example.encrypt; import io.ebean.config.EncryptKey; import io.ebean.config.EncryptKeyManager; public class BasicEncyptKeyManager implements EncryptKeyManager { public void initialise() { // can load keys or initialise source resources ... } public EncryptKey getEncryptKey(String tableName, String columnName) { // get the key for the given table and column String keyValue = ...; return new BasicEncryptKey(keyValue); } } </pre></div> </div> <h2 id="internals">Internals</h2> Ebean is detecting when an encrypted property is being used. It will call the EncryptKeyManager with the table and column of the property to get the encryption key. This key is then added as a bind variable to the prepared statement. As the key is added as a bind variable into the statement we can not use encryption with 'positioned' parameters because it can effectively change the position of other parameters. We can use named parameters or the criteria api for building queries but, we can't use positioned (1,2,3,4..) parameters. </article> </div> </div> <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script> <script src="/js/site3.js"></script> <script src="/js/search3.js"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-75181644-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-75181644-1'); </script> </body> </html>