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

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

```csharp
Chilkat.SecureString obj = new Chilkat.SecureString();
```

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

Minimal complete program:

```csharp
// Required once per process. Any string unlocks a 30-day trial; use your purchased code in production.
Chilkat.Global glob = new Chilkat.Global();
if (!glob.UnlockBundle("Anything for 30-day trial"))
{
    Console.WriteLine(glob.LastErrorText);
    return;
}

Chilkat.SecureString secureString = new Chilkat.SecureString();

bool success = secureString.Append("<str>");
if (!success)
{
    Console.WriteLine(secureString.LastErrorText);   // full diagnostic of what went wrong
    return;
}
```

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` | `public string DebugLogFilePath {get; set; }` | 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` | `public string LastErrorHtml {get; }` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `public string LastErrorText {get; }` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `public string LastErrorXml {get; }` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `public bool LastMethodSuccess {get; set; }` | read/write | Indicates the success or failure of the most recent method call: `true` means success, `false` means failure. |
| `VerboseLogging` | `public bool VerboseLogging {get; set; }` | read/write | If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `public string Version {get; }` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaintainHash` | property, read/write | `public string MaintainHash {get; set; }` |
| `ReadOnly` | property, read/write | `public bool ReadOnly {get; set; }` |
| `Access` | method | `public string Access();` |
| `Append` | method | `public bool Append(string str);` |
| `AppendSb` | method | `public bool AppendSb(StringBuilder sb);` |
| `AppendSecure` | method | `public bool AppendSecure(SecureString secStr);` |
| `HashVal` | method | `public string HashVal(string encoding);` |
| `LoadFile` | method | `public bool LoadFile(string path, string charset);` |
| `SecStrEquals` | method | `public bool SecStrEquals(SecureString secStr);` |
| `VerifyHash` | method | `public bool VerifyHash(string hashVal, string encoding);` |

## Properties

### SecureString.MaintainHash

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

```csharp
public string MaintainHash {get; set; }
```

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

```csharp
public bool ReadOnly {get; set; }
```

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

## Methods

### SecureString.Access

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

```csharp
public string Access();
```

Returns the clear-text string value.

Returns `null` on failure

### SecureString.Append

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

```csharp
public bool Append(string 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 · csharp · SecureString · AppendSb · method · since 9.5.0.71`

```csharp
public bool AppendSb(StringBuilder 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 · csharp · SecureString · AppendSecure · method · since 9.5.0.71`

```csharp
public bool AppendSecure(SecureString 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 · csharp · SecureString · HashVal · method · since 9.5.0.71`

```csharp
public string HashVal(string 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 `null` on failure

### SecureString.LoadFile

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

```csharp
public bool LoadFile(string path, string 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 · csharp · SecureString · SecStrEquals · method · since 9.5.0.71`

```csharp
public bool SecStrEquals(SecureString 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 · csharp · SecureString · VerifyHash · method · since 9.5.0.71`

```csharp
public bool VerifyHash(string hashVal, string 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/csharp/classes/StringBuilder.md)