Tayra

Appearance

Options ​

Tayra is configured through the TayraOptions class, which can be set via the AddTayra() overload that accepts an Action<TayraOptions>.

Configuration Example ​

cs
// TayraOptions - configures the Tayra encryption engine
//
// Property          Type        Default              Description
// ───────────────── ─────────── ──────────────────── ────────────────────────────
// KeyCacheDuration  TimeSpan    5 minutes            How long keys are held in the MemoryCache
// KeySizeInBits     int         256                  AES key size (128, 192, or 256)
// LicenseKey        string?     null                 Trial or production key; required in all environments
var options = new TayraOptions
{
    KeyCacheDuration = TimeSpan.FromMinutes(5),
    KeySizeInBits = 256,
    LicenseKey = null,
};
anchor

Options Reference ​

PropertyTypeDefaultDescription
KeyCacheDurationTimeSpan5 minutesHow long encryption keys are held in the in-memory MemoryCache before being re-fetched from the key store.
KeyStoreReadBackTimeoutTimeSpan3 secondsHow long to keep retrying the read of a key that was just created and is not visible in the key store yet. 00:00:00 reads once. See Reading a new key back.
KeySizeInBitsint256AES key size in bits. Valid values: 128, 192, 256.
LicenseKeystring?nullLicense key. Required in all environments - request a free trial key at tayra.dev. When not set, Tayra reads Tayra:LicenseKey, the TAYRA_LICENSE_KEY environment variable, or the per-user license file (Setting your license key).
BlindIndexBlindIndexOptionsemptyBlind index configuration object.
MaskingMaskingOptionsemptyMasking configuration object.
AuditLoggingAuditLoggingOptionsminimized IDs, per-record events at DebugControls the default audit logger. Key/subject IDs are prefix+hash minimized; set AuditLogging.LogFullIdentifiers = true to opt in to full identifiers. AuditLogging.Levels sets the log level of each event type (see Audit trail).
MethodReturnsDescription
Entity<T>(Action<EntityTypeBuilder<T>>)TayraOptionsConfigures an entity type for PII protection and/or blind indexing using the fluent API.

Setting Options ​

Pass a configuration delegate to AddTayra():

cs
var fullServices = new ServiceCollection();
fullServices.AddTayra(opts =>
{
    opts.LicenseKey = licenseKey;

    // How long encryption keys are cached in memory (default: 5 minutes)
    opts.KeyCacheDuration = TimeSpan.FromMinutes(10);

    // AES key size - 128, 192, or 256 bits (default: 256)
    opts.KeySizeInBits = 256;
});
anchor

You can also bind options from IConfiguration using the standard .NET options pattern:

cs
services.Configure<TayraOptions>(configuration.GetSection("Tayra"));
services.AddTayra(); // license key comes from config; chain a production key store as needed
anchor

With a corresponding appsettings.json:

json
{
  "Tayra": {
    "KeyCacheDuration": "00:10:00",
    "KeySizeInBits": 256,
    "LicenseKey": "your-license-key-here"
  }
}

Cache Duration Tradeoffs ​

The KeyCacheDuration setting controls how long encryption keys are held in memory after being retrieved from the key store.

The same duration applies to the record of which key version is current for a subject, so a key rotation made by another instance is picked up within KeyCacheDuration.

Short cache (1-2 minutes)

Better for scenarios where keys change frequently, such as during key rotation. The tradeoff is more frequent calls to the key store, which increases latency and load.

Long cache (30+ minutes)

Reduces key store calls significantly, improving performance. However, after a key is deleted for crypto-shredding, cached copies of the key remain usable until the cache entry expires. The ShredAsync method on ITayra evicts the key from the local cache immediately, but other application instances may still have cached copies.

For most applications, the default of 5 minutes provides a good balance. In distributed deployments, keep the cache duration shorter to ensure crypto-shredding takes effect across all instances within an acceptable window.

Reading a New Key Back ​

Tayra creates every key first-writer-wins and then reads it back, and uses only what it read. That is what makes two instances that create the same key at the same moment agree on one, and it means nothing is ever encrypted under a key the store does not hold. It applies to data keys, blind index HMAC keys, and envelope master keys.

Some key stores are eventually consistent: on AWS Secrets Manager and AWS Parameter Store, a read issued right after a create can miss the new entry, which is there a moment later. So a read-back that finds nothing is retried up to five times, with waits that double and add up to KeyStoreReadBackTimeout (100, 200, 400, 800 and 1500 ms for the default 3 seconds). If the key still cannot be read, the operation fails with InvalidOperationException rather than use the key unread; the key is normally in the store by then, so the next attempt finds it.

  • The wait is only spent when a read misses. On a strongly consistent store (PostgreSQL, Vault, Azure Key Vault) that happens only when the key is deleted in the same instant, for example by a concurrent crypto-shred, so the default costs nothing in normal operation.
  • Raise it if you see was stored but could not be read back or not found in the key store immediately after storing it against an eventually consistent store, typically on a cold start that creates many keys at once.
  • Set it to TimeSpan.Zero to read once and fail at once, which was the behavior up to 2.8.x.

Key Size ​

AES-256 (the default) is recommended for all new deployments. AES-128 and AES-192 are supported for compatibility with existing systems but offer a smaller security margin.

Key SizeBytesSecurity Level
128 bits16 bytesStandard
192 bits24 bytesHigh
256 bits32 bytesMaximum

Do Not Change Key Size After Deployment

Changing KeySizeInBits after data has been encrypted will cause decryption failures. The key size is not stored in the wire format - it is determined by the key itself. If you need to change key sizes, use key rotation to re-encrypt existing data.

See Also ​