API

General

Python Absio Library <http://absio.readthedocs.io/>

absio.initialize(api_key, **kwargs)

This method must be called first to initialize the module.

See the section about Obtaining an API Key for more information about the api_key argument.

Parameters:
  • api_key (UUID) – The API key that you have received from Absio.
  • app_name (str) – Name used by the Absio API Server Application to identify different applications. Default: None
  • server_url (str) – The URL of the Absio API Server Application that you intend to use. The api_key that you have been issued must have come from that server instance. Default is https://sandbox.absio.com.
  • root_dir (str) – If using the OFS provider, this will be the root path of the OFS. By default, this will be '.' or the current working directory.
absio.login(user_id, password=None, passphrase=None)

Logs in a User.

Parameters:
  • user_id (UUID) – The identifier of the user to login with.
  • password (str) – The user’s password, used to decrypt their key file. If not provided, then the passphrase must be. The passphrase will be used to grab the file from the provider and recover the password, allowing for decrypting the key file.
  • passphrase (str) – If the user’s key file is not local but is stored on the Absio API Server Application, the passphrase must be provided so that it may be retrieved.
Returns:

The logged in User.

Return type:

User

absio.logout(*args, **kwargs)

Clears any user data cached in memory.

The user will no longer be authenticated with the Absio API Server Application.

absio.is_password_valid(password)

Validates that a password meets the complexity requirements.

By default, the password must be at least 8 characters long and include at least 1 character from 3 of the following types of characters:

  • Lower case
  • Upper case
  • Number
  • Special

You may override this validator globally by replacing this function with your own, or you may pass your validator function as an argument to the functions that allow for credential updates.

Parameters:password (string) – The password to be validated.
Returns:If the password is valid.
Return type:bool
absio.is_passphrase_valid(passphrase)

Validates that a passphrase meets the complexity requirements.

By default, the passphrase must be at least 8 characters long and include at least 1 character from 3 of the following types of characters:

  • Lower case
  • Upper case
  • Number
  • Special

You may override this validator globally by replacing this function with your own, or you may pass your validator function as an argument to the functions that allow for credential updates.

Parameters:passphrase (string) – The passphrase to be validated.
Returns:If the passphrase is valid.
Return type:bool
absio.is_reminder_valid(reminder)

Validates that the reminder meets the complexity requirements.

Absio does not enforce any complexity upon the reminder, therefore this implementation just returns True. It can however be overridden to enforce your requirements.

You may override this validator globally by replacing this function with your own, or you may pass your validator function as an argument to the functions that allow for credential updates.

Returns:If the reminder is valid.
Return type:bool

Container

Containers are the method by which data is passed between users securely.

Crucial to utilizing a container is understanding ‘access’. This specifies details such as with whom the container should be shared, what access and permissions are enabled, if the access should be revoked at a particular time, etc.

Containers have headers and content. Headers are intended to include metadata information. They could contain client-enforceable controls such as “is this recipient allowed to print” or identifiers that help tie the content back to something your system understands. The only restriction is that the header must be JSON serializable, otherwise the sky is the limit as to what can be placed into the header.

The content is assumed to be a file body. However, it too could be more JSON, or XML, or any other type of data. The content is intended to be just that - the data.

Other metadata exists for containers that is not wrapped up and protected by encryption. This information includes the date the container was created, when it was modified, the ‘type’, and the length of the container.

absio.container.create(content, access=None, header=None, type=None, **kwargs)

Creates a Container.

The container will be uploaded to the Absio API Server Application and access will be granted to the specified users. If local storage is being utilized, the container and associated access will also be stored in the OFS.

The container will never expire for the creator. The creator is automatically granted full permissions to the container, unless a limited permission is defined in the access kwarg.

Parameters:
  • content (bytes) – The data to be stored in a container.
  • access (dict, list) – Details about with whom the container is shared and what permissions they have. If not provided, the container will only be accessible to the creator. If access is a dict, the keys need to be user IDs and the values are Access instances for that user. Finally, access can be provided as a list of user IDs. Default access will be granted for each user ID. (Default access is different for the creator and the other recipients; check here for more information.) If access is specified, then the creator must explicitly be included if they should have access.
  • header (JSON serializable data) – Optionally, containers may also contain headers.
  • type (string) – An optional clear bit of metadata that might help explain what type of data has been wrapped up into the container. This can be used to organize containers on the Absio API Server Application.
Returns:

The created Container.

Usage:

# Create a container only accessible by yourself
>>> container = create(content='asdf')
<Container(d21ba58c-9e50-472a-9ce2-5a2595704e7a) Encrypted: True>

# Share with default permissions and access settings to multiple users
>>> users = ['1d4c568b-e762-4284-b14e-167cc4776026', '0e28abdc-1a8f-43db-b565-088161af2b53']
>>> container = create(content='asdf', access=users)
<Container(d21ba58c-9e50-472a-9ce2-5a2595704e7a) Encrypted: True>

# Selectively fine-tune the access information
>>> expiring_access = Access(user_id='1d4c568b-e762-4284-b14e-167cc4776026', expiration=utcnow())
>>> permission = Permission()
>>> permission.container.download = False
>>> limited_access = Access(user_id='0e28abdc-1a8f-43db-b565-088161af2b53', permission=permission)
>>> accesses = [expiring_access, limited_access]
>>> container = create(content='asdf', access={access.id: access for access in accesses})
<Container(d21ba58c-9e50-472a-9ce2-5a2595704e7a) Encrypted: True>
absio.container.delete(container_id, *args, **kwargs)

This revokes the authenticated user’s access to the container.

If local storage is being utilized, the container and the associated access will be removed from the OFS. If the authenticated user is the only user with access, then the content will be deleted from the Absio API Server Application.

Parameters:container_id (UUID) – The ID of the container to delete.

Note

If you want the container itself to be deleted, you must first remove all other user’s access to it and then call this function. This will result in no other users having access and the content then being removed locally and on the Absio API Server Application.

absio.container.get(container_id, *args, portion='all', **kwargs)

Retrieves a container and decrypts it for use.

If local storage is being utilized, the library will first check the OFS. If not using local storage or the container is not found, the latest version will be downloaded from the Absio API Server Application. By default, the content is included (downloaded and decrypted).

Parameters:
  • container_id (UUID) – The ID of the container to fetch.
  • portion (str) – You may choose which section(s) of a container to retrieve. This may be one of content, header, metadata, or all. If either content or header is chosen, then the metadata (access information, date / creation information) is also retrieved.
Returns:

Your container, decrypted if possible.

Return type:

Container

absio.container.get_events(container_type=None, container_id=None, action=None, starting_event_id=None, **kwargs)

Gets all new container events since the last call to this method.

If any of the arguments are provided, then they change the criteria used to query and filter results. These events are retrieved from the Absio API Server Application.

Parameters:
  • container_type (string) – Only events of the specified container type will be returned. Type is a string used to categorize containers on the Absio API Server Application.
  • container_id (UUID) – Filter the results to only include events related to the specified container ID.
  • action (EventAction) – Filters the results to only include events that have the specified action.
  • starting_event_id (int) – 0 will start from the beginning and download all events for the current user with the specified criteria. Use the event_id field from a container event to start from a known event. If omitted, the newest events since the last call will be downloaded.
Returns:

All of the events that match the filter criteria.

Return type:

list of Events

absio.container.update(container_id, **kwargs)

Updates a container with the specified ID.

At least one of the optional kwargs must be provided for an update to occur. This will update the container and access information on the Absio API Server Application as well as in the OFS.

Parameters:
  • container_id (UUID) – The ID of the container to update.
  • access (dict, list) – Details about with whom the container is shared and what permissions they have. If not provided, the container will only be accessible to the creator. If access is a dict, the keys need to be user IDs and the values are Access instances for that user. Finally, access can be provided as a list of user IDs. Default access will be granted for each user ID. (Default access is different for the updater and the other recipients; check here for more information.) If access is specified, then the updater must explicitly be included if they should have access.
  • content (bytes) – New content to be encrypted.
  • header (JSON serializable data) – A new header to be applied.
  • type (string) – A new string to categorize the container on the Absio API Server Application.
class absio.crypto.container.Container(data=None, content_cls=<class 'absio.crypto.container.RawPayload'>, **kwargs)

Creates an Intelligent Data Object (Container).

Parameters:
  • data (encrypted bytes) – If data is provided, this represents a container in its entirety and is therefore considered to be an encrypted container.
  • content_cls (RawPayload) – This allows for determing what type of content payload is constructed. Some types of containers use a JSON payload, while others use bytes. By changing the constructor type, the data can automatically be translated into the format you desire.
  • container_id (UUID) – This is an optional kwarg used to construct an unencrypted Container.
  • header (JSON serializable unencrypted data) – An unencrypted payload for the header portion of a container.
  • content (Unencrypted data) – The unencrypted payload for the content portion of a container.
  • type" (string) – Allows for organization of containers on the Absio API Server Application.
container_keys = None

The ContainerKeys that were used to encrypt the container, if encrypted.

content = None

The container content

created_at

When the container was created

created_by

Who created the container

data

The data of a container.

decrypt(container_keys=None)

Decrypts a Container.

Parameters:container_keys (ContainerKeys) – An optional parameter, the container_keys that came from decrypting the recipient key blob (RKB). If not provided, and the Container keys were stored as part of the encryption process, those stored keys will be used.
encrypt(container_keys=None)

Encrypts a Container.

Parameters:container_keys (ContainerKeys) – If keys are provided, they will be used to do the encryption, otherwise a new set will be created.
Returns:ContainerKeys
encrypted

A property that returns a boolean indicating whether or not the container is encrypted.

header = None

The container header.

id = None

The UUID of the container.

modified_at

When the container was modified

modified_by

Who last modified the container.

type = None

The container’s type.

class absio.crypto.container.ContainerKeys(cipher_index=0, mac_index=0, cipher_key=None, mac_key=None)

Unique keys to perform cyrptographic operations on a Container.

cipher_index
cipher_key
static from_bytes()
mac_index
mac_key

Access

The Access object is used by the container create, update, and get functions to define a user’s access to a container. The access information includes specific permissions and an optional expiration.

class absio.access.Access(user_id, permissions=None, expiration=None, key=None)

Used to define a user’s access to a container.

Parameters:
  • user_id (UUID or string) – For whom this access applies.
  • permissions (Permissions or int) – What level of access they will have.
  • expiration (datetime) – When the access to the container will be revoked. If None, the access will never expire.
  • key (base64 encoded data) – The recipient’s key blob.
created_at
created_by
key_blob

The unique keys required to decrypt the container, for this particular access.

modified_at
modified_by
permissions = None

The Permissions associated with this access. By default if None is provided, a Permissions instance will be built, with full permissions.

user_id = None

The user to whom this access is for.

Permissions

Permissions are a critical component of Access.

Permissions are rules for the Absio API Server Application to enforce. The permissions define how the Absio API Server Application will respond to create, get, update and delete operations for a given container. Therefore, the absio library and Absio API Server Application will be enabled or disabled from performing certain operations based on these permissions as well.

For instance, if the container.download property is False for a user and they request the container with the get function, the Container instance returned to the user will not have the decrypted content or header since the Absio API Server Application will not allow access to this information to the absio library.

The following table defines the possible permissions:

Permission Creator’s Default Other User’s Default Description
access.view True True Permission to view the full access list containing all other user’s IDs, expiration dates, and permissions. Set to False to prevent a user from seeing other user’s access information for the container.
access.modify True False

Permission to add, remove, or update all users’ access to a container. Set to True to allow a user to modify access to the container.

Note

You should also set access.view to True if this is True. Otherwise, the user can modify the access list, but not include others who have access.

container.decrypt True True Permission to access the unique contianer- specific keys required for this user to to decrypt the container. Set to False to prevent a user from being able to decrypt the container’s content and header.
container.download True True Permission to allow a user to download the encrypted container’s data. Set to False to prevent a user from accessing the encrypted container data.
container.type.view True False Permission to view the container’s type attribute. Set to True to allow a user to see the container’s type attribute.
container.type.modify True False Permission to modify the container’s type attribute. Set to True to allow a user to make changes to a container’s type attribute.
container.upload True False

Permission to upload changes to the container’s content and header. Set to True to allow a user to upload changes to the container’s content and header.

Note

If setting access.modify to True, access.view and access.modify should also be set to True. Otherwise this combination of permissions will be rejected by the Absio API Server Application.

Known Permission “Error” Cases

The following are some permission states that may have adverse effects:

  1. access.view is False and access.modify is True. The user can update the access list but will not know the other users with current access. Thus the update could potentially remove all other users from the current access list (aside from the user performing the action).
  2. access.view is True and container.upload is True and access.modify is False. This operation will be rejected by the Absio API Server Application. Since uploading content requires re-keying the data, all access must be updated (each user with access will receive new keys). Since they cannot modify access, it will be rejected.
  3. container.upload is False. Calls to update may be rejected.
  4. container.download is False or container.decrypt is False. If the data is not cached locally in the Obfuscating File System, calls to get will return a Container with both content and header both not containing any data.
class absio.permissions.Permissions(value=127)

An easy way to set access permissions.

An instance of this class may be passed when specifying Access.

Each individual permission value is defined here.

Usage:

# By default, all permissions are set.
>>> Permissions()
<Permission(container.download|container.decrypt|container.upload|container.type.view|container.type.modify|access.view|access.modify) int=127>

# It is easy to individually remove permissions.
>>> p = Permissions()
>>> p.container.download = False
>>> p.container.decrypt = False
<Permission(container.upload|container.type.view|container.type.modify|access.view|access.modify) int=124>

# It is easy to selectively add permissions.
>>> p = Permissions(value=0)  # Start with no permissions.
>>> p.access.view = True
<Permission(access.view) int=8>

# You can also reconstruct permission flags if you know the integer value.
>>> Permissions(value=42)
<Permission(container.decrypt|container.type.modify|access.view) int=42>

Event

class absio.event.Event(action, id, changes, client_app_name, container_expired_at, container_id, container_modified_at, container_type, date, related_user_id, type)

Notification that something has happened.

The Absio API Server Application tracks all container and key file actions (accessed, added, updated, and deleted). This information may help you become aware of new containers, or receive updates from other users.

action

Always one of accessed, added, deleted, or updated.

id

An integer value for this event. Event IDs are constantly increasing.

changes

Information about what has changed. For example: {'field that changed': 'updated value'}

client_app_name

The name of the application responsible for the action. This may or may not exist, depending on the settings configured in the responsible application.

container_expired_at

A datetime object if the container has expired, None otherwise.

container_id

The container ID (UUID) that this event relates to, if type is container.

container_modified_at

A datetime object corresponding to when the container content was last modified. It does not change when updating the access, header, or type of a container and will be None in those cases.

container_type

The container type as specified upon creation or last update.

date

A datetime object corresponding to when the event occurred.

related_user_id

If this event relates or was triggered by another user, this field will be set to that user’s ID (UUID).

type

The event type, always one of container or key_file.

class absio.event.EventSchema(extra=None, only=(), exclude=(), prefix='', strict=None, many=False, context=None, load_only=(), dump_only=(), partial=False)

User

Handles Absio User Accounts.

class absio.user.User(id, key_file)

An Absio User.

id = None

The user’s ID value (UUID)

key_file

The user’s decrypted Key File.

keys = None

The user’s key ring. Contains both signing and derivation keys. If this user is one that has been logged in, this key ring will contain the private keys. Otherwise it will only have the public keys.

absio.user.change_credentials(password, passphrase, reminder=None, password_validator=<function is_password_valid>, reminder_validator=<function is_reminder_valid>, passphrase_validator=<function is_passphrase_valid>)

Changes the user’s credentials (password and passphrase) for the account.

Use a secure value for the passphrase as it can be used to reset the user’s password. This operation causes the key file to be re-encrypted. The new copy of the key file will be pushed to the Absio API Server Application. If local storage is being utilized, it will also be saved in the OFS.

Parameters:
  • password (string) – The new password to be used.
  • passphrase (string) – The new passphrase to be used.
  • reminder – An optional reminder that can be used to help recall the passphrase. This is publicly available in plain text. Do not include sensitive information or wording that allows the passphrase to be easily compromised.
  • password_validator – An optional validator to enforce password complexity requirements. If provided, it should take a single argument (the password) and return a boolean indicating whether or not the password passes validation.
  • reminder_validator (callable) – An optional validator to enforce passphrase complexity requirements. If provided, it should take a single argument (the passphrase) and return a boolean indicating whether or not the passphrase passes validation.
  • passphrase_validator (callable) – An optional validator to enforce passphrase complexity requirements. If provided, it should take a single argument (the passphrase) and return a boolean indicating whether or not the passphrase passes validation.
absio.user.create(password, reminder, passphrase, password_validator=<function is_password_valid>, reminder_validator=<function is_reminder_valid>, passphrase_validator=<function is_passphrase_valid>)

Creates a new user, registering them on the Absio API Server Application

Generates private keys and registers a new user on the Absio API Server Application. The user’s private keys are encrypted with the password to product a Key File. The passphrase is used to reset the password and download the Key File from the Absio API Server Application. If local storage is utilized, the Key File is also saved in the Obfuscating File System.

Parameters:
  • password (string) – Used to encrypt the key file.
  • reminder (string) – Used to prompt the user to remember their passphrase if trying to retrieve their key file from the Absio API Server Application.
  • passphrase (string) – Allows the user to reset the password and download their key file.
  • password_validator (callable) – An optional validator to enforce password complexity requirements. If provided, it should take a single argument (the password) and return a boolean indicating whether or not the password passes validation.
  • reminder_validator (callable) – An optional validator to enforce passphrase complexity requirements. If provided, it should take a single argument (the reminder) and return a boolean indicating whether or not the reminder passes validation.
  • passphrase_validator (callable) – An optional validator to enforce passphrase complexity requirements. If provided, it should take a single argument (the passphrase) and return a boolean indicating whether or not the passphrase passes validation.
Returns:

The newly created user.

Return type:

User

absio.user.delete()

Removes a user permanently.

Danger

This function cannot be undone. All data associated with the user will be permanently deleted and cannot be recovered. Use with caution.

absio.user.get_backup_reminder(user_id=None)

Gets the publicly accessible reminder for the user’s backup passphrase.

Parameters:user_id (UUID) – The identifier of the user for whom the reminder should be retrieved. If no value is provided, the ID of the currently authenticated user will be used.
Returns:The publicly accessible reminder for the user’s backup passphrase.

Providers

Server Cache OFS

This provider joins together the Server and OFS providers and is the default.

The OFS is intended to be used as a cache. Generally speaking, when querying for data the OFS is first interrogated. If it is not found, it is requested from the server. If the server has the data, we attempt to store it into the OFS cache prior to returning it.

Unlike the other providers, this provider supports options. These can be set with the provider context manager, or manipulated directly on the provider itself.

absio.providers.server_cache_ofs.login(user_id=None, password=None, passphrase=None, user=None)

Logs the user into the provider’s session.

absio.providers.server_cache_ofs.logout(*args, **kwargs)

Logs the user out of the provider’s session.

absio.providers.server_cache_ofs.initialize(api_key, **kwargs)

Initializes both the OFS and server providers.

absio.providers.server_cache_ofs.session = namespace(user=None)

The provider session will store the logged in user in the user attribute. Upon logout, the user will be cleared out.

absio.providers.server_cache_ofs.options = namespace(force_refresh=False)

These options will modify the behavior of the provider.

Option Default Purpose
force_refresh False Since the server_cache_ofs provider uses the OFS as a cache (which does not expire), then getting updated info into the cache could be a tricky matter. Setting this flag to True will result in data look ups avoiding querying the OFS first, instead reaching out for the data on the server. The newly retrieved data will then be stored in the OFS.

The force_refresh option in particular is useful when syncing events.

Container

absio.providers.server_cache_ofs.container.delete(container_id)

Removes a container from the OFS and the server.

absio.providers.server_cache_ofs.container.get(container_id, *args, portion='all', **kwargs)

Retrieves a container out of the OFS, falling back on the server if necessary.

This method will decrypt the container, if possible. Reasons for failing to decrypt the container include:

  1. Insufficient permissions.
  2. No data was stored on the Absio API Server Application
Parameters:
  • container_id (UUID) – The ID of the container to be fetched.
  • portion (str) – You may choose which section(s) of a container to retrieve. This may be one of content, header, metadata, or all. If either content or header is chosen, then the metadata (access information, date / creation information) is also retrieved.
Returns:

Your container, decrypted if possible.

Return type:

Container

absio.providers.server_cache_ofs.container.update_or_create(container, *args, **kwargs)

Updates or creates the container on the server, then tries to mirror the changes in the OFS.

The kwargs are forwarded to the absio.providers.server.container.update_or_create() function.

Events

absio.providers.server_cache_ofs.events.get(**kwargs)

Retrieves events from the Absio API Server Application.

Events are not cached in the OFS.

Parameters:
  • type (string: One of container or key_file.) – What type of event to fetch.
  • container_id (UUID) – If interested in events for a particular container, pass in the ID.
  • container_type (string) – Filter by the type of container.
  • action (One of accessed, added, deleted, or updated.) – Filter by the event’s action.
  • starting_event_id (int) – Only retrieve events >= to this ID value.

Key File

absio.providers.server_cache_ofs.key_file.get(user_id, password=None, passphrase=None)

Retrieves a key file from the OFS, falling back to the server.

Returns:The user’s decrypted key file is returned.
Return type:KeyFile.
absio.providers.server_cache_ofs.key_file.needs_sync(user_id=None)

Returns a bool indicating whether or not the Key File is synced.

If the Key File doesn’t exist in the OFS, or if it’s checksum doesn’t match the version hosted by the Absio API Server Application, this will return False.

This function only exists for this provider as it serves to bridge the gap between the two.

Returns:Whether or not the Key Files are different.
Return type:bool
absio.providers.server_cache_ofs.key_file.sync(passphrase, user_id=None, password=None)

Syncs a key file from the server to the OFS.

Parameters:
  • passphrase (str) – As the file is fetched from the Absio API Server Application, the passphrase must be provided. Because the passphrase can also be used to recover the password, the password argument is optional.
  • password (str) – If provided, the password will be used to decrypt the retrieved key file. This can be used to validate that the caller is in possession of both sets of credentials.
  • user_id (UUID) – If not provided, the ID of the user in the current session will be used.
Returns:

The user’s decrypted key file is returned.

Return type:

KeyFile.

absio.providers.server_cache_ofs.key_file.update_or_create(key_file, **kwargs)

Stores a new version of the keys file on the server and in the OFS.

Keys

absio.providers.server_cache_ofs.keys.get(user_id)

Retrieves the public keys for a user.

Parameters:user_id (UUID) – The ID of the user for whom the keys should be fetched.
Returns:A key ring containing only the public keys.
Return type:KeyRing

User

Server

All content is stored on the Absio API Server Application.

absio.providers.server.client = <module 'absio.providers.server.client' from '/home/scott/code/python-absio/src/absio/providers/server/client.py'>

A REST client that knows how to communicate with the Absio API Server Application. Behaves very similarly to the requests module.

absio.providers.server.login(user_id=None, password=None, passphrase=None, user=None)

Logs a user into the server provider’s session.

Parameters:
  • user_id (UUID) – An ID value of the user to login as.
  • password (str) – The user’s password. If not provided, passphrase must be. Then the pasword will be rescued from the Key File.
  • passphase – The user’s backup passphrase used to retrieve the Key File (and optionally rescue the password.)
  • user (User) – An existing user that may have been logged in via another provider.
absio.providers.server.logout(*args, **kwargs)

Logs the current user out of the server provider’s session.

absio.providers.server.initialize(api_key, server_url='https://sandbox.absio.com', **kwargs)

Begins setting up the server provider.

Parameters:
  • api_key (UUID) – The API Key used to identify and authenticate with the Absio API Server Application.
  • server_url (str) – The base URL of your desired server instance.

Container

absio.providers.server.container.delete(container_id)

Removes a user’s access to a container on the server.

This will not remove a container in its entirety. A container may be shared with other recipients and will not be removed from the server until no accesses exist. If you would like to entirely remove a container (and it is shared with other users), you must first update the container and remove their access.

Parameters:container_id (UUID) – The ID of the container to delete.
absio.providers.server.container.get(container_id, portion='all', decrypt=True)

Retrieves a container from the server.

This method will decrypt the container, if possible. Reasons for failing to decrypt the container include:

  1. Insufficient permissions.
  2. No data was stored on the Absio API Server Application
Parameters:
  • container_id (UUID) – The ID of the container to be fetched.
  • portion (str) – You may choose which section(s) of a container to retrieve. This may be one of content, header, metadata, or all. If either content or header is chosen, then the metadata (access information, date / creation information) is also retrieved.
  • decrypt (bool) – If True, the container will be returned decrypted, if possible.
Returns:

Your container, decrypted if possible.

Return type:

Container

absio.providers.server.container.update_or_create(container, requires_upload=True, access_changed=False, type_changed=False)

Uploads a new version of the container to the server.

Parameters:
  • container (Container) – The encrypted container to be uploaded to the server.
  • requires_upload (bool) – Whether or not the encrypted data has changed, warranting a new upload.
  • access_changed (bool) – Whether or not the container’s access has changed. This is ignored if requires_upload is True, as the access will be set regardless during the upload process.
  • type_changed (bool) – Whether or not the type of a container has changed. This is ignored if requires_upload is True, as the type will be set regardless during the upload process.
Returns:

The container in its updated state. This will contain refreshed timestamps and may have a different view of the access, depending upon the permissions that were applied.

Return type:

Container

Events

absio.providers.server.events.get(**kwargs)

Retrieves events from the Absio API Server Application.

Parameters:
  • type (string: One of container or key_file.) – What type of event to fetch.
  • container_id (UUID) – If interested in events for a particular container, pass in the ID.
  • container_type (string) – Filter by the type of container.
  • action (One of accessed, added, deleted, or updated.) – Filter by the event’s action.
  • starting_event_id (int) – Only retrieve events >= to this ID value.
Returns:

All matching events.

Return type:

list of Events

Key File

absio.providers.server.key_file.get(user_id, passphrase, password=None)

Retrieves a decrypted key file from the server.

If the password is provided, use it to decrypt the file, otherwise use the rescued password.

Parameters:
  • passphrase (str) – The passphrase associated with the key file. This is used to retrieve the file and may be used to decrypt it as well, depending upon whether or not the password argument is provided.
  • password (str) – Will be used to decrypt the key file.
absio.providers.server.key_file.update_or_create(key_file, passphrase=None, reminder=None)

Uploads a new version of the keys file to the server.

Parameters:
  • key_file (KeyFile) – The file to be stored on the server.
  • passphrase – A passphrase that can be used to retrieve the file back down from the server in an un-authenticated session. This will be hashed before it is sent to the server.
  • reminder (str) – If the passphrase is a human generated value, this reminder may help them remember what the passphrase is. Think of a security question / answer pairing.
Str passphrase:

str

Keys

absio.providers.server.keys.get(user_id)

Retrieves the public keys for a user from the Absio API Server Application.

Parameters:user_id (UUID) – The ID of the user for whom the keys should be fetched.
Returns:A key ring containing only the public keys.
Return type:KeyRing

User

absio.providers.server.user.change_credentials(password, passphrase, reminder=None, password_validator=<function is_password_valid>, passphrase_validator=<function is_passphrase_valid>, reminder_validator=<function is_reminder_valid>, **kwargs)

Changes a user’s password and passphrase.

absio.providers.server.user.create(signing_key, derivation_key)

Creates a new user on the Absio API Server Application.

Parameters:
  • signing_key (AuthKey) – The key the user will use for authentication / signature verification operations.
  • derivation_key (DerivationKey) – The key the user will use for unique secure container encryption key creation and key exchange algorithms.
Returns:

The user, as it was created on the server. Will populate their id value.

Return type:

User

absio.providers.server.user.delete(user)

Permanently removes the user from the Absio API Server Application.

This cannot be undone. Use with caution.

absio.providers.server.user.get_backup_reminder(user_id, **kwargs)

Retrieves the user’s reminder associated with their key file.

OFS

All content is stored in the Absio Obfuscating File System (OFS).

absio.providers.ofs.db = <absio.providers.ofs.database.AbsioDatabase object>

The OFS has a SQLite database where all data stored inside of it is encrypted. This database may be accessed here.

absio.providers.ofs.client = <absio.providers.ofs.ofs_client.AbsioOFSClient object>

The OFS client allows for creating and looking up random file locations, and then reading / writing to those locations.

absio.providers.ofs.login(user_id=None, password=None, passphrase=None, user=None)

Logs a user into the OFS provider’s session.

absio.providers.ofs.initialize(api_key, root_dir='.', **kwargs)

Begins setting up the OFS provider.

absio.providers.ofs.logout(*args, **kwargs)

Logs the current user out of the OFS provider session.

absio.providers.ofs.session = namespace(user=None)

The provider session will store the logged in user in the user attribute. Upon logout, the user will be cleared out.

Container

absio.providers.ofs.container.delete(container_id)

Removes a container from the OFS.

absio.providers.ofs.container.get(container_id, *args, portion='all', **kwargs)

Retrieves a container from the OFS.

This method will decrypt the container, if possible. Reasons for failing to decrypt the container include:

  1. Insufficient permissions.
  2. No data was stored on the Absio API Server Application
Parameters:
  • container_id (UUID) – The ID of the container to be fetched.
  • portion (str) – You may choose which section(s) of a container to retrieve. This may be one of content, header, metadata, or all. If either content or header is chosen, then the metadata (access information, date / creation information) is also retrieved.
Returns:

Your container, decrypted if possible.

Return type:

Container

absio.providers.ofs.container.update_or_create(container, *args, portion='all', **kwargs)

Stores a new version of the container in the OFS.

Key File

absio.providers.ofs.key_file.get(user_id, password=None, passphrase=None, **kwargs)

Retrieves a decrypted key file from the OFS.

absio.providers.ofs.key_file.get_checksum(user_id)

Retrieves a key file’s SHA384 checksum.

absio.providers.ofs.key_file.update_or_create(key_file, **kwargs)

Stores a new version of the keys file in the OFS.

Keys

absio.providers.ofs.keys.get(user_id)

Retrieves the public keys for a user from the OFS.

Parameters:user_id (UUID) – The ID of the user for whom the keys should be fetched.
Returns:A key ring containing only the public keys.
Return type:KeyRing
absio.providers.ofs.keys.update_or_create(key_ring)

Stores the public keys for a user in the OFS.

Parameters:key_ring (KeyRing) – The keys to be stored. Only the public portions will be stored.

User

Manipulates users in the OFS.

absio.providers.ofs.user.change_credentials(password, passphrase, password_validator=<function is_password_valid>, passphrase_validator=<function is_passphrase_valid>, **kwargs)

Changes a user’s credentials.

A new Key File is generated and stored in the OFS.

absio.providers.ofs.user.create(signing_key, derivation_key, user_id=None)

Creates a user in the OFS.

absio.providers.ofs.user.delete(user)

Deletes a user from the OFS.

All data stored in the OFS root directory will be removed.

Crypto

The Absio SDK provides basic cryptographic operations: key generation, key exchange, encyption/decryption, HMAC, signing, hashing and elliptic curve cryptography (ECC). A custom Integrated Encryption Scheme (IES) for confidentiality and source verification is included as part of the ECC features.

Symmetric Encryption / Decryption

exception absio.crypto.aes.DecryptionError

Raised for decryption problems.

For instance, if we expect the decrypted data to be a de-serializable JSON string and it is not.

absio.crypto.aes.create_iv)

Creates an initialization vector (iv).

Returns:An initialization vector.
Return type:bytes
absio.crypto.aes.create_key()

Creates a key suitable for usage with AES256.

Returns:A symmetric key.
Return type:bytes
absio.crypto.aes.decrypt(data, cipher_key, iv)

Symmetrically decrypts with AES.

Parameters:
  • data (bytes) – Ciphertext data to be decrypted.
  • cipher_key (bytes) – The symmetric key to be used for decryption.
  • iv (bytes) – An initialization vector.
Returns:

Plaintext for the decrypted data in bytes.

Return type:

bytes

absio.crypto.aes.encrypt(data, cipher_key, iv)

Symmetrically encrypts with AES.

Parameters:
  • data (bytes) – Plaintext data to be encrypted.
  • cipher_key (bytes) – The symmetric key to be used for encryption.
  • iv (bytes) – An initialization vector.
Returns:

Ciphertext for the encrypted data in bytes.

Return type:

bytes

Hashing

absio.crypto.hash.get_hash(data, algorithm=<class 'cryptography.hazmat.primitives.hashes.SHA384'>)

Tries to intelligently hash a data value.

If the data is itself already a hash, it does nothing.

Parameters:
  • data (bytes) – The data to hash.
  • algorithm (callable) – Which hashing algorithm to use.
Returns:

A hexdigest string.

Absio Integrated Encryption Scheme

Included in the IES module is a special Integrated Encryption Scheme.

In this scheme ECDH is computed using the recipient user’s public derivation key. The resultant key is used to encrypt the data. That data is then signed with the sending user’s signing key. By default this will use AES 256 CTR NoPadding along with ECDH and ECDSA both using curve P384. There is also a simple command line utility to perform the encrypt and decrypt operations.

absio.crypto.ies.decrypt(data, recip_keys, sender_keys=None)

Decrypts some ECC data.

Parameters:
  • recip_keys – The recipient’s key ring. The data will contain a reference to which Derivation key was used in the creation and from that information, the correct key will be chosen.
  • sender_keys – The sender’s key ring, used for signature verification. If not provided, the signing key material embedded in the data will be used instead.
absio.crypto.ies.encrypt(data, sender_keys, recip_keys, obj_id=None)

Encrypts some data with an ephemeral key.

Parameters:
  • sender_keys – The sender’s key ring, used for signature verification.
  • recip_keys – The recipient’s key ring. The data will contain a reference to which Derivation key was used in the creation and from that information, the correct key will be chosen.

Diffie-Hellman Key Exchange

absio.crypto.ecdhe.exchange(private_key, public_key)

Performs an Elliptic Curve Diffie Hellman key exchange.

Parameters:
  • private_key (P384 private key.) – Your private key.
  • public_key (P384 publix key.) – The public key belonging to the party to which the exchange should take place.
Returns:

A shared key.

Return type:

bytes

HMAC

The library will perform HMAC operations to ensure data integrity.

By default it will perform HMAC-SHA384.

absio.crypto.hmac.digest(private_key, data)

Creates an HMAC-SHA384 digest of some data with a private key.

Parameters:
  • private_key (bytes) – Some private key material.
  • data (bytes) – Data to be HMAC’d.
Returns:

The HMAC of the input data.

Return type:

bytes

absio.crypto.hmac.generate_key()

Creates a key suitable for HMAC-SHA384 operations.

Returns:A private key.
Return type:bytes
absio.crypto.hmac.verify(private_key, data, digest)

Verifies the HMAC of some data.

Parameters:
  • private_key (bytes) – Some private key material.
  • data (bytes) – The original data to be verified.
  • digest (bytes) – The original HMAC of the data.
Returns:

None if the verification was successful, raises an exception otherwise.

Return type:

None

Signature

absio.crypto.ecdsa.sign(private_key, data)

Signs some data.

Parameters:
  • private_key (TBD) – The private key to use for signing.
  • data (bytes) – The data to be signed.
Returns:

The signature.

Return type:

bytes

absio.crypto.ecdsa.verify(public_key, data, signature)

Signature verification.

For some given data and a signature, it will verify that it was in fact signed using the private key related to the provided public key.

Parameters:
  • public_key (TBD) – The public key corresponding to the private key used to generate the signature.
  • data (bytes) – The original data that was signed.
  • signature (bytes) – The resulting signature that is to be verified.
Returns:

None if the signature is valid, raises an exception otherwise.

Return type:

None