---
product: Chilkat
product_version: 11.7.0
language: cpp
language_label: C++
class: SecureString
class_name: CkSecureString
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/vcCkSecureStringRef.html
---
# Chilkat SecureString — C++ — v11.7.0

> Chilkat 11.7.0 · language=cpp · class=SecureString (CkSecureString)
> 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/cpp/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

**Object Creation**

```cpp
// Local variable on the stack
CkSecureString obj;

// Dynamically allocate/delete
CkSecureString *pObj = new CkSecureString();
// ...
delete pObj;
```

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

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## 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 get_DebugLogFilePath(CkString &str); const char *debugLogFilePath(void); void put_DebugLogFilePath(const char *newVal);` | 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 get_LastErrorHtml(CkString &str); const char *lastErrorHtml(void);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void get_LastErrorText(CkString &str); const char *lastErrorText(void);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void get_LastErrorXml(CkString &str); const char *lastErrorXml(void);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `bool get_LastMethodSuccess(void); void put_LastMethodSuccess(bool newVal);` | read/write | Indicates the success or failure of the most recent method call: `true` means success, `false` means failure. |
| `Utf8` | `bool get_Utf8(void); void put_Utf8(bool newVal);` | read/write | When set to `true`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `bool get_VerboseLogging(void); void put_VerboseLogging(bool newVal);` | read/write | If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void get_Version(CkString &str); const char *version(void);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaintainHash` | property, read/write | `void get_MaintainHash(CkString &str); const char *maintainHash(void); void put_MaintainHash(const char *newVal);` |
| `ReadOnly` | property, read/write | `bool get_ReadOnly(void); void put_ReadOnly(bool newVal);` |
| `Access` | method | `bool Access(CkString &outStr); const char *access(void);` |
| `Append` | method | `bool Append(const char *str);` |
| `AppendSb` | method | `bool AppendSb(CkStringBuilder &sb);` |
| `AppendSecure` | method | `bool AppendSecure(CkSecureString &secStr);` |
| `HashVal` | method | `bool HashVal(const char *encoding, CkString &outStr); const char *hashVal(const char *encoding);` |
| `LoadFile` | method | `bool LoadFile(const char *path, const char *charset);` |
| `SecStrEquals` | method | `bool SecStrEquals(CkSecureString &secStr);` |
| `VerifyHash` | method | `bool VerifyHash(const char *hashVal, const char *encoding);` |

## Properties

### SecureString.MaintainHash

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

```cpp
void get_MaintainHash(CkString &str);

const char *maintainHash(void);

void put_MaintainHash(const char *newVal);
```

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

```cpp
bool get_ReadOnly(void);

void put_ReadOnly(bool newVal);
```

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

## Methods

### SecureString.Access

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

```cpp
bool Access(CkString &outStr);

const char *access(void);
```

Returns the clear-text string value.

Returns true for success, false for failure.

### SecureString.Append

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

```cpp
bool Append(const char *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 · cpp · SecureString · AppendSb · method · since 9.5.0.71`

```cpp
bool AppendSb(CkStringBuilder &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 · cpp · SecureString · AppendSecure · method · since 9.5.0.71`

```cpp
bool AppendSecure(CkSecureString &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 · cpp · SecureString · HashVal · method · since 9.5.0.71`

```cpp
bool HashVal(const char *encoding, CkString &outStr);

const char *hashVal(const char *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 · cpp · SecureString · LoadFile · method · since 9.5.0.71`

```cpp
bool LoadFile(const char *path, const char *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 · cpp · SecureString · SecStrEquals · method · since 9.5.0.71`

```cpp
bool SecStrEquals(CkSecureString &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 · cpp · SecureString · VerifyHash · method · since 9.5.0.71`

```cpp
bool VerifyHash(const char *hashVal, const char *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/cpp/classes/StringBuilder.md)