xq package

Subpackages

• xq.algorithms package
  • Submodules
  • xq.algorithms.aes_encryption module
    • AESEncryption
      • AESEncryption.add_header_salt()
      • AESEncryption.decrypt()
      • AESEncryption.derive_key()
      • AESEncryption.encrypt()
  • xq.algorithms.encryption module
    • Encryption
      • Encryption.create_file_header()
      • Encryption.decryptFile()
      • Encryption.encryptFile()
      • Encryption.key
      • Encryption.shuffle()
  • xq.algorithms.otp_encryption module
    • OTPEncryption
      • OTPEncryption.decrypt()
      • OTPEncryption.decrypt_chunk()
      • OTPEncryption.decrypt_file_streaming()
      • OTPEncryption.encrypt()
      • OTPEncryption.encrypt_chunk()
      • OTPEncryption.encrypt_file_streaming()
  • Module contents
• xq.api package
  • Subpackages
    • xq.api.manage package
      • Module contents
    • xq.api.subscription package
      • Submodules
      • xq.api.subscription.authentication module
      • xq.api.subscription.key_management module
      • xq.api.subscription.user_management module
      • Module contents
    • xq.api.validation package
      • Submodules
      • xq.api.validation.key_management module
      • Module contents
  • Module contents
    • XQAPI
      • XQAPI.add_contact()
      • XQAPI.add_packet()
      • XQAPI.announce_device()
      • XQAPI.api_delete()
      • XQAPI.api_get()
      • XQAPI.api_patch()
      • XQAPI.api_post()
      • XQAPI.api_put()
      • XQAPI.authorize_alias()
      • XQAPI.authorize_device()
      • XQAPI.authorize_device_cert()
      • XQAPI.authorize_user()
      • XQAPI.code_validate()
      • XQAPI.create_and_store_packet()
      • XQAPI.create_and_store_packets()
      • XQAPI.create_and_store_packets_batch()
      • XQAPI.create_packet()
      • XQAPI.create_usergroup()
      • XQAPI.dashboard_login()
      • XQAPI.dashboard_signup()
      • XQAPI.delete_usergroup()
      • XQAPI.exchange_key()
      • XQAPI.get_communication_by_locator_token()
      • XQAPI.get_entropy()
      • XQAPI.get_packet()
      • XQAPI.get_packets()
      • XQAPI.get_usergroup()
      • XQAPI.grant_users()
      • XQAPI.login_verify()
      • XQAPI.revoke_packet()
      • XQAPI.revoke_users()
      • XQAPI.send_login_link()
      • XQAPI.update_usergroup()
      • XQAPI.validate_access_token()
      • XQAPI.validate_api_key()
• xq.exceptions package
  • Submodules
  • xq.exceptions.configuration module
    • SDKConfigurationException
  • xq.exceptions.encryption module
    • SDKEncryptionException
  • xq.exceptions.xq module
    • XQException
  • Module contents

Submodules

xq.config module

xq.config.configure_env(dotenv_path=None)

Module contents

class xq.XQ(api_key=None, dashboard_api_key=None, locator_key=None)

Bases: object

ALGORITHM_CONFIG = {'CTR': {'prefix': b'.2', 'scheme': 2}, 'GCM': {'prefix': b'.1', 'scheme': 1}, 'OTP': {'prefix': b'.B', 'scheme': 66}}

PREFIX_TO_ALGORITHM = {b'1': 'GCM', b'2': 'CTR', b'B': 'OTP'}

SCHEME_TO_ALGORITHM = {1: 'GCM', 2: 'CTR', 66: 'OTP'}

TOKEN_SIZE = 43

decrypt_auto(encrypted_message: bytes, key: bytes | None = None) → bytes

decrypt a message encrypted with encrypt_auto by parsing the header and retrieving or using provided key

Parameters:

• encrypted_message (bytes) – formatted message from encrypt_auto

• key (bytes, optional) – encryption key to use (with or without prefix), if None will retrieve from packet, defaults to None

Returns:

decrypted plaintext message

Return type:

bytes

decrypt_file(encryptedText: str | bytes | bytearray | BinaryIO, key: bytes | str | None = None, algorithm: str | None = None, out_file: str | PathLike | BinaryIO | None = None, chunk_size: int = 1048576) → bytes | str | None

Decrypt a given file/path/bytes. - algorithm: None → infer from key prefix (.B/.1/.2) - out_file: path/handle → write there; else return bytes.

decrypt_message(encryptedText: bytes, key: bytes, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP')

decrypt a previously encrypted string

Parameters:

• encryptedText (bytes) – encrypted text to decrypt

• key (bytes) – encryption key used to encrypt/decrypt

• algorithm (Algorithms) – algorithm used to encrypt/decrypt

• nonce (bytearray) – nonce provided from original encryption

Returns:

decrypted text

Return type:

str

encrypt_auto(text: str, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP', recipients: ~typing.List[str] | None = None, subject: str = 'message', expires_hours: int = 24, version: int = 1, key: bytes | None = None, locator_token: str | None = None) → bytes

encrypt a string with auto-generated or provided key and store the key packet

Parameters:

• text (str) – string to encrypt

• algorithm (Algorithms, optional) – the encryption algorithm to use, defaults to OTP

• recipients (List[str], optional) – list of recipients who can retrieve the key, defaults to None

• subject (str, optional) – subject/description for the encrypted message, defaults to “message”

• expires_hours (int, optional) – hours until key packet expires, defaults to 24

• version (int, optional) – message format version, defaults to 1

• key (bytes, optional) – encryption key to use (without prefix), if None will auto-generate, defaults to None

• locator_token (str, optional) – pre-existing locator token, if None will create and store packet, defaults to None

Returns:

formatted message: (token_size+version) + locator_token + scheme + ciphertext

Return type:

bytes

encrypt_file(fileObj: str | ~typing.BinaryIO | bytes | bytearray, key: bytes | str, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP', recipients: ~typing.List[str] | None = None, expires_hours: int = 24, out_file: str | ~os.PathLike | ~typing.BinaryIO | None = None, chunk_size: int = 1048576) → bytearray | str | None

Encrypt the contents of a given file/path/bytes.

Behavior: - GCM/OTP: returns bytes (outer header + body). out_file is ignored. - CTR:

• If out_file is provided: streams to out_file, returns None.

• If out_file is None: returns bytes (in-memory).

Parameters:

• fileObj – path (str), file-like object, or bytes/bytearray

• key – encryption key (bytes or str)

• algorithm – “OTP”, “GCM”, or “CTR”

• recipients – who can retrieve the key packet

• expires_hours – packet expiry

• out_file – optional writable binary file-like to stream CTR output into

• chunk_size – chunk size for CTR streaming

Returns:

encrypted payload or None (when CTR+out_file)

encrypt_message(text: str, key: bytes, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP', recipients: ~typing.List[str] | None = None)

encrypt a string

Parameters:

• text (str) – string to encrypt

• key (bytes, defaults to None) – encryption key to use to encrypted text

• algorithm (Algorithms, defaults to OTP) – the encryption algorithm to use

Returns:

ciphertext

Return type:

bytes

expand_key(data: bytes, key: bytes) → bytes

expand a key to the size of the text to be encrypted

Parameters:

• data (bytes) – data you are going to encrypt

• key (bytes, defaults to None) – encryption key you were going to utilize to encrypt the data

Returns:

expanded key to utilize for encryption

Return type:

bytes

generate_key_from_entropy() → bytes

helper method for automatically requesting entropy and shuffling key

Returns:

generated encryption key from entropy

Return type:

bytes

generate_multiple_keys_and_store_packets(count: int = 1, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP', recipients: ~typing.List[str] | None = None, subject: str = 'message', expires_hours: int = 24, packet_type: int | str = 'msg', meta: str | None = None, key_size_bits: int = 128) → List[dict]

generate multiple encryption keys from entropy and store them as packets

Parameters:

• count (int) – number of keys to generate

• algorithm (Algorithms, optional) – the encryption algorithm to use, defaults to OTP

• recipients (List[str], optional) – list of recipients who can retrieve the keys, defaults to None

• subject (str, optional) – subject/description for the key packets, defaults to “message”

• expires_hours (int, optional) – hours until key packets expire, defaults to 24

• packet_type (int | str, optional) – packet type, defaults to “msg”

• meta (str, optional) – additional metadata for the packets, defaults to None

Returns:

list of dicts containing key and locator_token pairs

Return type:

List[dict]

generate_multiple_keys_and_store_packets_database(count: int = 1, algorithm: {'OTP': <class 'xq.algorithms.otp_encryption.OTPEncryption'>, 'AES': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'GCM': <class 'xq.algorithms.aes_encryption.AESEncryption'>, 'CTR': <class 'xq.algorithms.aes_encryption.AESEncryption'>} = 'OTP', recipients: ~typing.List[str] | None = None, metadata_list: list | None = None, expires: int = 1, unit: str = 'days', type: str = 'database', key_size_bits: int = 128) → List[dict]

generate multiple encryption keys from entropy and store them as batch packets with metadata

Parameters:

• count (int) – number of keys to generate

• algorithm (Algorithms, optional) – the encryption algorithm to use, defaults to OTP

• recipients (List[str], optional) – list of recipients who can retrieve the keys, defaults to None

• metadata_list (list, optional) – list of metadata dicts with title and labels for each key, defaults to None

• expires (int, optional) – expiration time (applies to all entries), defaults to 1

• unit (str, optional) – time unit for expiration (applies to all entries), defaults to “days”

• type (str, optional) – packet type (applies to all entries), defaults to “database”

• key_size_bits (int, optional) – size of each key in bits, defaults to 128

Returns:

list of dicts containing key and locator_token pairs

Return type:

List[dict]

parse_file_for_decrypt(input_data)

Parse the XQ outer header and return: (locator:str, name_encrypted:bytes, content_source)

• If input_data is file-like: reads only the header, then rewinds the handle

to position 0 and returns the same handle as content_source. - If input_data is bytes/bytearray: parses in-place and returns the original bytes as content_source.

Header layout: [0:4] token_size+version (LE uint32), token_size=43 [4:47] locator (43 bytes, utf-8) [..] name_size (LE uint32) [..] name_encrypted (name_size bytes) [..] scheme (1 byte if version>0) body starts after header