Table of Contents

crypto

`crypto` encrypts and decrypts `bytes` values or files.

A crypto object starts without a key. Set a key before calling `encrypt`, `decrypt`, `encrypt_file`, or `decrypt_file`.

`crypto` is not cloneable because it holds key state.

Constructor

crypto()

Creates an empty crypto object.

Item Description
Syntax `crypto()`
Arguments none
Returns crypto object

Example: 

c = crypto();
print(c.ready);      // false
print(c.mode);       // none

Properties

Property Type Description
`ready` boolean `true` when a key has been configured.
`mode` string Current key mode: `none`, `raw`, `password`, or `controller`.

Properties are read-only. Use key methods to change the crypto state.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `crypto`.

Methods

clear()

Clears the configured key.

Item Description
Syntax `crypto.clear()`
Arguments none
Returns crypto object

Example: 

c = crypto().key_password('secret');
c.clear();
print(c.ready);      // false

key_raw(key)

Sets a raw key from a `bytes` object.

Argument Type Description
`key` bytes Raw key bytes.

Returns: crypto object.

Example: 

key = bytes();
key.add_string('my raw key');
c = crypto().key_raw(key);

key_password(password)

Derives a key from `password`.

Argument Type Description
`password` string Password text.

Returns: crypto object.

Example: 

c = crypto().key_password('secret');

key_controller(uniqueId)

Sets a controller-based key.

Argument Type Description
`uniqueId` bytes Controller unique ID bytes.

Returns: crypto object.

Example: 

id = bytes();
id.add_string('controller-id');
c = crypto().key_controller(id);

key_export()

Exports the current key as text.

Item Description
Syntax `crypto.key_export()`
Arguments none
Returns string

Example: 

c = crypto().key_password('secret');
key_text = c.key_export();

key_export(filePath)

Exports the current key to a file.

Argument Type Description
`filePath` string Output file path.

Returns: boolean-style number.

Example: 

crypto().key_password('secret').key_export('key.txt');

key_import(keyOrFile)

Imports a key from exported key text or from an existing file path.

Argument Type Description
`keyOrFile` string Exported key text, or path to a file containing exported key text.

Returns: crypto object.

Example: 

c1 = crypto().key_password('secret');
key_text = c1.key_export();
 
c2 = crypto().key_import(key_text);

encrypt(data)

Encrypts a `bytes` object.

Argument Type Description
`data` bytes Plain input bytes.

Returns: encrypted bytes object.

Example: 

plain = bytes();
plain.add_string('secret text');
 
encrypted = crypto().key_password('pw').encrypt(plain);

decrypt(data)

Decrypts a `bytes` object.

Argument Type Description
`data` bytes Encrypted input bytes.

Returns: decrypted bytes object.

Example: 

c = crypto().key_password('pw');
encrypted = c.encrypt(bytes().add_string('ABC'));
plain = c.decrypt(encrypted);

encrypt_file(sourcePath, destinationPath)

Encrypts one file into another file.

Argument Type Description
`sourcePath` string Source file path.
`destinationPath` string Destination file path.

Returns: boolean-style number.

Example: 

c = crypto().key_password('pw');
c.encrypt_file('plain.bin', 'plain.bin.crp');

decrypt_file(sourcePath, destinationPath)

Decrypts one file into another file.

Argument Type Description
`sourcePath` string Source encrypted file path.
`destinationPath` string Destination file path.

Returns: boolean-style number.

Example: 

c = crypto().key_password('pw');
c.decrypt_file('plain.bin.crp', 'plain_restored.bin');

Previous: Utils

Next: timer