Chilkat v11.5.0 — Secrets Integration

In Chilkat v11.5.0, a new boolean property named EnableSecrets was added to the following classes:

  • Ftp2
  • Http
  • Imap
  • JsonObject
  • MailMan
  • OAuth2
  • Rest
  • SFtp
  • Ssh
  • SshTunnel

What EnableSecrets Does

When EnableSecrets is set to true, certain properties and methods become secrets-aware.

This allows them to accept a secret specification string instead of a literal value. When such a string is provided, Chilkat automatically:

  • Detects the secret specification format
  • Looks up the corresponding secret
  • Retrieves the value from:
    • Windows Credential Manager (Windows), or
    • Apple Keychain (macOS)

Important Characteristics

  • Local-only lookup: Secrets are retrieved only from the local machine’s credential store.
  • Deterministic matching: A given specification matches exactly one secret.
  • No caching: Secrets are looked up each time they are used (not cached in memory).

Secret Specification String Format

A secret specification string has the following format:

!![appName|]service[|domain]|username

Notes:

  • The string must begin with !!
  • Components:
    • appName (optional)
    • service (required)
    • domain (optional)
    • username (required)

These components uniquely identify a secret stored in the local credential manager.

For more information:

Example: Using a Secret for a Password

Without secrets:

ftp.Password = "my_secret_password";

With secrets:

ftp.EnableSecrets = true;
ftp.Password = "!!ftp|ftp.example.com|henry";

In this example, Chilkat retrieves the password associated with:

  • service: ftp
  • domain: ftp.example.com
  • username: henry

Behavior on Failure

Property Assignment

If a secret lookup fails:

  • The property is set to an empty string
  • You can detect failure by checking for a zero-length value

Method Calls

If a secrets-enabled method is used:

  • The return value indicates success or failure

Example

imap.EnableSecrets = true;
bool success = imap.Login("henry@imap.example.com", "!!imap|henry@imap.example.com");

if (!success)
{
    // Handle failure
    // Additional diagnostic details are available in LastErrorText
}

Note: Detailed error information for failed lookups is available via LastErrorText.

Secrets-Aware Properties and Methods

Ftp2

  • Password, HttpProxyPassword, ProxyPassword, SocksPassword

Http

  • AwsAccessKey, AwsEndpoint, AwsRegion, AwsSessionToken, AwsSecretKey
  • ProxyPassword, SocksPassword, Password

Imap

  • HttpProxyPassword, SocksPassword
  • Login, SshAuthenticatePw

JsonObject

  • AddStringAt, AppendString, SetStringAt, SetStringOf
  • UpdateSb, UpdateString

MailMan

  • PopPassword, SmtpPassword, HttpProxyPassword, SocksPassword
  • PopPasswordBase64, SshAuthenticatePw

OAuth2

  • AuthorizationEndpoint, ClientId, ClientSecret, TokenEndpoint

Rest

  • SetAuthBasic

SFtp / Ssh / SshTunnel

  • HttpProxyPassword, SocksPassword
  • AuthenticatePw, AuthenticatePwPk

Storing Secrets Using a Specification String

A new method was added to the Chilkat.Secrets class:

SecretSpecToJson

This method converts a secret specification string into the JSON format used to identify a secret.

That JSON can then be passed to methods such as:

  • Secrets.UpdateSecretStr

to store the secret in the local credential manager.

Example

See: https://www.example-code.com/csharp/ex_Secrets_SecretSpecToJson.asp

Summary

With EnableSecrets, applications can securely reference credentials without embedding sensitive data directly in code or configuration. Instead, secrets are resolved at runtime from the operating system’s secure credential store using a simple and consistent naming format.