### Install AutoVer Tool

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/CONTRIBUTING.md

Command to install the `AutoVer` tool globally using the .NET CLI. This tool is used to create `change file` entries for project versioning.

```bash
dotnet tool install -g AutoVer
```

--------------------------------

### Delete Expired Data Protection Keys in .NET 9+

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/README.md

For .NET 9 and later, this example shows how to use IDeletableKeyManager to remove data protection keys that have expired. This is useful for managing storage in long-running services, but be aware of the risks of data loss.

```csharp
using Microsoft.AspNetCore.DataProtection;
using Microsoft.AspNetCore.DataProtection.KeyManagement;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();

builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/MyApplication/DataProtection");

var app = builder.Build();

var keyManager = app.Services.GetService<IKeyManager>();

if (keyManager is IDeletableKeyManager deletableKeyManager)
{
    var utcNow = DateTimeOffset.UtcNow;
    var yearAgo = utcNow.AddYears(-1);

    if (!deletableKeyManager.DeleteKeys(key => key.ExpirationDate < yearAgo))
    {
        Console.WriteLine("Failed to delete keys.");
    }
    else
    {
        Console.WriteLine("Old keys deleted successfully.");
    }
}
else
{
    Console.WriteLine("Key manager does not support deletion.");
}
...
```

--------------------------------

### Provide Custom `IAmazonSimpleSystemsManagement` Client

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Register a custom `IAmazonSimpleSystemsManagement` client in dependency injection before calling `PersistKeysToAWSSystemsManager` to override default region, credentials, or HTTP settings.

```csharp
// Program.cs — explicit SSM client with a specific region
using Amazon.SimpleSystemsManagement;
using Amazon;

var builder = WebApplication.CreateBuilder(args);

// Register a custom SSM client; PersistKeysToAWSSystemsManager picks it up via DI
builder.Services.AddSingleton<IAmazonSimpleSystemsManagement>(
    new AmazonSimpleSystemsManagementClient(RegionEndpoint.EUWest1));

builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/EUApp/DataProtection", o =>
    {
        o.TierStorageMode = TierStorageMode.AdvancedUpgradeable;
    });

var app = builder.Build();
app.Run();
```

--------------------------------

### Create Change File with AutoVer

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/CONTRIBUTING.md

Command to create a `change file` using the `AutoVer` tool. Specify the project name and a changelog message. Ensure this command is run from the repository root.

```bash
autover change --project-name "Amazon.AspNetCore.DataProtection.SSM" -m "Fixed an issue causing a failure somewhere
```

--------------------------------

### Register SSM Key Persistence (Advanced Options)

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Configures SSM key persistence with advanced options like KMS encryption, storage tier selection, and resource tagging. Requires additional `kms:Encrypt` permission on the specified KMS key if `KMSKeyId` is set.

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/MyApp/DataProtection", options =>
    {
        // Encrypt parameters with a customer-managed KMS key
        options.KMSKeyId = "arn:aws:kms:us-east-1:123456789012:key/abcd-1234-efgh-5678";

        // Automatically upgrade to Advanced tier (up to 8 KB) if the key XML exceeds
        // the Standard tier limit (4 KB); throws SSMParameterToLongException above 8 KB
        options.TierStorageMode = TierStorageMode.AdvancedUpgradeable;

        // Tag every SSM parameter created by this library
        options.Tags["Environment"] = "Production";
        options.Tags["ManagedBy"] = "DataProtection";
    });

var app = builder.Build();
app.Run();
```

--------------------------------

### PersistOptions Configuration

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Defines configuration options for SSM key persistence, including KMS key ID, storage tier mode, and resource tags. Use this to customize how keys are stored in SSM Parameter Store.

```csharp
// All PersistOptions properties
var options = new PersistOptions
{
    // Optional: ARN or alias of a customer-managed KMS key.
    // If omitted, AWS uses the account-default SSM key.
    KMSKeyId = "alias/my-dataprotection-key",

    // Controls which SSM parameter tier is used for storage.
    // StandardOnly      — max 4 096 chars; throws if exceeded (default)
    // AdvancedUpgradeable — Standard up to 4 096 chars, Advanced up to 8 192 chars
    // AdvancedOnly      — always Advanced tier (max 8 192 chars)
    // IntelligentTiering — AWS automatically selects the appropriate tier
    TierStorageMode = TierStorageMode.AdvancedUpgradeable
};

// Tags are added to the dictionary property (not the constructor)
options.Tags["Project"] = "MyWebApp";
options.Tags["CostCenter"] = "Engineering";

// Use in registration:
builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/MyApp/Keys", o =>
    {
        o.KMSKeyId   = options.KMSKeyId;
        o.TierStorageMode = options.TierStorageMode;
        o.Tags["Project"] = "MyWebApp";
    });
```

--------------------------------

### Register SSM Key Persistence (Basic)

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Registers SSM as the backing store for ASP.NET Core Data Protection keys. Keys are stored under the specified prefix path in SSM Parameter Store as SecureString values. Requires `ssm:PutParameter` and `ssm:GetParametersByPath` IAM permissions.

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/MyApplication/DataProtection");
    // Keys are stored at: /MyApplication/DataProtection/<key-guid>

builder.Services.AddControllersWithViews();

var app = builder.Build();
app.MapDefaultControllerRoute();
app.Run();
```

--------------------------------

### Configure Data Protection with AWS Systems Manager

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/README.md

Add data protection services and configure key persistence to AWS Systems Manager Parameter Store. This is typically done during application startup.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddDataProtection()
        .PersistKeysToAWSSystemsManager("/MyApplication/DataProtection");

    services.AddMvc();
}
```

--------------------------------

### Configure SSM Parameter Store Tier Storage Mode

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Select the SSM parameter storage tier for data protection keys. Standard is free but limited; Advanced supports larger keys at a cost; IntelligentTiering lets AWS decide.

```csharp
// StandardOnly (default) — fails loudly if key XML > 4 096 chars
builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/App/Keys", o =>
        o.TierStorageMode = TierStorageMode.StandardOnly);
```

```csharp
// AdvancedUpgradeable — Standard when possible, Advanced when necessary
builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/App/Keys", o =>
        o.TierStorageMode = TierStorageMode.AdvancedUpgradeable);
```

```csharp
// AdvancedOnly — always use Advanced tier regardless of key size
builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/App/Keys", o =>
        o.TierStorageMode = TierStorageMode.AdvancedOnly);
```

```csharp
// IntelligentTiering — let AWS decide automatically
builder.Services.AddDataProtection()
    .PersistKeysToAWSSystemsManager("/App/Keys", o =>
        o.TierStorageMode = TierStorageMode.IntelligentTiering);
```

--------------------------------

### Change File Structure for Contributions

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/CONTRIBUTING.md

Defines the structure for a `change file` used to log changelog messages and version increment types for modified projects. This file is typically located in the `.autover/changes/` directory.

```json
{
  "Projects": [
    {
      "Name": "Amazon.AspNetCore.DataProtection.SSM",
      "Type": "Patch",
      "ChangelogMessages": [
        "Fixed an issue causing a failure somewhere"
      ]
    }
  ]
}
```

--------------------------------

### Handle SSMParameterToLongException for Oversized Keys

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

Catch `SSMParameterToLongException` when data protection key XML exceeds the configured tier's size limit. This allows logging and corrective actions, such as changing the tier mode.

```csharp
// Handling SSMParameterToLongException in a custom IXmlRepository wrapper (advanced usage)
try
{
    dataProtector.Protect(largePayload);
}
catch (AggregateException aggEx)
    when (aggEx.InnerExceptions.Any(e => e is SSMParameterToLongException))
{
    var ssmEx = aggEx.InnerExceptions
        .OfType<SSMParameterToLongException>()
        .First();

    Console.Error.WriteLine($"Data protection key is too large for the configured SSM tier: {ssmEx.Message}");
    // Remediation: change TierStorageMode to AdvancedUpgradeable or AdvancedOnly
}
```

--------------------------------

### Required IAM Policy for Data Protection

Source: https://context7.com/aws/aws-ssm-data-protection-provider-for-aspnet/llms.txt

This IAM policy grants the minimum permissions needed to store and retrieve data protection keys using AWS Systems Manager Parameter Store. Additional permissions like kms:Encrypt, kms:Decrypt, and ssm:DeleteParameter may be required based on KMS key usage and .NET version.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DataProtectionSSM",
            "Effect": "Allow",
            "Action": [
                "ssm:PutParameter",
                "ssm:GetParametersByPath"
            ],
            "Resource": "arn:aws:ssm:*:*:parameter/MyApplication/DataProtection/*"
        },
        {
            "Sid": "DataProtectionKMS",
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:us-east-1:123456789012:key/abcd-1234-efgh-5678"
        },
        {
            "Sid": "DataProtectionSSMDelete",
            "Effect": "Allow",
            "Action": [
                "ssm:DeleteParameter"
            ],
            "Resource": "arn:aws:ssm:*:*:parameter/MyApplication/DataProtection/*"
        }
    ]
}
```

--------------------------------

### IAM Policy for AWS Systems Manager Data Protection

Source: https://github.com/aws/aws-ssm-data-protection-provider-for-aspnet/blob/main/README.md

This IAM policy grants the necessary permissions for the application to interact with AWS Systems Manager Parameter Store for storing and retrieving data protection keys. Ensure the Resource is scoped appropriately for production environments.

```javascript
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "rule1",
            "Effect": "Allow",
            "Action": [
                "ssm:PutParameter",
                "ssm:GetParametersByPath"
            ],
            "Resource": "*"
        }
    ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.