---
product: Chilkat
product_version: 11.7.0
language: wc
language_label: Unicode C
class: SecureString
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wc_CkSecureStringWRef.html
---
# Chilkat SecureString — Unicode C — v11.7.0

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

```c
HCkSecureStringW instance = CkSecureStringW_Create();
// ...
CkSecureStringW_Dispose(instance);
```

`HCkSecureStringW CkSecureStringW_Create(void);`

Creates an instance of the HCkSecureStringW object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkSecureStringW_Dispose(HCkSecureStringW handle);`

Objects created by calling CkSecureStringW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkSecureStringW_Dispose.

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 Unicode C.

## 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` | `void CkSecureStringW_getDebugLogFilePath(HCkSecureStringW cHandle, HCkString retval); void CkSecureStringW_putDebugLogFilePath(HCkSecureStringW cHandle, const wchar_t *newVal); const wchar_t *CkSecureStringW_debugLogFilePath(HCkSecureStringW cHandle);` | 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` | `void CkSecureStringW_getLastErrorHtml(HCkSecureStringW cHandle, HCkString retval); const wchar_t *CkSecureStringW_lastErrorHtml(HCkSecureStringW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkSecureStringW_getLastErrorText(HCkSecureStringW cHandle, HCkString retval); const wchar_t *CkSecureStringW_lastErrorText(HCkSecureStringW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkSecureStringW_getLastErrorXml(HCkSecureStringW cHandle, HCkString retval); const wchar_t *CkSecureStringW_lastErrorXml(HCkSecureStringW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkSecureStringW_getLastMethodSuccess(HCkSecureStringW cHandle); void CkSecureStringW_putLastMethodSuccess(HCkSecureStringW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkSecureStringW_getVerboseLogging(HCkSecureStringW cHandle); void CkSecureStringW_putVerboseLogging(HCkSecureStringW cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkSecureStringW_getVersion(HCkSecureStringW cHandle, HCkString retval); const wchar_t *CkSecureStringW_version(HCkSecureStringW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaintainHash` | property, read/write | `void CkSecureStringW_getMaintainHash(HCkSecureStringW cHandle, HCkString retval); void CkSecureStringW_putMaintainHash(HCkSecureStringW cHandle, const wchar_t *newVal); const wchar_t *CkSecureStringW_maintainHash(HCkSecureStringW cHandle);` |
| `ReadOnly` | property, read/write | `BOOL CkSecureStringW_getReadOnly(HCkSecureStringW cHandle); void CkSecureStringW_putReadOnly(HCkSecureStringW cHandle, BOOL newVal);` |
| `Access` | method | `BOOL CkSecureStringW_Access(HCkSecureStringW cHandle, const wchar_t *outStr); const wchar_t *CkSecureStringW_access(HCkSecureStringW cHandle);` |
| `Append` | method | `BOOL CkSecureStringW_Append(HCkSecureStringW cHandle, const wchar_t *str);` |
| `AppendSb` | method | `BOOL CkSecureStringW_AppendSb(HCkSecureStringW cHandle, HCkStringBuilderW sb);` |
| `AppendSecure` | method | `BOOL CkSecureStringW_AppendSecure(HCkSecureStringW cHandle, HCkSecureStringW secStr);` |
| `HashVal` | method | `BOOL CkSecureStringW_HashVal(HCkSecureStringW cHandle, const wchar_t *encoding, const wchar_t *outStr); const wchar_t *CkSecureStringW_hashVal(HCkSecureStringW cHandle, const wchar_t *encoding);` |
| `LoadFile` | method | `BOOL CkSecureStringW_LoadFile(HCkSecureStringW cHandle, const wchar_t *path, const wchar_t *charset);` |
| `SecStrEquals` | method | `BOOL CkSecureStringW_SecStrEquals(HCkSecureStringW cHandle, HCkSecureStringW secStr);` |
| `VerifyHash` | method | `BOOL CkSecureStringW_VerifyHash(HCkSecureStringW cHandle, const wchar_t *hashVal, const wchar_t *encoding);` |

## Properties

### SecureString.MaintainHash

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

```c
void CkSecureStringW_getMaintainHash(HCkSecureStringW cHandle, HCkString retval);
void CkSecureStringW_putMaintainHash(HCkSecureStringW cHandle, const wchar_t *newVal);
const wchar_t *CkSecureStringW_maintainHash(HCkSecureStringW cHandle);
```

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

```c
BOOL CkSecureStringW_getReadOnly(HCkSecureStringW cHandle);
void CkSecureStringW_putReadOnly(HCkSecureStringW cHandle, BOOL newVal);
```

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

## Methods

### SecureString.Access

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

```c
BOOL CkSecureStringW_Access(HCkSecureStringW cHandle, const wchar_t *outStr);
const wchar_t *CkSecureStringW_access(HCkSecureStringW cHandle);
```

Returns the clear-text string value.

Returns TRUE for success, FALSE for failure.

### SecureString.Append

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

```c
BOOL CkSecureStringW_Append(HCkSecureStringW cHandle, const wchar_t *str);
```

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

```c
BOOL CkSecureStringW_AppendSb(HCkSecureStringW cHandle, HCkStringBuilderW sb);
```

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

```c
BOOL CkSecureStringW_AppendSecure(HCkSecureStringW cHandle, HCkSecureStringW secStr);
```

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

```c
BOOL CkSecureStringW_HashVal(HCkSecureStringW cHandle, const wchar_t *encoding, const wchar_t *outStr);
const wchar_t *CkSecureStringW_hashVal(HCkSecureStringW cHandle, const wchar_t *encoding);
```

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 · wc · SecureString · LoadFile · method · since 9.5.0.71`

```c
BOOL CkSecureStringW_LoadFile(HCkSecureStringW cHandle, const wchar_t *path, const wchar_t *charset);
```

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

```c
BOOL CkSecureStringW_SecStrEquals(HCkSecureStringW cHandle, HCkSecureStringW secStr);
```

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

```c
BOOL CkSecureStringW_VerifyHash(HCkSecureStringW cHandle, const wchar_t *hashVal, const wchar_t *encoding);
```

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