SecureString Zig 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

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const secure_string = try chilkat.SecureString.init();
defer secure_string.deinit();

pub fn init() Allocator.Error!SecureString

Creates the underlying native Chilkat object. SecureString is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: SecureString) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkSecureString.HCkSecureString) SecureString

Wraps a handle obtained from the C API (chilkat.c.CkSecureString), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = secure_string.someMethod(allocator, ...) catch |err| {
    const why = try secure_string.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

DebugLogFilePath

// read/write
pub fn getDebugLogFilePath(self: SecureString, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: SecureString, value: [:0]const u8) void

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

SecureString Zig Reference Documentation

SecureString

Current Version: 11.6.1

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

Encrypted in-memory value

Append safely

Read-only protection

Hash maintenance

Hash output and verification

Compare and access

Object Creation

Errors and memory

Properties

DebugLogFilePath

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

MaintainHash

ReadOnly

VerboseLogging

Version

Methods

Access

Append

AppendSb

AppendSecure

HashVal

LoadFile

SecStrEquals

VerifyHash