Chilkat Secrets Class added in Version 10.1.0

December 13, 2024

Chilkat Secrets Class added in Version 10.1.0

Introduced in version 10.1.0, the Chilkat Secrets class enables managing secrets like passwords and OAuth2 tokens locally (on Windows and MacOS/iOS) and across various cloud platforms. It offers a unified API for seamless secret storage and supports the following standard operations:

Create/Update a Secret
List Secrets
Delete a Secret
Get a Secret’s Value

Secrets can be located in:

Windows Credentials Manager
Apple Keychain
AWS Secrets Manager
Azure Key Vault
IBM Cloud Secrets Manager
Oracle Cloud Secrets
Doppler Secrets
In-Memory Secrets

Naming Secrets

Chilkat provides a unified naming convention that adapts to the requirements of different storage locations. This allows applications to switch between storage locations seamlessly, without renaming secrets or worrying about allowed or disallowed characters in secret names.

In the Chilkat Secrets API, a secret’s name can be composed of 4 parts:

application (optional)
service (required)
domain (optional)
username (required)

The secret name is specified using JSON. For example:

{
  "appName": "ChilkatTest",
  "service": "OAuth2",
  "domain": "office365.com",
  "username": "joe@example.com"
}

The Chilkat Secrets API imposes fewer restrictions on characters in secret names. At the storage location, the secret name is constructed by concatenating parts with a separator, such as /. Chilkat automatically selects the appropriate separator based on the storage location. For example:

{appName}/{service} /{domain}/{username} — If all 4 parts are specified.
/{service}/ {domain}/{username} — If the optional application name is omitted. The leading “/” indicates an empty appName.
{appName}/{service}/{username} — If the optional domain is omitted.
{service}/{username} — If only the required service and username is specified.

Windows Credentials Manager

The Chilkat Secrets API works with Generic Credentials in the Windows Credentials Manager. Secret names are constructed by percent-encoding each part and using / as the separator. For example:

ChilkatTest/OAuth2/office365.com/joe@example.com

Apple Keychain

In Apple’s Keychain Access, passwords and other secure information are stored with specific metadata, including a Service and an Account. These two fields help identify the purpose of the stored credential and the associated user.

Chilkat maps {appName}/{service} to the Keychain Service and {domain}/{username} to the Keychain Account. If {appName} or {domain} are omitted, {service} and {username} map directly to the Keychain Service and Account.

Note: Chilkat URL-encodes each part. Using the example above, the resulting Apple Keychain Service and Account would be:

Service: ChilkatTest/OAuth2
Account: office365.com/joe%40example.com

AWS Secrets Manager

AWS imposes the following restrictions on secret names:

The secret name can contain ASCII letters, numbers, and the following characters: /_+=.@-
An AWS Secrets Manager secret name cannot contain accented European characters or any other non-ASCII characters. Secret names are restricted to ASCII characters only.

With Chilkat, the restrictions are more flexible. Any US-ASCII character and accented European characters can be used. Chilkat automatically removes accents from European characters (e.g., é becomes e). Disallowed US-ASCII characters are replaced with special sequences (e.g., $ becomes _.DL._). This mapping is handled transparently, so your application can use the original disallowed characters without issue. While the AWS Management Console will display the special sequences (e.g., _.DL._), your application will see the original characters (e.g., $).

In the example above, the secret name displayed in the AWS Management Console would be:

ChilkatTest/OAuth2/office365.com/joe@example.com

Azure Key Vault

Azure imposes the following restrictions on secret names:

The name must be a 1-127 character string, starting with a letter and containing only 0-9, a-z, A-Z, and -.

With Chilkat, the restrictions are more flexible. Similar to AWS, accents are removed from European characters, and disallowed us-ascii chars are replaced with special sequences (e.g., . becomes --DOT--). The “-” char is used as a separator. In the example above, the secret name displayed in the Azure Console would be:

ChilkatTest-OAuth2-office365--DOT--com-joe--AT--example--DOT--com

IBM Cloud Secrets Manager

IBM imposes the following restrictions on secret names:

The secret name can only include alphanumeric A-Z, a-z, 0-9 and the following special chars: -, _, .

The secret name displayed in the IBM Console would be:

ChilkatTest-OAuth2-office365.com-joe--AT--example.com

Oracle Cloud Secrets

Oracle imposes the following restrictions on secret names:

The secret name can only include alphanumeric + dash + underscore.

The secret name displayed in the Oracle Cloud Console would be:

ChilkatTest-OAuth2-office365--DOT--com-joe--AT--example--DOT--com

Doppler Secrets

Doppler imposes the following restrictions on secret names:

Doppler secret names may only contain uppercase letters, numbers, and underscores

The secret name displayed in the Doppler Console would be:

CHILKATTEST_OAUTH2_OFFICE365__DOT__COM_JOE__AT__EXAMPLE__DOT__COM

The Bootstrap Secret

Accessing a cloud-based secrets manager requires an authentication secret, such as an OAuth2 token, known as the bootstrap secret. This secret must be stored locally, with options like the Windows Credentials Manager or Apple Keychain being ideal. The Chilkat Secrets API includes a SetBootstrapSecret function for this purpose. Refer to the examples for more details.

admin