---
product: Chilkat
product_version: 11.7.0
language: pascal
language_label: Lazarus Pascal
class: SecureString
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/pascal_SecureStringRef.html
---
# Chilkat SecureString — Lazarus Pascal — v11.7.0

> Chilkat 11.7.0 · language=pascal · class=SecureString
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/SecureString.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`.

## Purpose

**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, unlocking and error handling

**Create / Free**

```pascal
uses
  Chilkat.SecureString;

var
  obj: TSecureString;
begin
  obj := TSecureString.Create;
  try
    if not obj.IsValid then
      raise Exception.Create('Failed to create a TSecureString instance.');

    // ... use obj ...

  finally
    obj.Free;
  end;
end;
```

`constructor Create;`

Allocates the underlying CkSecureString object and returns a new TSecureString instance. Simply adding **Chilkat.SecureString** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed).

`destructor Destroy; override;`

Every TSecureString created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkSecureString handle. A native (unmanaged) memory leak occurs if the object is never freed.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaintainHash` | property, read/write | `property MaintainHash: string read GetMaintainHash write SetMaintainHash;` |
| `ReadOnly` | property, read/write | `property ReadOnly: Boolean read GetReadOnly write SetReadOnly;` |
| `Access` | method | `function Access: string;` |
| `Append` | method | `function Append(const str: string): Boolean;` |
| `AppendSb` | method | `// sb is a TStringBuilder object. function AppendSb(sb: TChilkatBase): Boolean;` |
| `AppendSecure` | method | `// secStr is a TSecureString object. function AppendSecure(secStr: TChilkatBase): Boolean;` |
| `HashVal` | method | `function HashVal(const encoding: string): string;` |
| `LoadFile` | method | `function LoadFile(const path: string;     const charset: string): Boolean;` |
| `SecStrEquals` | method | `// secStr is a TSecureString object. function SecStrEquals(secStr: TChilkatBase): Boolean;` |
| `VerifyHash` | method | `function VerifyHash(const hashVal: string;     const encoding: string): Boolean;` |

## Properties

### SecureString.MaintainHash

`Chilkat 11.7.0 · pascal · SecureString · MaintainHash · property · read/write · since 9.5.0.71`

```pascal
property MaintainHash: string read GetMaintainHash write SetMaintainHash;
```

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`.

### SecureString.ReadOnly

`Chilkat 11.7.0 · pascal · SecureString · ReadOnly · property · read/write · since 9.5.0.71`

```pascal
property ReadOnly: Boolean read GetReadOnly write SetReadOnly;
```

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

## Methods

### SecureString.Access

`Chilkat 11.7.0 · pascal · SecureString · Access · method · since 9.5.0.71`

```pascal
function  Access: string;
```

Returns the clear-text string value.

Returns True for success, False for failure.

### SecureString.Append

`Chilkat 11.7.0 · pascal · SecureString · Append · method · since 9.5.0.71`

```pascal
function  Append(const str: string): Boolean;
```

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 True for success, False for failure.

### SecureString.AppendSb

`Chilkat 11.7.0 · pascal · SecureString · AppendSb · method · since 9.5.0.71`

```pascal
// sb is a TStringBuilder object.

function  AppendSb(sb: TChilkatBase): Boolean;
```

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 True for success, False for failure.

### SecureString.AppendSecure

`Chilkat 11.7.0 · pascal · SecureString · AppendSecure · method · since 9.5.0.71`

```pascal
// secStr is a TSecureString object.

function  AppendSecure(secStr: TChilkatBase): Boolean;
```

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 True for success, False for failure.

### SecureString.HashVal

`Chilkat 11.7.0 · pascal · SecureString · HashVal · method · since 9.5.0.71`

```pascal
function  HashVal(const encoding: string): string;
```

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](https://www.chilkatsoft.com/binary_encodings.asp)

Returns True for success, False for failure.

### SecureString.LoadFile

`Chilkat 11.7.0 · pascal · SecureString · LoadFile · method · since 9.5.0.71`

```pascal
function  LoadFile(const path: string;
    const charset: string): Boolean;
```

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 True for success, False for failure.

### SecureString.SecStrEquals

`Chilkat 11.7.0 · pascal · SecureString · SecStrEquals · method · since 9.5.0.71`

```pascal
// secStr is a TSecureString object.

function  SecStrEquals(secStr: TChilkatBase): Boolean;
```

Returns `True` if the `secStr` equals the contents of this secure string.

Returns True for success, False for failure.

### SecureString.VerifyHash

`Chilkat 11.7.0 · pascal · SecureString · VerifyHash · method · since 9.5.0.71`

```pascal
function  VerifyHash(const hashVal: string;
    const encoding: string): Boolean;
```

Verifies the `hashVal` 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 `hashVal`. It can be any of the binary encoding algorithms, such as `base64`, `hex`, and many more listed at [Chilkat Binary Encodings](https://www.chilkatsoft.com/binary_encodings.asp)

Returns True for success, False for failure.

## Related classes

[`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringBuilder.md)