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§
- Blocking variant of IronOxide
- Types useful in multiple modules
- IronOxide SDK configuration
- Document API
- Group API
- Policy types
- Convenience re-export of essential types
- Blind Index Search API
- User API
Structs§
- A struct which holds the basic info that will be needed for making requests to an ironcore service. Currently just the base_url.
- Primary SDK Object
- Provides soft rotation capabilities for user and group keys
Enums§
- Result of calling
initialize_check_rotation
- Errors generated by IronOxide SDK operations
Functions§
- Initializes the IronOxide SDK with a device.
- Initializes the IronOxide SDK with a device and checks for necessary private key rotations
Type Aliases§
- A
Result
alias where the Err case isIronOxideErr