SecureString Rust Reference Documentation

SecureString

Current Version: 11.6.1

Chilkat.SecureString

Store, append, compare, hash, verify, and securely access sensitive string values.

Chilkat.SecureString holds sensitive text in an encrypted in-memory form while still allowing controlled operations on the value. It can append clear-text strings, append text from a StringBuilder, append another SecureString, load text from a file, return the clear-text value when needed, compare secure strings, mark the value read-only, maintain a hash of the current value, and verify a supplied hash against that maintained value.

Encrypted in-memory value

Store sensitive text in a form that is decrypted only when needed for access, modification, comparison, or hashing.

Append safely

Append clear-text strings, StringBuilder content, or another SecureString; the value is then re-encrypted.

Read-only protection

Set ReadOnly to prevent later modification of the secure string.

Hash maintenance

Set MaintainHash to a supported hash algorithm such as sha256, sha512, sha1, or md5.

Hash output and verification

Retrieve the current hash value in an encoding such as hex or Base64, or verify a supplied encoded hash with VerifyHash.

Compare and access

Compare two secure strings with SecStrEquals, or call Access when the clear-text value is required.

Common pattern: Create a SecureString, load or append the sensitive text, set MaintainHash if later verification is needed, and optionally set ReadOnly after the final value is established. Use Access only at the point where the clear-text string is actually needed, and check LastErrorText if an append, file load, hash, or verification operation fails.
Hash note: VerifyHash depends on MaintainHash having already been set so the object maintains an internal hash for the current secure string value.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::SecureString;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let secure_string = SecureString::new();
// ... the native object is freed when `secure_string` goes out of scope.
pub fn new() -> SecureString

Creates the underlying native Chilkat object (SecureString also implements Default). Every method takes &self, so the object never needs to be declared mut. A SecureString is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for SecureString

The native object is freed when the SecureString is dropped — when it goes out of scope, or explicitly with drop(secure_string). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<SecureString>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match secure_string.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
MaintainHash
// read/write
pub fn maintain_hash(&self) -> String
pub fn set_maintain_hash(&self, value: &str)
Introduced in version 9.5.0.71

If set to the name of a hash algorithm, then a hash of the current string value is maintained. This allows for the hash to be verified via the VerifyHash method. Possible hash algorithm names are sha1, sha256, sha384, sha512, md5, md2, ripemd160, ripemd128,ripemd256, and ripemd320.

top
ReadOnly
// read/write
pub fn read_only(&self) -> bool
pub fn set_read_only(&self, value: bool)
Introduced in version 9.5.0.71

Can be set to true to make this secure string read-only (cannot be modified).

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

Access
pub fn access(&self) -> Result<String>
Introduced in version 9.5.0.71

Returns the clear-text string value.

Returns Err(chilkat::Error) on failure.

top
Append
pub fn append(&self, str: &str) -> Result<()>
Introduced in version 9.5.0.71

Appends a clear-text string to this secure string. The in-memory data will be decrypted, the string will be appended, and then it will be re-encrypted. Can return false if the string has been marked as read-only via the ReadOnly property.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AppendSb
pub fn append_sb(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.71

Appends a clear-text string contained in a StringBuilder to this secure string. The in-memory data will be decrypted, the string will be appended, and then it will be re-encrypted. Can return false if the string has been marked as read-only via the ReadOnly property.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AppendSecure
pub fn append_secure(&self, sec_str: &SecureString) -> Result<()>
Introduced in version 9.5.0.71

Appends the contents of a secure string to this secure string. The in-memory data will be decrypted, the secure string will be appended, and then it will be re-encrypted. Can return false if this string has been marked as read-only via the ReadOnly property.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
HashVal
pub fn hash_val(&self, encoding: &str) -> Result<String>
Introduced in version 9.5.0.71

Returns the hash value for the current value of this secure string. The encoding specifies the encoding to be used. It can be any of the binary encoding algorithms, such as base64, hex, and many more listed at Chilkat Binary Encodings

Returns Err(chilkat::Error) on failure.

More Information and Examples
Example: SecureString.HashVal method
top
LoadFile
pub fn load_file(&self, path: &str, charset: &str) -> Result<()>
Introduced in version 9.5.0.71

Loads the contents of a file into this secure string. The current contents of this object are replaced with the new text from the file.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SecStrEquals
pub fn sec_str_equals(&self, sec_str: &SecureString) -> Result<()>
Introduced in version 9.5.0.71

Returns true if the sec_str equals the contents of this secure string.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
VerifyHash
pub fn verify_hash(&self, hash_val: &str, encoding: &str) -> Result<()>
Introduced in version 9.5.0.71

Verifies the hash_val against the hash value stored for the current value of this secure string. The MaintainHash property must've previously been set for this secure string to maintain an internal hash. The encoding specifies the encoding of the hash_val. It can be any of the binary encoding algorithms, such as base64, hex, and many more listed at Chilkat Binary Encodings

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top