Overview of the IronCore Labs Alloy SDK

The Alloy SDK brings together a set of tools that you can use for your different Application Layer Encryption needs. It unifies functionality that was provided in our SaaS Shield Tenant Security Client (TSC) SDKs and our new Cloaked AI tools in a single library that you can include in your application. This library provides tools to encrypt data using standard, deterministic, and vector encryption algorithms.

Whether you are handling structured or unstructured documents, fields that are stored in a relational database or key value store, vectors that are stored in a vector database, or some combination of these, the Alloy SDK provides the tools you need to protect the private or sensitive data your apps process.

Standard Encryption

The Alloy SDK includes methods for encrypting and decrypting data using standard encryption. These methods are built on the AES algorithm (specifically, AES256-GCM). Typically, data is encrypted using a technique called envelope encryption. A data encryption key (DEK) is chosen at random and used to encrypt the data, then the DEK is encrypted using another key to create an encrypted DEK (EDEK) that is stored along with the encrypted data.

Standard encryption provides the greatest security for the encrypted data, but it is not possible to search for data encrypted in this way. Each time you encrypt the same data (say the string “Hello World”), even if you use the same key, you get a different encrypted output. This is by design; it prevents someone from encrypting a data value of interest then looking for matches in the encrypted data store.

Deterministic Encryption

If you need to be able to find data items that are the same as a specific value, but you want to preserve the privacy and security of the data, you can use deterministic encryption. This encryption technique is similar to standard encryption, but if you encrypt the same piece of data with the same key multiple times, you will get the same encrypted value each time. This allows you to encrypt a target value with a key then search your data store for all matching values.

Deterministic encryption is a form of property preserving encryption - in this case, the property that is preserved even after the data is encrypted is equality. The Alloy SDK has methods for encrypting and decrypting data using deterministic encryption. The algorithm it uses is AES-SIV.

Vector Encryption

The Alloy SDK has a set of methods specifically used to encrypt vectors of real values, such as those produced by an embedding model. The encryption algorithm is another form of property preserving encryption, similar to determinstic encryption described above. The property that is preserved by vector encryption is the distance between vectors, rather than equality. A common use case for vector embeddings is to generate a vector representing a target value that you want to search for in a vector database, using nearest neighbor search. If the vectors have been encrypted with the Alloy SDK, you can encrypt the search vector then use a standard nearest neighbor search (such as one provided by a vector database) to find close matches.

Key Management

One of the most difficult aspects of any system that includes encryption is managing the encryption keys. The Alloy SDK provides two different ways for you to manage the keys that are used for encryption and decryption.

SaaS Shield Integration

This SDK is the next generation of IronCore functionality that was introduced with the SaaS Shield TSC SDKs. It interfaces with the Tenant Security Proxy to provide full Customer Managed Key (CMK) capabilities in your application. The same key management capabilities that are provided for standard encryption and deterministic encryption are available to all components of the Alloy SDK.

Standalone

The SDK can also be configured to operate in a standalone mode that does not require interaction with the TSP and the rest of the SaaS Shield infrastructure. This may be a more appropriate option if you are utilizing the functionality in an application that does not need to offer customer control over the encryption keys. Your app will need to provide a set of secrets that are used to derive the keys needed for standard, deterministic, and vector encryption. These secrets are provided by your app when the SDK is initialized; you will need to manage them using the secret management tools in your application’s infrastructure.

Note on sharing secrets between operations in standalone: for simplicity’s sake you may wish to have a single secret that is used across your different encryption modes (deterministic, standard, vector). To do so, you need to manually configure secrets for each mode with the same secret bytes. Keep in mind that the upside of configuration and rotation simplicity is offset by a reduction in security and a larger blast radius if a key is exposed.

Key Rotation

Whether you use standalone keys or SaaS Shield, the Alloy SDK provides tools to help you manage key rotation, which is a part of the encryption key lifecycle that can be especially tricky.

Using the SDK

The Alloy SDK is distributed as a library that you link into your application. It is available for use in applications built using multiple programming languages:

• Kotlin
• Java
• Python
• Rust

You can declare a dependency on the ironcore-alloy library, which is available in the standard package repository for your chosen language (crates.io, Sonatype, or PyPi), and you can then use any of the Alloy functionality. Detailed docs are available for each language.

The SDKs include methods to encrypt the vectors and any associated metadata, plus methods to prepare a query vector so you can do nearest neighbor searches of the encrypted vectors or to prepare a query string to match metadata for filtering. Our SDK documentation has details.

Source Code

The source for the SDK is publicly available on Github. We welcome feedback, questions, and feature requests.

Changelog

The changelog can be viewed in the library repository.