Struct ipworksencrypt::AESFile

Properties   Methods   Events   Config Settings   Errors  

The AESFile struct implements the AESF file format and uses the XTS-AES standard with 256-bit encryption.

Syntax

ipworksencrypt::AESFile

Remarks

The AESFile component provides robust encryption capabilities to securely store and retrieve data using XTS-AES 256-bit encryption. This component implements the AESF file format, enabling developers to encrypt arbitrary data and serialize it in a standardized manner.

The first step in using the component is to set password property. Specify the input data using input_file or input_message. Next, call encrypt and the component will encrypt the input data and populate output_message, or write to the file specified by output_file with the result.

To change the password of existing file encrypted in AESF format, or to encrypt a file under a different password call change_password. To decrypt data, first set password property. Specify the input data using input_file or input_message. Next, call decrypt and the component will compute the plaintext and populate output_message or write to output_file with the result.

AES File Format

The AES file format used by AES Drive is documented below in detail. All algorithms used by AES Drive are standards and publicly documented.

Each encrypted file consists of a header and the encrypted contents. The header is 144 bytes in length and contains the AES file format version, a checksum of the header bytes, and the encrypted file-specific key and padding length. The original file data is encrypted using XTS-AES with file-specific keys that are derived from a master key for the drive.

Encrypted files are slightly longer than their unencrypted equivalents due to presence of encryption information (from 145 to 656 bytes each, or less than 0.5% on average). This information is stored at both beginning and end of the file, and is composed of the following elements:

Additional Details

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksEncrypt. Due to this, the AESFile struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of AESFile when you have finished using the instance.

Property List

---

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

global_salt property (AESFile Struct)

The additional random data to compute encryption keys.

Syntax

fn global_salt(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 
fn set_global_salt(&self, value : Vec<u8>) ->  Option<IPWorksEncryptError> 
fn set_global_salt_ref(&self, value : &[u8]) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

This is an optional property and will be populated when decrypt is called. When this property is set, it will provide additional randomness to encryption. The length of the salt must be 16 bytes.

The global salt will be used during generation of a key and IV. It can optionally be set before calling the encrypt method. It is recommended to use a unique and randomly generated value. If it is not set, then the struct will generate a value automatically.

Data Type

Vec

input_file property (AESFile Struct)

The file to process.

Syntax

fn input_file(&self ) -> Result<String, IPWorksEncryptError> 
fn set_input_file(&self, value : &str) ->  Option<IPWorksEncryptError> 
fn set_input_file_ref(&self, value : &String) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

This property specifies the file to be processed. Set this property to the full or relative path to the file which will be processed.

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

String

input_message property (AESFile Struct)

The message to process.

Syntax

fn input_message(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 
fn set_input_message(&self, value : Vec<u8>) ->  Option<IPWorksEncryptError> 
fn set_input_message_ref(&self, value : &[u8]) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

This property specifies the message to be processed.

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

Vec

output_file property (AESFile Struct)

The output file when encrypting or decrypting.

Syntax

fn output_file(&self ) -> Result<String, IPWorksEncryptError> 
fn set_output_file(&self, value : &str) ->  Option<IPWorksEncryptError> 
fn set_output_file_ref(&self, value : &String) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

This property specifies the file to which the output will be written when encrypt or decrypt is called. This may be set to an absolute or relative path.

This property is only applicable to encrypt and decrypt.

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

String

output_message property (AESFile Struct)

The output message after processing.

Syntax

fn output_message(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 

Default Value

""

Remarks

This property will be populated with the output from the operation if output_file is not set.

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

This property is read-only.

Data Type

Vec

overwrite property (AESFile Struct)

Indicates whether or not the struct should overwrite files.

Syntax

fn overwrite(&self ) -> Result<bool, IPWorksEncryptError> 
fn set_overwrite(&self, value : bool) ->  Option<IPWorksEncryptError> 

Default Value

false

Remarks

This property indicates whether or not the struct will overwrite output_file. If overwrite is False, an error will be thrown whenever output_file exists before an operation. The default value is False.

Data Type

bool

password property (AESFile Struct)

The password to be used to calculate encryption and decryption keys.

Syntax

fn password(&self ) -> Result<String, IPWorksEncryptError> 
fn set_password(&self, value : &str) ->  Option<IPWorksEncryptError> 
fn set_password_ref(&self, value : &String) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

When this property is set the struct will use PBKDF2 to derive an XTS master key. This must be set before calling encrypt or decrypt.

While there are no strict format or length requirements, it is recommended to use complex passwords. Once set, the password is transformed and never held in plaintext in memory.

Data Type

String

salt property (AESFile Struct)

The additional random data included in the file header.

Syntax

fn salt(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 
fn set_salt(&self, value : Vec<u8>) ->  Option<IPWorksEncryptError> 
fn set_salt_ref(&self, value : &[u8]) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

This property is optional and will be populated when decrypt is called. When this property is set it will provide additional randomness to encryption at the file level. The length of the salt must be 16 bytes.

The salt will be used within each file as input to encryption. It can optionally be set before calling the encrypt method. It is recommended to use a unique and randomly generated value. If it is not set, then the struct will generate a value automatically.

Data Type

Vec

version property (AESFile Struct)

The AESF file format version number.

Syntax

fn version(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_version(&self, value : i32) ->  Option<IPWorksEncryptError> 

Default Value

1

Remarks

This property will be populated when decrypt is called. Possible values are:

Data Type

i32

change_password method (AESFile Struct)

Changes the password for the specified file.

Syntax

fn change_password(&self, path : &str, old_password : &str, new_password : &str) -> Result<(), IPWorksEncryptError>

Remarks

change_password is optional and allows you to update the password used to encrypt an AESF file. This securely changes the password, ensuring that the file remains protected with the new password.

config method (AESFile Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksEncryptError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

decrypt method (AESFile Struct)

Decrypts the data.

Syntax

fn decrypt(&self) -> Result<(), IPWorksEncryptError>

Remarks

This method will decrypt the specified data. The password property is required.

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

encrypt method (AESFile Struct)

Encrypts the data.

Syntax

fn encrypt(&self) -> Result<(), IPWorksEncryptError>

Remarks

This method will encrypt the specified data. The following properties are applicable:

• password (required)
• global_salt
• version

Input and Output Properties

The struct will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• input_file
• input_message

When a valid source is found, the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

reset method (AESFile Struct)

Resets the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksEncryptError>

Remarks

When called, the struct will reset all of its properties to their default values.

on_error event (AESFile Struct)

Fired when information is available about errors during data delivery.

Syntax

// AESFileErrorEventArgs carries the AESFile Error event's parameters.
pub struct AESFileErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// AESFileErrorEvent defines the signature of the AESFile Error event's handler function.
pub trait AESFileErrorEvent {
  fn on_error(&self, sender : AESFile, e : &mut AESFileErrorEventArgs);
}

impl <'a> AESFile<'a> {
  pub fn on_error(&self) -> &'a dyn AESFileErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn AESFileErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_log event (AESFile Struct)

Fires with log information during processing.

Syntax

// AESFileLogEventArgs carries the AESFile Log event's parameters.
pub struct AESFileLogEventArgs {
  fn log_level(&self) -> i32
  fn message(&self) -> &String
  fn log_type(&self) -> &String
}

// AESFileLogEvent defines the signature of the AESFile Log event's handler function.
pub trait AESFileLogEvent {
  fn on_log(&self, sender : AESFile, e : &mut AESFileLogEventArgs);
}

impl <'a> AESFile<'a> {
  pub fn on_log(&self) -> &'a dyn AESFileLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn AESFileLogEvent);
  ...
}

Remarks

This event fires during processing with log information. The level of detail that is logged is controlled via the LogLevel.

LogLevel indicates the level of message. Possible values are:

LogMessage is the log entry.

LogType indicates the type of log. Possible values are:

• "INFO"
• "ENCRYPT"
• "COMPRESS"
• "SIGN"
• "DECRYPT"
• "DECOMPRESS"
• "VERIFY"
• "DEBUG"

on_progress event (AESFile Struct)

Fired as progress is made.

Syntax

// AESFileProgressEventArgs carries the AESFile Progress event's parameters.
pub struct AESFileProgressEventArgs {
  fn data(&self) -> &[u8]
  fn filename(&self) -> &String
  fn bytes_processed(&self) -> i64
  fn percent_processed(&self) -> i32
}

// AESFileProgressEvent defines the signature of the AESFile Progress event's handler function.
pub trait AESFileProgressEvent {
  fn on_progress(&self, sender : AESFile, e : &mut AESFileProgressEventArgs);
}

impl <'a> AESFile<'a> {
  pub fn on_progress(&self) -> &'a dyn AESFileProgressEvent;
  pub fn set_on_progress(&mut self, value : &'a dyn AESFileProgressEvent);
  ...
}

Remarks

This event is fired automatically as data is encrypted or decrypted by the struct. When WriteToProgressEvent is true, the output data is provided through the Data parameter, allowing for it to be streamed out.

Filename contains the name of the file being written. If no file is being written, Filename will contain an empty string, and the output data will be provided exclusively through this event.

The PercentProcessed parameter indicates the current status of the operation.

The BytesProcessed parameter holds the total number of bytes processed so far.

Config Settings (AESFile Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

AESFile Config Settings

Base Config Settings

Trappable Errors (AESFile Struct)

AESFile Errors