Skip to content
Application Encryption SDK
Branch: master
Clone or download
jpaskhay and sushantmimani minor cleanup in SM READMEs (#43)
- remove docker build info until we add it back with external cicd effort
- clarified current state of implementation info
- leaving bulk of the info in them as is for now as upcoming golang SM implementation may change how we convey SM info
Latest commit d5ad6c1 Jul 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Put the issue templates in the right spot Jun 26, 2019
docs added a couple implementation details to Internals (#40) Jul 11, 2019
languages minor cleanup in SM READMEs (#43) Jul 12, 2019
samples Update README.md (#33) Jul 8, 2019
scripts initial code commit Jun 26, 2019
tests/java/test-app READMEs were missing from initial commit Jul 1, 2019
.editorconfig Add a few more rules to the EditorConfig, including language-specific Jun 27, 2019
.gitignore initial commit of master from internal repo Jun 19, 2019
CODE_OF_CONDUCT.md initial commit of master from internal repo Jun 19, 2019
CONTRIBUTING.md Contributors list and link fix (#27) Jul 9, 2019
CONTRIBUTORS.md Contributors list and link fix (#27) Jul 9, 2019
LICENSE initial commit of master from internal repo Jun 19, 2019
README.md fix license badge link (#41) Jul 10, 2019
SECURITY.md

README.md

Asherah

Join Slack License

Asherah is an application-layer encryption SDK, currently in incubator status, that provides advanced encryption features and defense in depth against compromise.

NOTICE: This is an alpha product

Internally, we are preparing this for production workloads and have a high degree of confidence in it, but we want to be clear that this should still be considered an incubator project. We have not yet had any formal external security audits of this product. We do not yet consider Asherah as validated for production use. As we receive more feedback, both internally and externally, APIs and features may be subject to change. Once we have cleared external audits and hit feature and testing milestones, we will release languages and versions into production status.

Table of Contents

Introduction

The Asherah SDK provides advanced encryption techniques exposed via simple APIs for application-layer encryption. Its goal is to provide an easy-to-use library which abstracts away internal complexity and provides rapid, frequent key rotation with enterprise scale in mind.

Multiple layers of keys are used in conjunction with a technique known as "envelope encryption". Envelope encryption is a practice where a key used to encrypt data is itself encrypted by a higher-order key and stored alongside the encrypted data, hence forming an envelope structure. The master key used at the root of the key hierarchy is typically managed by a Hardware Security Module (HSM) or Key Management Service (KMS).

The SDK generates cryptographically strong intermediate keys in the hierarchical model and manages their storage via a pluggable backing datastore. The integration with a HSM or KMS provider for the root (master) key in the hierarchy is implemented using a similar pluggable model. This allows for supporting a wide variety of datastores and cloud providers for different architectures.

The SDK provides implementations in multiple languages using native interoperability mechanisms to securely manage and cache internally-generated keys in off-heap protected memory. The combination of secure memory management and the hierarchical key model's partitioning help minimize attack exposure in the event of compromise. Using the protected memory cache has an added benefit of reducing interactions with external resources to improve latency and minimize incurred costs.

Getting Started

The basic use of the SDK proceeds in 3 steps:

Step 1: Create a session factory

A session factory is required to generate encryption/decryption sessions. For simplicity, the session factory uses the builder pattern, specifically a step builder. This ensures all required properties are set before a factory is built.

To obtain an instance of the builder, use the static factory method newBuilder. Once you have a builder, you can use the withXXX setter methods to configure the session factory properties.

Below is an example of a session factory that uses in-memory persistence and static key management.

AppEncryptionSessionFactory appEncryptionSessionFactory = AppEncryptionSessionFactory
    .newBuilder("myservice", "sample_code")
    .withMemoryPersistence() // in-memory metastore persistence only
    .withNeverExpiredCryptoPolicy()
    .withStaticKeyManagementService("secretmasterkey!") // hard-coded/static master key
    .build());

Step 2: Create a session

Use the factory to create a session.

AppEncryption<byte[], byte[]> appEncryptionBytes = appEncryptionSessionFactory.getAppEncryptionBytes("shopper123");

The scope of a session is limited to a partition id, i.e. every partition id should have its own session.

Step 3: Use the session to accomplish the cryptographic task

The SDK supports 2 usage patterns:

Encrypt / Decrypt

This usage style is similar to common encryption utilities where payloads are simply encrypted and decrypted, and it is completely up to the calling application for storage responsibility.

String originalPayloadString = "mysupersecretpayload";

// encrypt the payload
byte[] dataRowRecordBytes = appEncryptionBytes.encrypt(originalPayloadString.getBytes(StandardCharsets.UTF_8));

// decrypt the payload
String decryptedPayloadString = new String(appEncryptionBytes.decrypt(newBytes), StandardCharsets.UTF_8);

Store / Load

This pattern uses a key-value/document storage model. An AppEncryption instance can accept a Persistence implementation and hooks into its load and store calls.

Example HashMap-backed Persistence implementation:

Persistence dataPersistence = new Persistence<JSONObject>() {

  Map<String, JSONObject> mapPersistence = new HashMap<>();

  @Override
  public Optional<JSONObject> load(String key) {
    return Optional.ofNullable(mapPersistence.get(key));
  }

  @Override
  public void store(String key, JSONObject value) {
    mapPersistence.put(key, value);
  }
};

Putting it all together, an example end-to-end use of the store and load calls:

// Encrypts the payload, stores it in the dataPersistence and returns a look up key
String persistenceKey = appEncryptionJson.store(originalPayload.toJsonObject(), dataPersistence);

// Uses the persistenceKey to look-up the payload in the dataPersistence, decrypts the payload if any and then returns it
Optional<JSONObject> payload = appEncryptionJson.load(persistenceKey, dataPersistence);

Further Reading

Supported Languages

Feature Support

Feature Java .NET
AWS KMS Support Yes Yes
RDBMS Metastore Yes Yes
DynamoDB Metastore Yes Yes

Current Status

Asherah is currently in incubator status. Please refer to our Roadmap for additional information.

You can’t perform that action at this time.