Tayra

Appearance

AWS Parameter Store ​

The AWS Parameter Store persists encryption keys as SecureString parameters in AWS Systems Manager Parameter Store, encrypted with AWS KMS. It is the recommended choice for applications running on AWS that want native integration with IAM and KMS.

Installation ​

shell
dotnet add package Tayra.KeyStore.AwsParameterStore
powershell
Install-Package Tayra.KeyStore.AwsParameterStore

Basic Setup ​

The simplest registration uses the default AWS credentials chain (environment variables, instance profile, IAM role, etc.):

cs
var services = new ServiceCollection();

// Use AWS Systems Manager Parameter Store
// with the default AWS credentials chain
services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseAwsKeyStore();
anchor

Configuration Options ​

Use the options overload to customize the path prefix, KMS key, region, and retry behavior:

cs
var services = new ServiceCollection();

services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseAwsKeyStore(options =>
    {
        // Path prefix for parameters (default: "/tayra/")
        // Must start and end with '/'
        options.PathPrefix = "/myapp/encryption/keys/";

        // Optional custom KMS key ID or alias for encrypting SecureString parameters
        // When null, the default AWS-managed key (alias/aws/ssm) is used
        options.KmsKeyId = "alias/my-custom-key";

        // Optional AWS region override (default: from credentials chain)
        options.Region = "us-west-2";

        // Maximum number of retries for transient errors (default: 3)
        options.MaxRetries = 5;

        // Base delay for exponential backoff on retries (default: 100ms)
        options.RetryBaseDelay = TimeSpan.FromMilliseconds(200);
    });
anchor

Options Reference ​

PropertyTypeDefaultDescription
PathPrefixstring"/tayra/"Path prefix for parameters. Must start and end with /.
KmsKeyIdstring?nullOptional custom KMS key ID or alias for encrypting SecureString parameters. When null, the default AWS-managed key (alias/aws/ssm) is used.
Regionstring?nullOptional AWS region override. When null, the region from the default credentials chain is used.
MaxRetriesint3Maximum number of retries for transient errors.
RetryBaseDelayTimeSpan100msBase delay for exponential backoff on retries.

Pre-configured SSM Client ​

If you already have an IAmazonSimpleSystemsManagement client configured (e.g., with assumed-role credentials), pass it directly:

cs
var services = new ServiceCollection();

var ssmClient = new Amazon.SimpleSystemsManagement.AmazonSimpleSystemsManagementClient(
    Amazon.RegionEndpoint.USWest2);

services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseAwsKeyStore(ssmClient, options =>
    {
        options.PathPrefix = "/myapp/encryption/keys/";
    });
anchor

PathPrefix Convention ​

Tayra stores each encryption key as a SecureString parameter. The full parameter name is constructed as:

{path_prefix}{sanitized_key_id}
ComponentValueSource
path_prefix/tayra/PathPrefix option (default: "/tayra/"). Automatically normalized to start and end with /.
sanitized_key_iduser-123/personal/nameThe Tayra key identifier with colons (:) converted to path separators (/) for hierarchical organization.

For example, with the default prefix /tayra/ and a key ID of user-123:personal:name, the parameter name is:

/tayra/user-123/personal/name

This hierarchical structure enables:

  • Browsing keys by subject in the AWS Console
  • Using IAM policies scoped to specific path prefixes
  • Efficient prefix-based operations (DeleteByPrefixAsync, ListKeyIdsAsync)

Organize by Environment

Use path prefixes to separate keys across environments:

csharp
options.PathPrefix = "/tayra/production/keys/";  // Production
options.PathPrefix = "/tayra/staging/keys/";      // Staging

KMS Key for Encryption ​

Parameter Store SecureString parameters are encrypted at rest using AWS KMS. You can control which KMS key is used:

  • Default (null) -- Uses the AWS-managed key alias/aws/ssm. This is free and suitable for most use cases.
  • Custom KMS key -- Specify a key ID, key ARN, alias name, or alias ARN. Use this when you need customer-managed key controls, key rotation policies, or cross-account access.
csharp
options.KmsKeyId = "alias/my-custom-key";
// or
options.KmsKeyId = "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012";

IAM Policy Requirements ​

The IAM role or user must have the following permissions:

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:PutParameter",
        "ssm:GetParameter",
        "ssm:DeleteParameter",
        "ssm:DeleteParameters",
        "ssm:GetParametersByPath",
        "ssm:DescribeParameters"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/tayra/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:*:*:key/*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "ssm.*.amazonaws.com"
        }
      }
    }
  ]
}

Least Privilege

Scope the Resource ARN to match your PathPrefix. The example above uses /tayra/keys/* which matches the default prefix. If you change PathPrefix, update the policy accordingly.

Retry Logic ​

The AWS Parameter Store key store includes built-in retry logic with exponential backoff for transient errors. The backoff delay doubles on each attempt: for the default settings (base delay = 100ms, max retries = 3), the delays are approximately 100ms, 200ms, and 400ms.

This is in addition to any retry policy configured on the AmazonSimpleSystemsManagementClient itself.

Parameter Store Limits ​

Be aware of AWS Parameter Store service limits:

LimitValueNotes
Max parameters per account per region10,000 (standard)Can be increased to 100,000 via AWS Support
Max parameter name length2,048 charactersIncluding the path prefix
Max parameter value size4 KB (standard)AES-256 keys are 32 bytes, well within this limit
GetParameter TPS1,000Shared across all parameters in the account

For applications with a very large number of data subjects, consider whether these limits are sufficient or whether a different key store (PostgreSQL, Vault) would be more appropriate.

See Also ​