Skip to content

Encrypt operational secrets in Cratis Chronicle

Use [Encrypted] in Cratis Chronicle to encrypt a non-personal operational secret at rest without including it in personal-data erasure. A partner credential or webhook signing secret can need this protection even though it is not data about a person.

If the value is personally identifiable information (PII), use [PII] instead. That marker encrypts personal data and includes it in Chronicle’s erasure mechanism for the General Data Protection Regulation (GDPR). The Security overview explains how choosing the wrong marker can make a non-personal secret unreadable when a person’s key is erased.

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class EncryptedAttribute(EncryptionScope scope = EncryptionScope.Subject, string details = "") : Attribute
{
public EncryptionScope Scope { get; } = scope;
public string Details { get; } = details;
}

View C# snippet source on GitHub

In .NET, import EncryptedAttribute from Cratis.Chronicle.ProtectedValues. The optional details parameter records why the value needs encryption; it does not change the encryption behavior.

using Cratis.Chronicle.ProtectedValues;

View C# snippet source on GitHub

When a secret has a dedicated concept type, a type that names that domain value, mark the type itself. Each event property using that type is then encrypted, so you do not have to repeat the marker on every event.

[Encrypted]
public record PartnerApiKey(string Value) : ConceptAs<string>(Value);
public record PartnerIntegrationConfiguredWithKey(PartnerApiKey ApiKey);

View C# snippet source on GitHub

Mark a single property directly when the value has no dedicated concept type. In this example, Chronicle encrypts ApiKey and leaves PartnerName as plaintext:

public record PartnerIntegrationConfigured(
[Encrypted] string ApiKey,
string PartnerName);
// When this event is written, ApiKey is encrypted. PartnerName is stored as plaintext.

View C# snippet source on GitHub

Choose one marker for each value. [PII] and [Encrypted] select different keys and erasure behavior; combining them is invalid, not extra protection. Schema generation rejects a property that resolves both markers. In .NET, it throws PIIAndEncryptedCombinedNotSupported:

// Throws PIIAndEncryptedCombinedNotSupported at schema-generation time,
// and is flagged at compile time by CHR0053.
public record EncryptedCustomerRegistered(
[PII] [Encrypted] string SomeValue);

View C# snippet source on GitHub

Use [PII] for personal data and [Encrypted] for non-personal operational secrets. In .NET, CHR0053 catches directly visible combinations at compile time. Schema generation also catches combinations inherited through a marked concept type.

A record can contain both a personal email address marked [PII] and a non-personal partner credential marked [Encrypted]. A subject identity tells Chronicle who a protected value belongs to. Even when both values resolve to the same subject, Chronicle stores their keys under different identifiers. Erasing the person’s PII leaves the credential’s key untouched, so the credential can still be decrypted.

The kernel keeps these operations separate:

  • [Encrypted] key identifiers use a reserved prefix that the PII path does not produce.
  • The compliance entry points DeleteEncryptionKeyFor and AllowNewEncryptionKeyFor refuse identifiers with that prefix.

The confidentiality API exposes no equivalent erasure operation. Use [PII] for personal data that needs to participate in erasure; [Encrypted] does not provide that behavior.

EncryptionScope determines which values share an encryption key. It does not change the encryption algorithm:

public enum EncryptionScope
{
Subject, // per compliance identity - the default
Namespace, // one key shared by every value marked this way in the event store namespace
Global // one key shared by every value marked this way across the whole installation
}

View C# snippet source on GitHub

Choose the scope that matches the secret’s ownership:

Scope Values that share a key
EncryptionScope.Subject (default) Values with the same compliance identity in the event store namespace. This is the subject, or the event source id when none is set, but the key remains separate from any [PII] key for that identity.
EncryptionScope.Namespace Every value marked with this scope in a given event store namespace, regardless of the document’s subject.
EncryptionScope.Global Every value marked with this scope across the whole Chronicle installation, including every event store and namespace.

For example, use Namespace for a webhook signing secret shared across the partner integrations in that namespace. Global shares a key more broadly, across event stores as well as namespaces. Neither scope is available for [PII]: personal-data erasure remains tied to the compliance identity. See Compliance for that workflow.

[Encrypted]
public record PartnerApiKeyScoped(string Value) : ConceptAs<string>(Value); // one key per partner (EncryptionScope.Subject, the default)
[Encrypted(EncryptionScope.Namespace)]
public record PartnerWebhookSecret(string Value) : ConceptAs<string>(Value); // one key for every partner in the namespace
[Encrypted(EncryptionScope.Global)]
public record LicenseToken(string Value) : ConceptAs<string>(Value); // one key for the whole installation

View C# snippet source on GitHub

Keep the event source identifier in plaintext: Chronicle needs it to correlate events and locate subject-scoped keys when no subject is set. In .NET, schema generation throws EncryptedNotSupportedOnEventSourceId for identifier types derived from EventSourceId / EventSourceId<T> that themselves carry [Encrypted].

Applying [Encrypted] directly to an event source identifier property or record parameter is also prohibited. CHR0052 catches directly marked members whose types derive from EventSourceId<T> at compile time. The example below triggers that diagnostic, not EncryptedNotSupportedOnEventSourceId during schema generation. Do not rely on schema generation to reject directly marked members:

public record PartnerId(Guid Value) : EventSourceId<Guid>(Value);
// CHR0052: [Encrypted] cannot be applied to an EventSourceId<T> member.
public record PartnerIntegrationConfiguredWithId(
[Encrypted] PartnerId PartnerId,
string ApiKey);

View C# snippet source on GitHub

If the identifier itself is a secret, use a non-sensitive surrogate as the event source id and store the secret in a separate [Encrypted] property.

Use [Encrypted] in .NET, @encrypted() in TypeScript, @Encrypted in Kotlin/Java, or the encrypted macro in Elixir. The examples above show each client’s syntax. These clients emit security metadata for the kernel to apply encryption and reject a value that resolves both PII and encryption metadata during schema generation.

For read model decryption, continue to Releasing PII and encrypted values. It explains which reads decrypt values automatically and how to release an instance outside that path.