red_october package

Submodules

red_october.exceptions module

exception red_october.exceptions.RedOctoberDecryptException[source]

Bases: red_october.exceptions.RedOctoberRemoteException

This exception is raised when there are errors decrypting a file.

exception red_october.exceptions.RedOctoberException[source]

Bases: exceptions.EnvironmentError

This exception is raised from errors in the RedOctober Library.

exception red_october.exceptions.RedOctoberRemoteException[source]

Bases: red_october.exceptions.RedOctoberException

This exception is raised to indicate issues returned from API.

red_october.red_october module

class red_october.red_october.RedOctober(host, port, name, password, ssl=True, verify=True)[source]

Bases: object

It provides Python bindings to a remote RedOctober server via HTTP(S).

Additional documentation regarding the API endpoints is available at https://github.com/cloudflare/redoctober

call(endpoint, method='POST', params=None, data=None)[source]

It calls the remote endpoint and returns the result, if success.

Parameters:
  • endpoint (str) – RedOctober endpoint to call (e.g. newcert).
  • method (str) – HTTP method to utilize for the Request.
  • params – (dict or bytes) Data to be sent in the query string for the Request.
  • data – (dict or bytes or file) Data to send in the body of the Request.
Raises:

RedOctoberRemoteException – In the event of a False in the success key of the API response.
Returns:

Data contained in result key of the API response, or

True if there was no response data, but the call was a success.
Return type:

mixed
cancel_order(order_num)[source]

It cancels an order by number.

Parameters:order_num (str) – Order number to get.
Returns:Status of order cancellation.
Return type:bool
change_password(new_password)[source]

It allows users to change their password.

Parameters:
  • name (str) – Name of account.
  • password (str) – Password for account.
  • new_password (str) – New password for account.
Returns:

Password change status.
Return type:

bool
create_order(labels, duration, uses, data)[source]

It creates lets others users know delegations are needed.

Parameters:
  • labels (iter) – Iterator of strings to label order with.
  • duration (datetime.timedelta) – Proposed duration of delegation.
  • uses (int) – Proposed delegation use amounts.
  • data (str) – Base64 encoded string representing the encrypted string.
Returns:

Mapping representing the newly created order. Example:

{
    "Admins": [
         "Bob",
         "Eve"
     ],
     "AdminsDelegated": null,
     "Delegated": 0,
     "DurationRequested": 3.6e+12,
     "Labels": [
         "blue",
         "red"
     ],
     "Name": "Alice",
     "Num": "77da1cfd8962fb9685c15c84",
     "TimeRequested": "2016-01-25T15:58:41.961906679-08:00",
 }

Return type:

dict
create_user(user_type='rsa')[source]

It creates a new user account.

Allows an optional UserType to be specified which controls how the record is encrypted. This can have a value of either rsa or ecc and if none is provided will default to rsa.

Parameters:user_type (str) – Controls how the record is encrypted. This can have a value of either ecc or rsa.
Returns:Status of user creation.
Return type:bool
create_vault()[source]

It creates a new vault.

Create is the necessary first call to a new vault. It creates an admin account.

Returns:Status of vault creation
Return type:bool
decrypt(data)[source]

It allows a user to decrypt a piece of data.

Parameters:data (str) – Base64 encoded string representing the encrypted string.
Raises:RedOctoberDecryptException – If not enough minimum users from the set of owners have delegated their keys to the server, or if the decryption credentials are incorrect.
Returns:
Response object with the following keys:
  • Data (str): Decrypted data
  • Secure (bool): Not documented. Seems to always be True
  • Delegates (list of str): Delegate names
Return type:dict
delegate(time=None, uses=None)[source]

It allows for the delegation of decryption rights.

Delegate allows a user to delegate their decryption password to the server for a fixed period of time and for a fixed number of decryptions. If the user’s account is not created, it creates it. Any new delegation overrides the previous delegation.

Parameters:
  • time (datetime.timedelta) – Period of time that delegation is valid for.
  • uses (int) – Number of times that delegation can be used.
Returns:

Status of delegation creation.
Return type:

bool
encrypt(minimum, owners, data)[source]

It allows a user to encrypt a piece of data.

Parameters:
  • minimum (int) – Minimum number of users from owners set that must have delegated their keys to the server.
  • owners (iter) – Iterator of strings indicating users that may decrypt the document.
  • data (str) – Data to encrypt.
Returns:

Base64 encoded string representing the encrypted string.
Return type:

str
get_order_information(order_num)[source]

It gets information for a specified order.

Parameters:order_num (str) – Order number to get.
Returns:Mapping representing the order information. Example:
{
    "Admins": [
        "Bob",
        "Eve"
    ],
    "AdminsDelegated": null,
    "Delegated": 0,
    "DurationRequested": 3.6e+12,
    "Labels": [
        "blue",
        "red"
    ],
    "Name": "Alice",
    "Num": "77da1cfd8962fb9685c15c84",
    "TimeRequested": "2016-01-25T15:58:41.961906679-08:00"
}
Return type:dict
get_orders_outstanding()[source]

It returns a mapping of current orders.

Returns:Mapping representing the currently open orders. Example:
{
    "77da1cfd8962fb9685c15c84":{
        "Name":"Alice",
        "Num":"77da1cfd8962fb9685c15c84",
        "TimeRequested":"2016-01-25T15:58:41.961906679-08:00",
        "DurationRequested":3600000000000,
        "Delegated":0,"
        AdminsDelegated":null,
        "Admins":["Bob, Eve"],
        "Labels":["Blue","Red"]
    }
}
Return type:dict
get_owners(data)[source]

It provides the delegates required to decrypt a piece of data.

Parameters:data (str) – Base64 encoded string representing the encrypted string.
Raises:RedOctoberDecryptException – If incorrect decryption credentials are provided.
Returns:
List of strings representing users that are able to decrypt
the data.
Return type:list
get_summary()[source]

It provides a list of keys and delegations for the server.

Returns:
A mapping containing keys on the system, and users who have
currently delegated their key to the server. Example:
 {
 "Live":{
 "Bill":{"Admin":false,
         "Type":"rsa",
         "Expiry":"2013-11-26T08:42:29.65501032-08:00",
         "Uses":3},
 "Cat":{"Admin":false,
        "Type":"rsa",
        "Expiry":"2013-11-26T08:42:42.016311595-08:00",
        "Uses":3},
 "Dodo":{"Admin":false,
         "Type":"rsa",
         "Expiry":"2013-11-26T08:43:06.651429104-08:00",
         "Uses":3}
},
"All":{
 "Alice":{"Admin":true, "Type":"rsa"},
 "Bill":{"Admin":false, "Type":"rsa"},
 "Cat":{"Admin":false, "Type":"rsa"},
 "Dodo":{"Admin":false, "Type":"rsa"}
}
Return type:dict
modify_user_role(modify_name, command='revoke')[source]

It allows for administration of user roles.

Parameters:
  • modify_name (str) – Name of account to modify.
  • command (str) – Command to apply to user: admin: Promote user to administrator. revoke: Revoke administrator rights. delete: Delete user.
Returns:

Role modfication status.
Return type:

bool
purge_delegates()[source]

It deletes all delegates for an encryption key.

Returns:Purge status.
Return type:bool

Module contents

This library allows you to interact with a remote Red October Instance using Python.

Red October is a cryptographically-secure implementation of the two-person rule to protect sensitive data. From a technical perspective, Red October is a software-based encryption and decryption server. The server can be used to encrypt a payload in such a way that no one individual can decrypt it. The encryption of the payload is cryptographically tied to the credentials of the authorized users.

Authorized persons can delegate their credentials to the server for a period of time. The server can decrypt any previously-encrypted payloads as long as the appropriate number of people have delegated their credentials to the server.

This architecture allows Red October to act as a convenient decryption service. Other systems, including CloudFlare’s build system, can use it for decryption and users can delegate their credentials to the server via a simple web interface. All communication with Red October is encrypted with TLS, ensuring that passwords are not sent in the clear.