项目作者: godaddy

项目描述 :
Asherah is a multi-language, cross-platform application encryption SDK
高级语言: C#
项目地址: git://github.com/godaddy/asherah.git
创建时间: 2019-06-17T21:52:15Z
项目社区:https://github.com/godaddy/asherah

开源协议:MIT License

下载


License
CircleCI
Codecov

Asherah

An application-layer encryption SDK that provides advanced encryption features and defense in depth against compromise.

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.

Table of Contents

Introduction

Asherah makes use of multiple layers of keys 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.

  1. SessionFactory sessionFactory = SessionFactory.newBuilder("some_product", "some_service")
  2. .withInMemoryMetastore() // in-memory metastore
  3. .withNeverExpiredCryptoPolicy()
  4. .withStaticKeyManagementService("thisIsAStaticMasterKeyForTesting") // hard-coded/static master key
  5. .build());

Step 2: Create a session

Use the factory to create a session.

  1. Session<byte[], byte[]> sessionBytes = sessionFactory.getSessionBytes("shopper123");

The scope of a session is limited to a partition id, i.e. every partition id should have its own session. Also note
that a payload encrypted using some partition id, cannot be decrypted using a different one.

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.

  1. String originalPayloadString = "mysupersecretpayload";
  2. // encrypt the payload
  3. byte[] dataRowRecordBytes = sessionBytes.encrypt(originalPayloadString.getBytes(StandardCharsets.UTF_8));
  4. // decrypt the payload
  5. String decryptedPayloadString = new String(sessionBytes.decrypt(dataRowRecordBytes), StandardCharsets.UTF_8);

Store / Load

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

Example HashMap-backed Persistence implementation:

  1. Persistence dataPersistence = new Persistence<JSONObject>() {
  2. Map<String, JSONObject> mapPersistence = new HashMap<>();
  3. @Override
  4. public Optional<JSONObject> load(String key) {
  5. return Optional.ofNullable(mapPersistence.get(key));
  6. }
  7. @Override
  8. public void store(String key, JSONObject value) {
  9. mapPersistence.put(key, value);
  10. }
  11. };

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

  1. // Encrypts the payload, stores it in the dataPersistence and returns a look up key
  2. String persistenceKey = sessionJson.store(originalPayload.toJsonObject(), dataPersistence);
  3. // Uses the persistenceKey to look-up the payload in the dataPersistence, decrypts the payload if any and then returns it
  4. Optional<JSONObject> payload = sessionJson.load(persistenceKey, dataPersistence);

Sample Applications

The samples directory includes sample applications that demonstrate use of Asherah SDK using various
languages and platforms.

Further Reading

Supported Languages

Derived Projects

Asherah-Cobhan implementations built atop the Asherah SDK for Go.

Feature Support

  • AWS KMS Support
  • RDBMS Metastore
  • DynamoDB Metastore
  • Session caching
  • Encrypt/Decrypt pattern
  • Store/Load pattern

Contributing

All contributors and contributions are welcome! Please see our contributing docs for more
information.