---
product: Chilkat
product_version: 11.7.0
language: delphidll
language_label: Delphi DLL
class: SecureString
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/dd_CkSecureStringRef.html
---
# Chilkat SecureString — Delphi DLL — v11.7.0

> Chilkat 11.7.0 · language=delphidll · 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/delphidll/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/Dispose**

```pascal
var
myObject: HCkSecureString;

begin
myObject := CkSecureString_Create();

// ...

CkSecureString_Dispose(myObject);
end;
```

`function CkSecureString_Create: HCkSecureString; stdcall;`

Creates an instance of the HCkSecureString object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

`procedure CkSecureString_Dispose(handle: HCkSecureString); stdcall;`

Objects created by calling CkSecureString_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

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 Delphi DLL.

## 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` | `procedure CkSecureString_getDebugLogFilePath(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; procedure CkSecureString_putDebugLogFilePath(objHandle: HCkSecureString; newPropVal: PWideChar); stdcall; function CkSecureString__debugLogFilePath(objHandle: HCkSecureString): PWideChar; stdcall;` | 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` | `procedure CkSecureString_getLastErrorHtml(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; function CkSecureString__lastErrorHtml(objHandle: HCkSecureString): PWideChar; stdcall;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `procedure CkSecureString_getLastErrorText(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; function CkSecureString__lastErrorText(objHandle: HCkSecureString): PWideChar; stdcall;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `procedure CkSecureString_getLastErrorXml(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; function CkSecureString__lastErrorXml(objHandle: HCkSecureString): PWideChar; stdcall;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `function CkSecureString_getLastMethodSuccess(objHandle: HCkSecureString): wordbool; stdcall; procedure CkSecureString_putLastMethodSuccess(objHandle: HCkSecureString; newPropVal: wordbool); stdcall;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `function CkSecureString_getVerboseLogging(objHandle: HCkSecureString): wordbool; stdcall; procedure CkSecureString_putVerboseLogging(objHandle: HCkSecureString; newPropVal: wordbool); stdcall;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `procedure CkSecureString_getVersion(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; function CkSecureString__version(objHandle: HCkSecureString): PWideChar; stdcall;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaintainHash` | property, read/write | `procedure CkSecureString_getMaintainHash(objHandle: HCkSecureString; outPropVal: HCkString); stdcall; procedure CkSecureString_putMaintainHash(objHandle: HCkSecureString; newPropVal: PWideChar); stdcall; function CkSecureString__maintainHash(objHandle: HCkSecureString): PWideChar; stdcall;` |
| `ReadOnly` | property, read/write | `function CkSecureString_getReadOnly(objHandle: HCkSecureString): wordbool; stdcall; procedure CkSecureString_putReadOnly(objHandle: HCkSecureString; newPropVal: wordbool); stdcall;` |
| `Access` | method | `function CkSecureString_Access(objHandle: HCkSecureString;     outStr: HCkString): wordbool; stdcall; function CkSecureString__access(objHandle: HCkSecureString): PWideChar; stdcall;` |
| `Append` | method | `function CkSecureString_Append(objHandle: HCkSecureString;     str: PWideChar): wordbool; stdcall;` |
| `AppendSb` | method | `function CkSecureString_AppendSb(objHandle: HCkSecureString;     sb: HCkStringBuilder): wordbool; stdcall;` |
| `AppendSecure` | method | `function CkSecureString_AppendSecure(objHandle: HCkSecureString;     secStr: HCkSecureString): wordbool; stdcall;` |
| `HashVal` | method | `function CkSecureString_HashVal(objHandle: HCkSecureString;     encoding: PWideChar;     outStr: HCkString): wordbool; stdcall; function CkSecureString__hashVal(objHandle: HCkSecureString;     encoding: PWideChar): PWideChar; stdcall;` |
| `LoadFile` | method | `function CkSecureString_LoadFile(objHandle: HCkSecureString;     path: PWideChar;     charset: PWideChar): wordbool; stdcall;` |
| `SecStrEquals` | method | `function CkSecureString_SecStrEquals(objHandle: HCkSecureString;     secStr: HCkSecureString): wordbool; stdcall;` |
| `VerifyHash` | method | `function CkSecureString_VerifyHash(objHandle: HCkSecureString;     hashVal: PWideChar;     encoding: PWideChar): wordbool; stdcall;` |

## Properties

### SecureString.MaintainHash

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

```pascal
procedure CkSecureString_getMaintainHash(objHandle: HCkSecureString; outPropVal: HCkString); stdcall;
procedure CkSecureString_putMaintainHash(objHandle: HCkSecureString; newPropVal: PWideChar); stdcall;
function CkSecureString__maintainHash(objHandle: HCkSecureString): PWideChar; stdcall;
```

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 · delphidll · SecureString · ReadOnly · property · read/write · since 9.5.0.71`

```pascal
function CkSecureString_getReadOnly(objHandle: HCkSecureString): wordbool; stdcall;
procedure CkSecureString_putReadOnly(objHandle: HCkSecureString; newPropVal: wordbool); stdcall;
```

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

## Methods

### SecureString.Access

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

```pascal
function CkSecureString_Access(objHandle: HCkSecureString;
    outStr: HCkString): wordbool; stdcall;
function CkSecureString__access(objHandle: HCkSecureString): PWideChar; stdcall;
```

Returns the clear-text string value.

Returns True for success, False for failure.

See the notes about [PWideChar memory ownership and validity](https://www.chilkatsoft.com/delphi_pwidechar.asp).

### SecureString.Append

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

```pascal
function CkSecureString_Append(objHandle: HCkSecureString;
    str: PWideChar): wordbool; stdcall;
```

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 · delphidll · SecureString · AppendSb · method · since 9.5.0.71`

```pascal
function CkSecureString_AppendSb(objHandle: HCkSecureString;
    sb: HCkStringBuilder): wordbool; stdcall;
```

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 · delphidll · SecureString · AppendSecure · method · since 9.5.0.71`

```pascal
function CkSecureString_AppendSecure(objHandle: HCkSecureString;
    secStr: HCkSecureString): wordbool; stdcall;
```

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 · delphidll · SecureString · HashVal · method · since 9.5.0.71`

```pascal
function CkSecureString_HashVal(objHandle: HCkSecureString;
    encoding: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkSecureString__hashVal(objHandle: HCkSecureString;
    encoding: PWideChar): PWideChar; stdcall;
```

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.

See the notes about [PWideChar memory ownership and validity](https://www.chilkatsoft.com/delphi_pwidechar.asp).

### SecureString.LoadFile

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

```pascal
function CkSecureString_LoadFile(objHandle: HCkSecureString;
    path: PWideChar;
    charset: PWideChar): wordbool; stdcall;
```

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 · delphidll · SecureString · SecStrEquals · method · since 9.5.0.71`

```pascal
function CkSecureString_SecStrEquals(objHandle: HCkSecureString;
    secStr: HCkSecureString): wordbool; stdcall;
```

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 · delphidll · SecureString · VerifyHash · method · since 9.5.0.71`

```pascal
function CkSecureString_VerifyHash(objHandle: HCkSecureString;
    hashVal: PWideChar;
    encoding: PWideChar): wordbool; stdcall;
```

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/delphidll/classes/StringBuilder.md)