Crate ironoxide

source ·
Expand description

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.

§User Operations

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();

This 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.

§Group Operations

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();

§Document Operations

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();

Modules§

Structs§

Enums§

Functions§

Type Aliases§

  • A Result alias where the Err case is IronOxideErr