Chilkat.Secrets Class Overview

Chilkat.Secrets provides a common API for storing, retrieving, listing, and deleting secrets from local and cloud-based secret managers. It supports string, binary, and JSON secrets, optional compression, Windows Credential Manager / Apple Keychain storage, cloud secret managers, and in-memory secrets.

What the Class Is Used For

Use Chilkat.Secrets when an application needs to store sensitive values such as passwords, API keys, OAuth credentials, access tokens, unlock codes, certificates, private configuration values, or JSON credential objects. The class provides a consistent interface for multiple secret locations, allowing code to work with local, cloud, or in-memory secret storage.

Multiple Secret Locations Store secrets in the local manager, AWS Secrets Manager, Azure Key Vault, IBM Cloud Secrets Manager, Oracle Cloud Secrets, Doppler, or memory.
String, Binary, and JSON Secrets Use separate methods for string secrets, binary secrets, and JSON secrets.
Optional Compression Enable Compression to store secret contents in compressed form.
Bootstrap Support Store local bootstrap credentials used to authenticate to cloud-based secret managers.

Typical Workflow

  1. Create a Chilkat.Secrets object.
  2. Set Location to the desired secret manager, such as local_manager, aws_secrets_manager, azure_key_vault, or memory.
  3. Optionally enable Compression if the secret content should be stored compressed.
  4. Build a JsonObject that identifies the secret.
  5. Create or update the secret with UpdateSecretStr, UpdateSecretSb, UpdateSecretBd, or UpdateSecretJson.
  6. Retrieve the secret later with GetSecretStr, GetSecretSb, GetSecretBd, or GetSecretJson.
  7. Use ListSecrets to discover matching secrets, or DeleteSecret to remove a secret.
  8. If a method fails or behaves unexpectedly, inspect LastErrorText.

Supported Secret Locations

Location Value Secret Store Notes
local_manager Windows Credential Manager, or Apple Keychain on macOS and iOS. This is the default location. On Linux and Android, local_manager behaves the same as memory.
aws_secrets_manager AWS Secrets Manager Use for AWS-hosted secrets.
azure_key_vault Azure Key Vault Use for Azure-hosted secrets.
ibm_cloud IBM Cloud Secrets Manager Use for IBM Cloud-hosted secrets.
oracle_cloud Oracle Cloud Secrets Use for Oracle Cloud-hosted secrets.
doppler Doppler Secrets Use for Doppler-managed secrets.
memory In-memory secrets Secrets exist only in memory and are not persisted to an external manager.
Platform note: The local secret manager maps to Windows Credential Manager on Windows and Apple Keychain on macOS and iOS. It is not yet a true local-manager option on Linux or Android, where it behaves like memory.

Core Concepts

Concept Meaning Important Members
Secret Location Determines where secrets are stored and retrieved. Location
Secret Identifier A JsonObject that identifies the secret by the fields required for the selected location. GetSecret*, UpdateSecret*, DeleteSecret
Secret Content The value stored in the secret manager. It may be a string, binary data, or JSON. UpdateSecretStr, UpdateSecretBd, UpdateSecretJson
Compression Optional compressed storage of the secret contents. Compression
Auto Splitting Windows-specific handling for local-manager secrets larger than the Windows Credential Manager per-secret size limit. AutoSplit
Bootstrap Secret Local credentials used to authenticate to a cloud-based secrets manager. SetBootstrapSecret

Properties

Property Default Purpose and Guidance
Location local_manager Selects where secrets are stored. Supported values include local_manager, aws_secrets_manager, azure_key_vault, ibm_cloud, oracle_cloud, doppler, and memory.
Compression false If true, the contents of the secret are stored compressed.
AutoSplit true Specific to local_manager secrets on Windows. If a secret exceeds the Windows Credential Manager limit of 2560 bytes, it is automatically compressed and split when created or updated, and automatically recomposed when retrieved. A secret can be split into a maximum of 10 parts.
UncommonOptions Empty string Catch-all property for uncommon needs. It should typically remain empty.
LastErrorText Read-only diagnostic text Provides diagnostic information for the last method or property access. Check this when a method fails or behaves unexpectedly.

Creating and Updating Secrets

Method Secret Type Input Behavior
UpdateSecretStr String JsonObject identifier and string content. Creates the string secret if it does not exist, or updates it if it already exists.
UpdateSecretSb String JsonObject identifier and StringBuilder content. Creates or updates a string secret from a StringBuilder.
UpdateSecretBd Binary JsonObject identifier and BinData content. Creates or updates a binary secret.
UpdateSecretJson JSON JsonObject identifier and JsonObject secret content. Creates or updates a JSON secret.
Chilkat unlock code note: Starting in Chilkat v11.3.0, if service = "Chilkat" and username = "unlock_code", then the secret can be stored and retrieved without Chilkat being unlocked. This allows the Chilkat unlock code itself to be persisted to a secrets manager.

Retrieving Secrets

Method Secret Type Output Use When
GetSecretStr String Returns the string content directly. Use for simple string secrets such as passwords, tokens, or unlock codes.
GetSecretSb String Places the string content in a StringBuilder. Use when the secret should be received into a mutable text buffer.
GetSecretBd Binary Places binary secret content in a BinData object. Use for binary credentials, keys, certificates, or other non-text data.
GetSecretJson JSON Places JSON secret content in a JsonObject. Use for structured credentials or configuration stored as JSON.

Listing, Deleting, and Secret Specifications

Method Purpose Important Details
ListSecrets Lists secrets matching wildcarded or exact values. The query is supplied in a JsonObject, and the matching results are returned in another JsonObject.
DeleteSecret Deletes a secret. Cloud secrets managers will typically disable the secret and schedule it for deletion after some number of days.
SecretSpecToJson Converts a compact secret specification string to JSON. A secret specification string is formatted as !!part1|part2|part3|part4, where parts 3 and 4 are optional.
Secret identifier format: Most operations identify the target secret with a JsonObject. Use SecretSpecToJson when you want to convert a compact string form into the JSON identifier form expected by the API.

Bootstrap Secrets for Cloud Managers

Accessing a cloud-based secrets manager requires authentication credentials. Those credentials cannot be stored in the same cloud secrets manager before the application can authenticate to it. A bootstrap secret solves this problem by storing the cloud-manager authentication credentials locally, such as in Windows Credential Manager or Apple Keychain.

Method Purpose Inputs
SetBootstrapSecret Stores the authentication credentials needed to access a cloud-based secrets manager. jsonId contains the name of the bootstrap secret. secretContent contains the bootstrap secret content.
Practical role: Bootstrap secrets provide the local starting point for authenticating to cloud secret managers such as AWS Secrets Manager, Azure Key Vault, IBM Cloud Secrets Manager, Oracle Cloud Secrets, or Doppler.

Method Summary by Category

Category Members Purpose
Location and storage options Location, Compression, AutoSplit, UncommonOptions Choose the secret store and configure storage behavior.
Create or update secrets UpdateSecretStr, UpdateSecretSb, UpdateSecretBd, UpdateSecretJson Store string, binary, or JSON secret content.
Retrieve secrets GetSecretStr, GetSecretSb, GetSecretBd, GetSecretJson Fetch string, binary, or JSON secret content.
Discover and remove secrets ListSecrets, DeleteSecret List matching secrets or delete a secret.
Secret specification conversion SecretSpecToJson Convert a compact !!part1|part2|part3|part4 secret spec into JSON.
Cloud-manager bootstrap SetBootstrapSecret Store local credentials used to authenticate to cloud-based secret managers.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected behavior.

Security Notes

Item Security Guidance
Secret content Treat retrieved secret values as sensitive. Avoid logging them, exposing them in error messages, or keeping them in memory longer than necessary.
Bootstrap secrets Bootstrap credentials unlock access to cloud-based secret managers. Store them only in an appropriate local secure store such as Windows Credential Manager or Apple Keychain.
memory location In-memory secrets are not persisted and are useful for temporary secrets, but they do not provide durable storage.
Delete behavior Cloud managers may disable and schedule a secret for deletion rather than immediately erasing it.
Diagnostics Use LastErrorText for troubleshooting, but avoid writing sensitive secret values to logs.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Secret cannot be found Location, GetSecretStr, GetSecretJson, GetSecretBd Confirm the selected location and the fields in the secret identifier JSON.
Unexpected local-manager behavior on Linux or Android Location On Linux and Android, local_manager behaves the same as memory.
Large Windows local secret fails or is split AutoSplit Windows Credential Manager supports a maximum of 2560 bytes per secret. With AutoSplit enabled, larger secrets are compressed, split, and later recomposed automatically, up to 10 parts.
Wrong secret data type GetSecretStr, GetSecretBd, GetSecretJson Use the retrieval method that matches how the secret was stored: string, binary, or JSON.
Cloud manager authentication fails SetBootstrapSecret Confirm that the bootstrap secret exists locally and contains the credentials needed to authenticate to the cloud-based secrets manager.
Secret deletion does not appear immediate DeleteSecret Cloud secrets managers may disable the secret and schedule deletion for a later time.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected store, retrieve, list, delete, bootstrap, or conversion behavior.

Common Pitfalls

Pitfall Better Approach
Assuming local_manager is persistent on all platforms. On Windows it uses Credential Manager, and on macOS/iOS it uses Keychain. On Linux and Android it behaves like memory.
Storing cloud-manager login credentials inside the cloud manager itself. Use a bootstrap secret stored locally to authenticate to the cloud-based secrets manager.
Retrieving a JSON secret with the string or binary method. Use GetSecretJson for JSON secrets, GetSecretStr or GetSecretSb for string secrets, and GetSecretBd for binary secrets.
Ignoring Windows Credential Manager size limits. Leave AutoSplit enabled for large Windows local-manager secrets.
Expecting cloud secret deletion to be immediate. Cloud secret managers commonly disable and schedule deletion rather than immediately removing the secret.
Using UncommonOptions unnecessarily. Leave it empty unless a specific uncommon behavior is required.
Ignoring diagnostics after failures. Check LastErrorText for details.

Best Practices

Recommendation Reason
Choose Location explicitly. It makes the storage target clear and avoids platform-specific surprises.
Use the method matching the secret type. Store and retrieve string, binary, and JSON secrets with the corresponding Str, Bd, or Json methods.
Leave AutoSplit enabled for Windows local-manager secrets. It helps handle secrets larger than the Windows Credential Manager per-secret limit.
Use SetBootstrapSecret for cloud manager authentication credentials. Cloud secrets managers require credentials before they can be accessed.
Use Compression when secret contents benefit from compressed storage. Compression may reduce stored size, especially for larger text or JSON secrets.
Use ListSecrets with exact or wildcarded criteria. It helps discover secrets without hard-coding every identifier.
Check LastErrorText after failures. It provides useful diagnostic detail for failed or unexpected behavior.

Summary

Chilkat.Secrets is a unified secret-management class for local, cloud, and in-memory secrets. It supports string, binary, and JSON secret values; optional compression; Windows-specific automatic splitting for large local secrets; bootstrap credentials for cloud secret managers; listing and deletion; and conversion from compact secret specification strings to JSON identifiers.

The most important practical guidance is to select Location deliberately, use the secret method matching the data type, protect retrieved secret values, use bootstrap secrets for cloud manager authentication, leave AutoSplit enabled for Windows local-manager storage, and inspect LastErrorText whenever an operation fails or behaves unexpectedly.