IronOxide - IronCore Labs Rust SDK
The IronOxide Rust SDK is a pure Rust library that integrates IronCore’s privacy, security, and data control solution into your Rust application. Operations in the IronOxide SDK are performed in the context of a user or backend service account. This SDK supports all possible operations that work in the IronCore platform including creating and managing users and groups, encrypting and decrypting document bytes, and granting and revoking access to documents to users and groups.
Users are the basis of IronOxide’s functionality. Each user is a unique identity that has its own public/private key-pair. Users must always act through devices. A device is authorized using a user’s private encryption key and is therefore tightly bound to that user. Data can be never be encrypted directly to a device, so devices can be considered ephemeral as there is no penalty for deleting a device and creating a new one.
This SDK provides all the necessary functionality to manage users and devices. Users can be created, fetched, listed, and updated, while devices can be created and deleted all using IronOxide’s UserOps.
Creating a User
Creating a user with IronOxide::user_create requires a valid IronCore or Auth0 JWT as well as the desired password that will be used to encrypt and escrow the user’s private key.
// Assuming an external function to get the jwt let jwt_str = get_jwt(); let jwt = Jwt::new(jwt_str)?; let password = "foobar"; let opts = UserCreateOpts::new(false); let user_result = IronOxide::user_create(&jwt, password, &opts, None).await?;
Until they generate a device, this user will be unable to make any SDK calls.
Generating a Device
Generating a device with IronOxide::generate_new_device requires a valid IronCore or Auth0 JWT corresponding to the desired user, as well as the user’s password (needed to decrypt the user’s escrowed private key).
// Assuming an external function to get the jwt let jwt_str = get_jwt(); let jwt = Jwt::new(jwt_str)?; let password = "foobar"; let opts = DeviceCreateOpts::new(None); let device_result = IronOxide::generate_new_device(&jwt, password, &opts, None).await?; // A `DeviceAddResult` can be converted into a `DeviceContext` used to initialize the SDK let device_context: DeviceContext = device_result.into();
DeviceContext can now be used to initialize the SDK.
Initializing the SDK
With ironoxide::initialize, you can use a
DeviceContext to create an instance of the
IronOxide SDK object
that can be used to make calls using the provided device.
let config = IronOxideConfig::default(); let sdk = ironoxide::initialize(&device_context, &config).await?;
All calls made with
sdk will use the user’s provided device.
Groups are one of the many differentiating features of the DataControl platform. Groups are collections of users who share access permissions. Group members are able to encrypt and decrypt documents using the group, and group administrators are able to update the group and modify its membership. Members can be dynamically added and removed without the need to re-encrypt the data. This requires a series of cryptographic operations involving the administrator’s keys, the group’s keys, and the new member’s public key. By making it simple to control group membership, we provide efficient and precise control over who has access to what information!
This SDK allows for easy management of your cryptographic groups. Groups can be created, fetched, updated, and deleted using IronOxide’s GroupOps.
Creating a Group
For simple group creation, the group_create function can be called with default values.
use ironoxide::group::GroupCreateOpts; let group_result = sdk.group_create(&GroupCreateOpts::default()).await?; // Group ID used for future calls to this group let group_id: &GroupId = group_result.id();
All secret data that is encrypted using the IronCore platform are referred to as documents. Documents wrap the raw bytes of secret data to encrypt along with various metadata that helps convey access information to that data. Documents can be encrypted, decrypted, updated, granted to users and groups, and revoked from users and groups using IronOxide’s DocumentOps.
Encrypting a Document
For simple encryption to self, the document_encrypt function can be called with default values.
use ironoxide::document::DocumentEncryptOpts; let data = "secret data".to_string().into_bytes(); let encrypted = sdk.document_encrypt(data, &DocumentEncryptOpts::default()).await?; let encrypted_bytes = encrypted.encrypted_data();
Decrypting a Document
Decrypting a document is even simpler, as the only thing required by document_decrypt is the bytes of the encrypted document.
let document = sdk.document_decrypt(encrypted_bytes).await?; let decrypted_data = document.decrypted_data();
Blocking variant of IronOxide
Types useful in multiple modules
IronOxide SDK configuration
Convenience re-export of essential types
Blind Index Search API
Primary SDK Object
Provides soft rotation capabilities for user and group keys
Result of calling
Errors generated by IronOxide SDK operations
Initializes the IronOxide SDK with a device.
Initializes the IronOxide SDK with a device and checks for necessary private key rotations
Result alias where the Err case is