Crypteron Documentation

Overview

Crypteron is a data security platform for .NET, Java and Scala backend applications. Crypteron automatically handles encryption, tamper protection, key management and data migration for all types of data including SQL data, NoSQL objects, files, files streams, message queues and more.

This documentation will help you understand how Crypteron works so you get up and running with a secure server-side application in a few minutes instead of a few months. This documentation is under development so check back soon for updates. If you get stuck at all, please do not hesitate to contact us at [email protected] - we're here to help!

Getting Started

Signup

Crypteron has two components - a Crypteron cloud hosted platform that handles management functionality and an agent library that you include in your application's code. A self-hosted version of the platform is available as an option for Enterprise customers with large installations or unique needs. Contact us for details on that.

The first step is Sign Up for the hosted platform and create your free Crypteron account. Once you have verified your email and updated your profile, you'll be asked to add your app to the Crypteron Dashboard. This will allow Crypteron to handle all aspects of key management for your application securely and remotely. We'll dive deeper into key management later.

Choose a name for your app, select a plan and click Create App. If you don't have an application to secure right now, just use the name "Sample App". We'll provide a sample application that you can use.

Create a new app

 

Get App Secret

The Crypteron Dashboard creates an App Secret so you can securely connect it to your backend application. Click on the Show button to view your application's App Secret and then copy it to your clipboard:

App Secret

NOTE: Your App Secret is 100% unrelated to any encryption keys but you should treat it like a password or a secret. If you think that its been compromised then you can reset it by clicking the App Secret refresh button

Plug-in App Secret

You can add your App Secret to your .NET or Java application either by via configuration (i.e. in .XML files) or programmatically . If you don't have an application then you can download or clone a Sample .NET App or a Sample Java App from our GitHub repo.

App Secret via Configuration

C# Configuration

Paste your App Secret into your app.config or web.config file:

<configuration>
  <configSections>
    <section 
        name="crypteronConfig" 
        type="Crypteron.CrypteronConfig, CipherCore, Version=2017, Culture=neutral, PublicKeyToken=e0287981ec67bb47" 
        requirePermission="false" />
  </configSections>

  <crypteronConfig>
    <myCrypteronAccount appSecret="[App Secret Goes Here]" />
  </crypteronConfig>
</configuration>
Java Configuration

App Secret Programmatically

You can also plug-in your App Secret programmatically through code if you want to enable some advanced scenarios.

NOTE: You need to add a Crypteron Agent to your application for this to compile.

C#
// Current Agents (v2016.11.1.2 and after)
CrypteronConfig.Config.MyCrypteronAccount.AppSecret = "[App Secret Goes Here]";


// Older Agents (before v2016.11.1.2)
// put 'using Crypteron.ConfigFile;' at top
var myCrypteronAccount = new MyCrypteronAccount()
{
    AppSecret = "[App Secret Goes Here]"
};
CrypteronConfig.Config.MyCrypteronAccount = myCrypteronAccount;
Java

Show me some code!

Ok, time to get into the code. Crypteron provides several .NET and Java agent libraries in NuGet and Maven for securing different types of data that we outline in the following sections. All of these agent libraries use the same security model defined in the Crypteron Dashboard. This lets you re-use security partitions, access control rules and key rotations across all types of data. Not only that, as long at they have the same AppSecret, data encrypted by any one agent can be decrypted by any other agent without any compatibility issues. For example: Data encrypted by the CipherDB C# Entity Framework agent can be decrypted by the CipherObject Java agent.

Interested in skipping ahead?

  • For securing data stored in a database with an ORM such as Entity Framework, NHibernate, Hibernate or JPA,  jump to CipherDB.
  • For securing data in plain old C# or Java objects, including support for NoSQL, message queues, and JSON, jump to CipherObject.
  • For securing data in files or file streams, jump to CipherStor.

Database With ORM - CipherDB

Crypteron's CipherDB agent library secures data that is persisted using Microsoft Entity Framework, NHibernate, Hibernate, or JPA. If your database is compatible with any of these ORM solutions, we highly recommend you utilize one in your projects.  An ORM, or object-relational mapper, enables developers to work with relational data using domain-specific objects. It eliminates the need for most of the data-access code that developers usually need to write and it integrates with Crypteron effortlessly.

With CipherDB, you simply decorate your entity classes to specify which class properties contain sensitive data. Add a [Secure] attribute above each property in C# or a @Secure annotation in Java / Scala.

C# Example

public class Patient
{
    public int Id {get; set;}
    
    [Secure]
    public string FullName {get; set;}
    
    [Secure]
    public string SocialSecurityNumber {get; set;}
}

Java Example

public class Patient
{
    private int Id;

    @Secure
    private String fullName;

    @Secure
    private String socialSecurityNumber;
}

Whenever one of these objects is persisted to the database CipherDB will automatically encrypt and sign the properties you tagged as secure with AES-GCM. Conversely, CipherDB will decrypt and verify those properties whenever the object is loaded back from memory.

If you can't add annotations or attributes to your class properties because your classes were automatically generated using a database-first workflow, don't worry! Simply prefix your property names with the string Secure_ and CipherDB will take care of the rest. For example, if your Patient class was automatically generated from the schema in a Patients table, rename the FullName column to Secure_FullName. Simple!

All CipherDB .NET agent libraries are in NuGet. All CipherDB Java agent libraries are in Maven.  Download and install the version that matches your environment:

Your app is now connected to the Crypteron platform. C# developers have one extra step described in the following section but Java / Scala developers are now done.

CipherDB will sign and encrypt each sensitive class property with AES-GCM encryption before persistence and decrypt and verify the data on the way back. CipherDB even performs row binding which detects if a malicious user moves data, such as a salary field, from one row to another. You can develop the rest of your application as you normally would and rest easy knowing that all sensitive data is signed and encrypted.

Java developers, be sure to check out the sample applications  on GitHub, and read the Java API docs for more details. Also, read through the CipherDB .NET Developer Guide since a lot of the advanced features described there, such as multiple security partitions, key rotations, data migration, access control rules and more, apply to the Java edition as well. We'll be updating the CipherDB Java Developer Guide soon to include these additional specifications. And as always, contact us if you need help.

.NET developers, keep reading!

Creating a CipherDB Session in C# - Entity Framework

C# developers, you have one tiny extra step in order for CipherDB to integrate with Entity Framework. Add Crypteron.CipherDB.Session.Create(this); to your app's DbContext constructor.

Simplest to inherit and override, so lets say you have a regular MyEntitiesContext class that inherits from the DbContext class (standard Entity Framework so far). You now simply create a new class that inherits from the MyEntitiesContext class and includes the line above in its constructor.

In action:

public class SecureEntitiesContext : MyEntitiesContext
{
    public SecureEntitiesContext()
    {
        Crypteron.CipherDB.Session.Create(this);
    }
}

Then just use the SecureEntitiesContext class instead of MyEntitiesContext. Straight forward enough!

// Before
using (var db = new MyEntitiesContext())
{
    // do work
}
// After
using (var db = new SecureEntitiesContext())
{
    // do work
}

For more details including advanced features such as multiple security partitions, key rotations, data migration, access control rules and more, check out the CipherDB .NET Developer's Guide. Also, download the sample apps and browse through the .NET API Documentation. And as always, contact us if you need help.

Data Objects - CipherObject

Crypteron's CipherObject agent library secures data in plain old C# or Java objects. This low level functionality gives you extreme flexibility since these secure objects are just like any other C# or Java object except that their sensitive data properties are undecipherable. This means you can take an object secured with CipherObject and serialize it as JSON, put it into a message queue, store it in a NoSQL database or anything else you can think of. And remember, all data secured by any Crypteron agent (e.g. C# CipherDB) is compatible with all other Crypteron agents (e.g. Java CipherObject), so you can mix and match for your ideal solution.

The syntax for specifying which class properties contain sensitive data is the same as CipherDB. Simply tag these properties with a [Secure] attribute in C# or a @Secure annotation in Java. When you're ready to securely seal the object, such as before serialization or persistence, use the seal method. Conversely, use the unseal method to unseal a secured object.

C# Example

// Attributes on data class
public class Patient
{
    public int Id {get; set;}
    
    [Secure]
    public string FullName {get; set;}
    
    [Secure]
    public string SocialSecurityNumber {get; set;}
}

// myPatient is of type Patient
// Encrypt and sign the object before sending
myPatient.seal();

// Decrypt and verify the object after fetching
myPatient.unseal();

Java Example

// Annotations on data class
public class Patient
{
    private int Id

    @Secure
    private String fullName;

    @Secure
    private String socialSecurityNumber;
}

// myPatient is of type Patient
// Secure the object before sending
CipherObject.seal(myPatient);

// Decrypt and verify the object after fetching
CipherObject.unseal(myPatient);

After calling seal on an object, the properties tagged as sensitive will be signed and encrypted with AES-GCM. This adds privacy and tamper protection. Calling unseal on an object will decrypt the sensitive properties and verify that they weren't tampered with.

The CipherObject .NET agent library is in NuGet. The CipherObject Java agent library is in Maven.  Download and install the version that matches your environment:

NOTE: The CipherDB .NET Developers Guide contains more details on advanced features and configuration options that apply to all agent libraries, including Java.

Files and Streams - CipherStor

Crypteron's CipherStor agent library secures files and streams with AES-GCM encryption and tamper protection. This means you can store your sensitive files and streams on any network, cloud or storage provider that supports them, including Azure Blob Storage and Amazon S3, without any additional engineering.

Our straightforward API will encrypt and sign as well as decrypt and verify any file or stream with additional support for compression and native Azure Blob Storage integration. And like all the other Crypteron agent libraries, all aspects of key management happen transparently behind the scenes.

C# Example

var cipherStor = new CipherStorExt();

// Files
cipherStor.EncryptLocalFile(clearInFilename, encryptedOutFilename, compressFlag);
cipherStor.DecryptLocalFile(encryptedInFilename, clearOutFilename);

// Streams
cipherStor.EncryptStream(clearInputStream, encryptedOutputStream, compressFlag);
cipherStor.DecryptStream(encryptedOutputStream, clearInputStream);

Java Example

CipherStor cipherStor = new CipherStor();

// Files
cipherStor.encryptLocalFile(clearFile, encryptedFile, compressFlag);
cipherStor.decryptLocalFile(encryptedFile, clearFile);

// Streams
cipherStor.encryptStream(clearInputStream, encryptedOutputStream, compressFlag);
cipherStor.decryptStream(encryptedStream, clearOutputStream);

Key Management

Even the strongest encryption is weak unless coupled with proper key management. You could secure your home with the best lock in the world but if you leave the key under the mat, make too many copies or don't change your locks often someone is going to break in eventually. At the same time if you have to drive to the bank to fetch your keys from a vault every time you need to get into your house (and drive back every time you leave) you won't be able to get anything done.

Crypteron's key management system achieves a balance between these two extremes and, most importantly, does so completely automatically and transparently. Once you install any of our agent libraries - CipherDB, CipherObject or CipherStor - you're done; there are literally no further steps for key management. Our patent pending, API-less key management means there is no need to invoke any key management APIs. It just works.

In case you're curious, we've included some technical details below on what goes on behind the scenes but keep in mind that this is all automatic. For advanced features such as multiple security partitions, access control rules, key rotations / versioning, and data migration, please read the CipherDB .NET Developers Guide.

Key Storage

  • When you create an app in the Crypteron Dashboard a default Data Encryption Key (DEK) is created for your application.
  • The Data Encryption Key (DEK) is encrypted and signed using AES-256-GCM with a Key Encryption Key (KEK) and stored remotely on Crypteron's hosted platform. Enterprise customers have a self-hosted option to store these keys on-site.
    • The Key Encryption Key (KEK) is encrypted and signed using elliptic curve cryptography (secp521r1) with a Master Encryption Key (MEK) and a Master Signing Key (MSK).
  • The Master Encryption Key (MEK) and Master Signing Key (MSK) are secured in a hardened service certificate store.

NOTE: CipherStor goes one step further and generates a Media Encryption Key to encrypt each file. This key is encrypted by the Data Encryption Key (DEK) as described above.

key-management-heirarchy

Key Distribution and Caching

The following steps take place behind the scenes when your app needs to encrypt or decrypt a piece of data using CipherDB, CipherObject or CipherStor:

  • The Crypteron agent checks if there was a recent heartbeat. The heartbeat verifies that the App Secret is active and hasn't been revoked by you. It also verifies that your app has a valid license.
  • The agent determines which encryption keys are required. Paid plans include support for multiple security partitions as well as multiple key versions.
  • The agent checks if the required keys are already available in its local, short-term, in-memory cache.
  • If the encryption keys are not cached, the agent checks if there is already a pending network request to the Crypteron platform for the same keys on another application thread.
  • If no other network request for the same encryption keys is pending, the agent creates one over a secure Key Management REST API (security details below). The agent automatically handles timeouts and retries due to Internet latency or re-routing.
  • Once the requested keys are returned, the agent stores them in a local, short-term, in-memory cache. All keys are automatically purged after a few minutes.

Key Management API Security

All key requests between the Crypteron agent and the Crypteron platform are made over a secure REST-based API with multiple layers of encryption:

  • The API traffic has multiple layers of encryption, starting with SSL (specifically TLS) as the outer layer
  • Within the encrypted SSL/TLS pipe, HTTP request headers and body are all signed and verified via an HMAC-SHA256 signature in the standard HTTP Authorization header.
    • The App Secret itself is never sent across the network, even in an encrypted form. It is only used as the key to the HMAC-SHA256 signatures
    • The server also confirms that you haven't previously revoked the App Secret or disabled or paused your App
  • Replay attacks are mitigated by validating a 128-bit nonce included in the Authorization header as well as a UTC time stamp in the HTTP Date Header
    • We allow a 15-minute tolerance to account for drifts in system clocks
  • The HTTP request body consists of the key request object, binary serialized using Protocol Buffers for CPU and space efficiency
  • The HTTP key response from the server is binary serialized, encrypted and signed using AES-GCM and then transmitted over SSL/TLS
    • This second layer of cryptographic security protects your traffic from known or unknown weaknesses in SSL/TLS (e.g. the infamous HeartBleed)
  • The Crypteron Dashboard allows you to easily reset your App Secret and rotate your encryption keys with a click of a button

REMINDER: All of the technical details in this section are to assure you of the robust security built into Crypteron's key management platform. Everything described above happens automatically and transparently.

 

Aren't you glad you don't have to code this yourself??

Training Videos

A video is worth a thousand words. This 3-minute video will show you the basics, including how to shutdown key management with a single click in the event of a data breach:

Java video tutorial

Sample Applications

Most developers learn best by looking at sample code so we put together a set of sample console applications for C# and Java. Both repos contain samples for all flavors of CipherDB, CipherObject and CipherStor. You can download, compile and run them on your own machine to see first hand how Crypteron works. Just be sure to Sign Up for a free Crypteron account first and copy your App Secret into the project first.

Advanced Features and Configuration

Security Partitions

Segmentation is a key component of robust data security. Crypteron's management dashboard allows you to easily silo your sensitive data into different security partitions each with its own set of encryption keys, access control rules and audit log. You might, for example, create one security partition for billing data (PCI compliance) and another for medical data (HIPAA compliance).

To create or edit a security partition, log into the Crypteron Dashboard and choose your App.

To use them from your code, please see the example below.

// Everything in default security partition
using (var db = new SecureEntitiesContext())
{
    // do work
}
// Data in 'billing' security partition
using (var db = new SecureEntitiesContext("billing"))
{
    // do work
}

Access Control Rules

An access control rule limits how different user roles access data within a security partition. For example, you might create an access control rule that allows supervisors to both encrypt and decrypt data within the billing security partition and create another that only allows users in nursing to decrypt data within the medical security partition.

To create or edit an access control rule, log into the Crypteron Dashboard, select your App and then select the Security Partition within which you want to create an access control rule.

To use them from your code, please see the example below.

// Everything in default security partition
// with no concept of role-based access controls
using (var db = new SecureEntitiesContext())
{
    // do work
}
// Data in 'billing' security partition with fine-grained
// role-based access controls as 'supervisor' role
using (var db = new SecureEntitiesContext("billing", "supervisor"))
{
    // do work
}

Searchable Encryption

One of the fundamental objectives of strong encryption is to eradicate any and every pattern from your plain text as it’s encrypted to cipher text. However, when performing a search one is specifically looking for patterns to search efficiently. So intuitively, there is a natural tension between strong encryption and free-for-all-searching.

Crypteron builds an in-place, cryptographically secure, distributed search index to enable searches securely. Your data is protected with fully randomized, strong encryption. We describe additional nuances of searchable encryption in this blog post.

The syntax for specifying which class properties containing sensitive data should have searchable encryption enabled is built on the existing approach for CipherDB and CipherObject. Simply add a Mode.Searchable parameter to your [Secure] attribute in C# or a Mode.SEARCHABLE value to your @Secure annotation in Java. If you can't add annotations or attributes to your class properties because your classes were automatically generated using a database-first workflow, don't worry! Simply prefix your property names with the string SecureSearch_ and we will take care of the rest.

The example below demonstrates adding searchability to our Patient class allowing us to search for Patients given their Social Security Number.

C# Example

// Attributes on data class
public class Patient
{
    public int Id {get; set;}
    
    [Secure]
    public string FullName {get; set;}
    
    [Secure(Mode.Searchable)]
    public string SocialSecurityNumber {get; set;}
}

// To search for SSN 123-456-7890, 
// generate a search prefix
var searchPrefix = 
    SecureSearch.GetPrefix("123-456-7890");

// Use the search prefix in a query
var foundPatient = secDb.Patients.Where(p =>
    p.SocialSecurityNumber.StartsWith(searchPrefix)
)

Java Example

// Annotations on data class
public class Patient
{
    private int Id

    @Secure
    private String fullName;

    @Secure(Mode.SEARCHABLE)
    private String socialSecurityNumber;
}

// To search for SSN 123-456-7890,
// generate a search prefix
final String searchPrefix = 
    SecureSearch.getPrefix("123-456-7890");

// Use the search prefix in a query:
final TypedQuery query =
    entityManager.createQuery("SELECT p FROM Patient p where p.socialSecurityNumber LIKE :searchPrefix", Patient.class);
query.setParameter("searchPrefix", searchPrefix + "%");
final Patient foundPatient = query.getSingleResult();

Additional Advanced Features

The purpose of this documentation is to get you up and running as quickly as possible with all of the Crypteron agent libraries. There are additional advanced features and configuration options that weren't covered including:

  • Key rotations
  • Data migration after a key rotation
  • One-click data breach response
  • Searchable encryption
  • Name mapping
  • Stored procedures
  • Performance

For a more comprehensive overview of these features, please view the following resources:

  1. CipherDB .NET Developers Guide - this guide goes well beyond CipherDB and .NET to cover options that apply to all agent libraries, including Java
  2. Searchable Encryption Blog Post
  3. CipherDB Performance Benchmarks
  4. CipherStor Performance Benchmarks
  5. Sample Apps - many advanced features are covered in the samples above
  6. Contact Us - we're pretty fanatical about support and we love helping our customers. If there's something complicated that you are trying to accomplish, don't hesitate to ask for help!

API Reference

Our C# / .NET and Java API references for all of our agent libraries are below.

NOTE: the Crypteron Dashboard is API driven as well with a REST endpoint for all key management functionality including creating new Apps, Security Partitions and Access Control Rules as well as pausing key management in the event of a data breach, executing a key rotation or refreshing the App Secret. You can read the Management REST API documentation here.

Recent blog posts

Encryption, Entity Framework and Projections

We just got another email asking how Crypteron’s CipherDB encryption works with Entity Framework’s projections. So I decided it’s time to write a blog post about it. For starters, Crypteron works very well with Entity Framework. And for the most past Entity Framework works with – well – Entities. But there are some cases where […]

PCI DSS and key rotations simplified

PCI compliance requires data encryption keys to be changed frequently. Here is how you can do it easily.

Your data-center is not secure and what you can do about it

There is no secure perimeter anymore. Neither in your corporate network nor in your data center. Fight a winning battle armed with self-protecting data rather than a losing one trying to protecting the infrastructure.

Introducing the Crypteron Startup Innovators Program

Qualifying startups get up to 50% off all plans. Tell us how you’re changing the world and the our Startup Innovators Program will support your journey.

6 encryption mistakes that lead to data breaches

If encryption is so unbreakable, why do businesses and governments keep getting hacked? Six common encryption mistakes that lead to data breaches.

Announcing the new Crypteron Community Edition

Starting today you can now sign up for the Crypteron Community Edition for free with no performance limitations.

Data breach response – One click to save your business

Get breathing room – when you need it the most. Respond to a data breach with a single click.

Why We Need Proper Data-At-Rest Encryption: 191M U.S. Voters’ Data Exposed

Adding security at the application level is a large step forward in protecting data from the constant threat of data breaches

How to encrypt large files

CipherStor is blazingly fast! Here we show how to use it within your data-flow pipeline to maintain high performance when encrypting large files.

Crypteron CipherStor Performance Benchmarks

Blazing fast performance by Crypteron CipherStor that hits several gigabytes/sec enabling security even in high bandwidth scenarios