The AWS SDK for .NET V3 has entered maintenance mode. We recommend that you migrate to [AWS SDK for .NET V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html). For additional details and information on how to migrate, please refer to our [maintenance mode announcement](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/). # Security for this AWS Product or Service Cloud security at Amazon Web Services (AWS) is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations. Security is a shared responsibility between AWS and you. The [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) describes this as Security of the Cloud and Security in the Cloud. **Security of the Cloud** – AWS is responsible for protecting the infrastructure that runs all of the services offered in the AWS Cloud and providing you with services that you can use securely. Our security responsibility is the highest priority at AWS, and the effectiveness of our security is regularly tested and verified by third-party auditors as part of the [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/). **Security in the Cloud** – Your responsibility is determined by the AWS service you are using, and other factors including the sensitivity of your data, your organization’s requirements, and applicable laws and regulations. This AWS product or service follows the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the [AWS service security documentation page](https://docs.aws.amazon.com/security/?id=docs_gateway#aws-security) and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). **Topics** + [Data protection](data-protection.md) + [Identity and Access Management](security-iam.md) + [Compliance Validation](compliance-validation.md) + [Resilience](disaster-recovery-resiliency.md) + [Infrastructure Security](infrastructure-security.md) + [Enforcing a minimum TLS version](enforcing-tls.md) + [S3 Encryption Client Migration (V1 to V2)](s3-encryption-migration-v1-v2.md) + [S3 Encryption Client Migration (V2 to V4)](s3-encryption-migration-v2-v4.md) # Data protection in this AWS Product or Service The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in this AWS product or service. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/). For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*. For data protection purposes, we recommend that you protect AWS account credentials and set up individual users with AWS IAM Identity Center or AWS Identity and Access Management (IAM). That way, each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways: + Use multi-factor authentication (MFA) with each account. + Use SSL/TLS to communicate with AWS resources. We require TLS 1.2 and recommend TLS 1.3. + Set up API and user activity logging with AWS CloudTrail. For information about using CloudTrail trails to capture AWS activities, see [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html) in the *AWS CloudTrail User Guide*. + Use AWS encryption solutions, along with all default security controls within AWS services. + Use advanced managed security services such as Amazon Macie, which assists in discovering and securing sensitive data that is stored in Amazon S3. + If you require FIPS 140-3 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/). We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form text fields such as a **Name** field. This includes when you work with this AWS product or service or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form text fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server. # Identity and Access Management AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use AWS resources. IAM is an AWS service that you can use with no additional charge. **Topics** + [Audience](#security_iam_audience) + [Authenticating with identities](#security_iam_authentication) + [Managing access using policies](#security_iam_access-manage) + [How AWS services work with IAM](#security_iam_service-with-iam) + [Troubleshooting AWS identity and access](#security_iam_troubleshoot) ## Audience How you use AWS Identity and Access Management (IAM) differs, depending on the work that you do in AWS. **Service user** – If you use AWS services to do your job, then your administrator provides you with the credentials and permissions that you need. As you use more AWS features to do your work, you might need additional permissions. Understanding how access is managed can help you request the right permissions from your administrator. If you cannot access a feature in AWS, see [Troubleshooting AWS identity and access](#security_iam_troubleshoot) or the user guide of the AWS service you are using. **Service administrator** – If you're in charge of AWS resources at your company, you probably have full access to AWS. It's your job to determine which AWS features and resources your service users should access. You must then submit requests to your IAM administrator to change the permissions of your service users. Review the information on this page to understand the basic concepts of IAM. To learn more about how your company can use IAM with AWS, see the user guide of the AWS service you are using. **IAM administrator** – If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to AWS. To view example AWS identity-based policies that you can use in IAM, see the user guide of the AWS service you are using. ## Authenticating with identities Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role. You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*. For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*. ### AWS account root user When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*. ### Federated identity As a best practice, require human users to use federation with an identity provider to access AWS services using temporary credentials. A *federated identity* is a user from your enterprise directory, web identity provider, or Directory Service that accesses AWS services using credentials from an identity source. Federated identities assume roles that provide temporary credentials. For centralized access management, we recommend AWS IAM Identity Center. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*. ### IAM users and groups An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*. An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*. ### IAM roles An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*. IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*. ## Managing access using policies You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*. Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**. By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation. ### Identity-based policies Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*. Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*. ### Resource-based policies Resource-based policies are JSON policy documents that you attach to a resource. Examples include IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy. Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy. ### Access control lists (ACLs) Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format. Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about ACLs, see [Access control list (ACL) overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) in the *Amazon Simple Storage Service Developer Guide*. ### Other policy types AWS supports additional policy types that can set the maximum permissions granted by more common policy types: + **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*. + **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*. + **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*. + **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*. ### Multiple policy types When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. ## How AWS services work with IAM To get a high-level view of how AWS services work with most IAM features, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*. To learn how to use a specific AWS service with IAM, see the security section of the relevant service's User Guide. ## Troubleshooting AWS identity and access Use the following information to help you diagnose and fix common issues that you might encounter when working with AWS and IAM. **Topics** + [I am not authorized to perform an action in AWS](#security_iam_troubleshoot-no-permissions) + [I am not authorized to perform iam:PassRole](#security_iam_troubleshoot-passrole) + [I want to allow people outside of my AWS account to access my AWS resources](#security_iam_troubleshoot-cross-account-access) ### I am not authorized to perform an action in AWS If you receive an error that you're not authorized to perform an action, your policies must be updated to allow you to perform the action. The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a fictional `my-example-widget` resource but doesn't have the fictional `awes:GetWidget` permissions. ``` User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: awes:GetWidget on resource: my-example-widget ``` In this case, the policy for the `mateojackson` user must be updated to allow access to the `my-example-widget` resource by using the `awes:GetWidget` action. If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials. ### I am not authorized to perform iam:PassRole If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to AWS. Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service. The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in AWS. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service. ``` User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole ``` In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action. If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials. ### I want to allow people outside of my AWS account to access my AWS resources You can create a role that users in other accounts or people outside of your organization can use to access your resources. You can specify who is trusted to assume the role. For services that support resource-based policies or access control lists (ACLs), you can use those policies to grant people access to your resources. To learn more, consult the following: + To learn whether AWS supports these features, see [How AWS services work with IAM](#security_iam_service-with-iam). + To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*. + To learn how to provide access to your resources to third-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*. + To learn how to provide access through identity federation, see [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*. + To learn the difference between using roles and resource-based policies for cross-account access, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*. # Compliance Validation for this AWS Product or Service To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/). You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html). Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. For more information about your compliance responsibility when using AWS services, see [AWS Security Documentation](https://docs.aws.amazon.com/security/). This AWS product or service follows the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the [AWS service security documentation page](https://docs.aws.amazon.com/security/?id=docs_gateway#aws-security) and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). # Resilience for this AWS Product or Service The AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures. For more information about AWS Regions and Availability Zones, see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/). This AWS product or service follows the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the [AWS service security documentation page](https://docs.aws.amazon.com/security/?id=docs_gateway#aws-security) and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). # Infrastructure Security for this AWS Product or Service This AWS product or service uses managed services, and therefore is protected by the AWS global network security. For information about AWS security services and how AWS protects infrastructure, see [AWS Cloud Security](https://aws.amazon.com/security/). To design your AWS environment using the best practices for infrastructure security, see [Infrastructure Protection](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html) in *Security Pillar AWS Well‐Architected Framework*. You use AWS published API calls to access this AWS Product or Service through the network. Clients must support the following: + Transport Layer Security (TLS). We require TLS 1.2 and recommend TLS 1.3. + Cipher suites with perfect forward secrecy (PFS) such as DHE (Ephemeral Diffie-Hellman) or ECDHE (Elliptic Curve Ephemeral Diffie-Hellman). Most modern systems such as Java 7 and later support these modes. Additionally, requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) (AWS STS) to generate temporary security credentials to sign requests. This AWS product or service follows the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the [AWS service security documentation page](https://docs.aws.amazon.com/security/?id=docs_gateway#aws-security) and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). # Enforcing a minimum TLS version in the AWS SDK for .NET To increase security when communicating with AWS services, you should configure the AWS SDK for .NET to use TLS 1.2 or later. The AWS SDK for .NET uses the underlying .NET runtime to determine which security protocol to use. By default, current versions of .NET use the latest configured protocol that the operating system supports. Your application can override this SDK behavior, but it's *not recommended* to do so. ## .NET Core By default, .NET Core uses the latest configured protocol that the operating system supports. The AWS SDK for .NET doesn't provide a mechanism to override this. If you're using a .NET Core version earlier than 2.1, we *strongly* recommend you upgrade your .NET Core version. See the following for information specific to each operating system. **Windows** Modern distributions of Windows have TLS 1.2 support [enabled by default](https://learn.microsoft.com/en-us/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-). If you're running on Windows 7 SP1 or Windows Server 2008 R2 SP1, you need to ensure that TLS 1.2 support is enabled in the registry, as described at [https://learn.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings\$1tls-12](https://learn.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12). If you're running an earlier distribution, you must upgrade your operating system. For information about TLS 1.3 support in Windows, check the latest Microsoft documentation for the minimum required client or server versions. **macOS** If you're running .NET Core 2.1 or later, TLS 1.2 is enabled by default. TLS 1.2 is supported by [OS X Mavericks v10.9 or later](https://support.apple.com/en-us/103373). .NET Core version 2.1 and later require newer versions of macOS, as described at [https://learn.microsoft.com/en-us/dotnet/core/install/windows?tabs=net80&pivots=os-macos](https://learn.microsoft.com/en-us/dotnet/core/install/windows?tabs=net80&pivots=os-macos). If you're using .NET Core 1.0, .NET Core [uses OpenSSL on macOS](https://github.com/dotnet/announcements/issues/21), a dependency that must be installed separately. OpenSSL added support for TLS 1.2 in version 1.0.1, and added support for TLS 1.3 in version 1.1.1. **Linux** .NET Core on Linux requires OpenSSL, which comes bundled with many Linux distributions. But it can also be installed separately. OpenSSL added support for TLS 1.2 in version 1.0.1, and added support for TLS 1.3 in version 1.1.1. If you're using a modern version of .NET Core (2.1 or later) and have installed a package manager, it's likely that a more modern version of OpenSSL was installed for you. To be sure, you can run **`openssl version`** in a terminal and verify that the version is later than 1.0.1. ## .NET Framework If you're running a modern version of .NET Framework (4.7 or later) and a modern version of Windows (at least Windows 8 for clients, Windows Server 2012 or later for servers), TLS 1.2 is enabled and used by default. If you're using a .NET Framework runtime that doesn't use the operating system settings (.NET Framework 3.5 through 4.5.2), the AWS SDK for .NET will attempt to [add support for TLS 1.1 and TLS 1.2](https://github.com/aws/aws-sdk-net/blob/aws-sdk-net-v3.7/sdk/src/Core/Amazon.Runtime/Pipeline/HttpHandler/AmazonSecurityProtocolManager.cs) to the supported protocols. If you're using .NET Framework 3.5, this will be successful only if the appropriate hot patch is installed, as follows: + Windows 10 version 1511 and Windows Server 2016 – [KB3156421](https://support.microsoft.com/kb/3156421) + Windows 8.1 and Windows Server 2012 R2 – [KB3154520](https://support.microsoft.com/kb/3154520) + Windows Server 2012 – [KB3154519](https://support.microsoft.com/kb/3154519) + Windows 7 SP1 and Server 2008 R2 SP1 – [KB3154518](https://support.microsoft.com/kb/3154518) **Warning** Starting August 15th, 2024, the AWS SDK for .NET will end support for .NET Framework 3.5 and will change the minimum .NET Framework version to 4.7.2. For more information, see the blog post [Important changes coming for .NET Framework 3.5 and 4.5 targets of the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/important-changes-coming-for-net-framework-3-5-and-4-5-targets-of-the-aws-sdk-for-net/). If your application is running on a newer .NET Framework on Windows 7 SP1 or Windows Server 2008 R2 SP1, you need to ensure that TLS 1.2 support is enabled in the registry, as described at [https://learn.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings\$1tls-12](https://learn.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12). Newer versions of Windows have it [enabled by default](https://learn.microsoft.com/en-us/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-). For detailed best practices for using TLS with .NET Framework, see the Microsoft article at [https://learn.microsoft.com/en-us/dotnet/framework/network-programming/tls](https://learn.microsoft.com/en-us/dotnet/framework/network-programming/tls). ## AWS Tools for PowerShell [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/) use the AWS SDK for .NET for all calls to AWS services. The behavior of your environment depends on the version of Windows PowerShell you're running, as follows. **Windows PowerShell 2.0 through 5.x** Windows PowerShell 2.0 through 5.x run on .NET Framework. You can verify which .NET runtime (2.0 or 4.0) is being used by PowerShell by using the following command. ``` $PSVersionTable.CLRVersion ``` + When using .NET Runtime 2.0, follow the instructions provided earlier regarding the AWS SDK for .NET and .NET Framework 3.5. **Warning** Starting August 15th, 2024, the AWS SDK for .NET will end support for .NET Framework 3.5 and will change the minimum .NET Framework version to 4.7.2. For more information, see the blog post [Important changes coming for .NET Framework 3.5 and 4.5 targets of the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/important-changes-coming-for-net-framework-3-5-and-4-5-targets-of-the-aws-sdk-for-net/). + When using .NET Runtime 4.0, follow the instructions provided earlier regarding the AWS SDK for .NET and .NET Framework 4\$1. **Windows PowerShell 6.0** Windows PowerShell 6.0 and newer run on .NET Core. You can verify which version of .NET Core is being used by running the following command. ``` [System.Reflection.Assembly]::GetEntryAssembly().GetCustomAttributes([System.Runtime.Versioning.TargetFrameworkAttribute], $true).FrameworkName ``` Follow the instructions provided earlier regarding the AWS SDK for .NET and the relevant version of .NET Core. ## Xamarin For Xamarin, see the directions at [https://learn.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/transport-layer-security](https://learn.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/transport-layer-security). In summary: **For Android** + Requires Android 5.0 or later. + **Project Properties**, **Android Options**: HttpClient implementation must be set to **Android** and the SSL/TLS implementation set to **Native TLS 1.2\$1**. **For iOS** + Requires iOS 7 or later. + **Project Properties**, **iOS Build**: HttpClient implementation must be set to **NSUrlSession**. **For macOS** + Requires macOS 10.9 or later. + **Project Options**, **Build**, **Mac Build**: HttpClient implementation must be set to **NSUrlSession**. ## Unity You must use Unity 2018.2 or later, and use the .NET 4.x Equivalent scripting runtime. You can set this in **Project Settings**, **Configuration**, **Player**, as described at [https://docs.unity3d.com/2019.1/Documentation/Manual/ScriptingRuntimeUpgrade.html](https://docs.unity3d.com/2019.1/Documentation/Manual/ScriptingRuntimeUpgrade.html). The .NET 4.x Equivalent scripting runtime enables TLS 1.2 support to all Unity platforms running Mono or IL2CPP. ## Browser (for Blazor WebAssembly) WebAssembly runs in the browser instead of on the server, and uses the browser for handling HTTP traffic. Therefore, TLS support is determined by browser support. Blazor WebAssembly, in preview for ASP.NET Core 3.1, is supported only in browsers that support WebAssembly, as described at [https://learn.microsoft.com/en-us/aspnet/core/blazor/supported-platforms](https://learn.microsoft.com/en-us/aspnet/core/blazor/supported-platforms). All mainstream browsers supported TLS 1.2 before supporting WebAssembly. If this is the case for your browser, then if your app runs, it can communicate over TLS 1.2. See your browser's documentation for more information and verification. # Amazon S3 Encryption Client Migration (V1 to V2) **Note** If you are using V2 and want to migrate to V4, see [Amazon S3 Encryption Client Migration (V2 to V4)](s3-encryption-migration-v2-v4.md). This topic shows how to migrate your applications from Version 1 (V1) of the Amazon Simple Storage Service (Amazon S3) encryption client to Version 2 (V2), and ensure application availability throughout the migration process. Objects that are encrypted with the V2 client can't be decrypted with the V1 client. In order to ease migration to the new client without having to re-encrypt all objects at once, a "V1-transitional" client has been provided. This client can *decrypt* both V1- and V2-encrypted objects, but *encrypts* objects only in V1-compatible format. The V2 client can *decrypt* both V1- and V2-encrypted objects (when enabled for V1 objects), but *encrypts* objects only in V2-compatible format. ## Migration Overview This migration happens in three phases. These phases are introduced here and described in detail later. Each phase must be completed for *all* clients that use shared objects before the next phase is started. 1. **Update existing clients to V1-transitional clients to read new formats.** First, update your applications to take a dependency on the V1-transitional client instead of the V1 client. The V1-transitional client enables your existing code to decrypt objects written by the new V2 clients and objects written in V1-compatible format. **Note** The V1-transitional client is provided for migration purposes only. Proceed to upgrading to the V2 client after moving to the V1-transitional client. 1. **Migrate V1-transitional clients to V2 clients to write new formats.** Next, replace all V1-transitional clients in your applications with V2 clients, and set the security profile to `V2AndLegacy`. Setting this security profile on V2 clients enables those clients to decrypt objects that were encrypted in V1-compatible format. 1. **Update V2 clients to no longer read V1 formats.** Finally, after all clients have been migrated to V2 and all objects have been encrypted or re-encrypted in V2-compatible format, set the V2 security profile to `V2` instead of `V2AndLegacy`. This prevents the decryption of objects that are in V1-compatible format. ## Update Existing Clients to V1-transitional Clients to Read New Formats The V2 encryption client uses encryption algorithms that older versions of the client don't support. The first step in the migration is to update your V1 decryption clients so that they can read the new format. The V1-transitional client enables your applications to decrypt both V1- and V2-encrypted objects. This client is a part of the [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet package. Perform the following steps on each of your applications to use the V1-transitional client. 1. Take a new dependency on the [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) package. If your project depends directly on the **AWSSDK.S3** or **AWSSDK.KeyManagementService** packages, you must either update those dependencies or remove them so that their updated versions will be pulled in with this new package. 1. Change the appropriate `using` statement from `Amazon.S3.Encryption` to `Amazon.Extensions.S3.Encryption`, as follows: ``` // using Amazon.S3.Encryption; using Amazon.Extensions.S3.Encryption; ``` 1. Rebuild and redeploy your application. The V1-transitional client is fully API-compatible with the V1 client, so no other code changes are required. ## Migrate V1-transitional Clients to V2 Clients to Write New Formats The V2 client is a part of the [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet package. It enables your applications to decrypt both V1- and V2-encrypted objects (if configured to do so), but encrypts objects only in V2-compatible format. After updating your existing clients to read the new encryption format, you can proceed to safely update your applications to the V2 encryption and decryption clients. Perform the following steps on each of your applications to use the V2 client: 1. Change `EncryptionMaterials` to `EncryptionMaterialsV2`. 1. When using KMS: 1. Provide a KMS key ID. 1. Declare the encryption method that you are using; that is, `KmsType.KmsContext`. 1. Provide an encryption context to KMS to associate with this data key. You can send an empty dictionary (Amazon encryption context will still be merged in), but providing additional context is encouraged. 1. When using user-provided key wrap methods (symmetric or asymmetric encryption): 1. Provide an `AES` or an `RSA` instance that contains the encryption materials. 1. Declare which encryption algorithm to use; that is, `SymmetricAlgorithmType.AesGcm` or `AsymmetricAlgorithmType.RsaOaepSha1`. 1. Change `AmazonS3CryptoConfiguration` to `AmazonS3CryptoConfigurationV2` with the `SecurityProfile` property set to `SecurityProfile.V2AndLegacy`. 1. Change `AmazonS3EncryptionClient` to `AmazonS3EncryptionClientV2`. This client takes the newly converted `AmazonS3CryptoConfigurationV2` and `EncryptionMaterialsV2` objects from the previous steps. ### Example: KMS to KMS\$1Context **Pre-migration** ``` using System.Security.Cryptography; using Amazon.S3.Encryption; var encryptionMaterial = new EncryptionMaterials("1234abcd-12ab-34cd-56ef-1234567890ab"); var configuration = new AmazonS3CryptoConfiguration() { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial); ``` **Post-migration** ``` using System.Security.Cryptography; using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; var encryptionContext = new Dictionary(); var encryptionMaterial = new EncryptionMaterialsV2("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext); var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial); ``` ### Example: Symmetric Algorithm (AES-CBC to AES-GCM Key Wrap) `StorageMode` can be either `ObjectMetadata` or `InstructionFile`. **Pre-migration** ``` using System.Security.Cryptography; using Amazon.S3.Encryption; var symmetricAlgorithm = Aes.Create(); var encryptionMaterial = new EncryptionMaterials(symmetricAlgorithm); var configuration = new AmazonS3CryptoConfiguration() { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial); ``` **Post-migration** ``` using System.Security.Cryptography; using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; var symmetricAlgorithm = Aes.Create(); var encryptionMaterial = new EncryptionMaterialsV2(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm); var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial); ``` **Note** When decrypting with AES-GCM, read the entire object to the end before you start using the decrypted data. This is to verify that the object hasn't been modified since it was encrypted. ### Example: Asymmetric Algorithm (RSA to RSA-OAEP-SHA1 Key Wrap) `StorageMode` can be either `ObjectMetadata` or `InstructionFile`. **Pre-migration** ``` using System.Security.Cryptography; using Amazon.S3.Encryption; var asymmetricAlgorithm = RSA.Create(); var encryptionMaterial = new EncryptionMaterials(asymmetricAlgorithm); var configuration = new AmazonS3CryptoConfiguration() { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial); ``` **Post-migration** ``` using System.Security.Cryptography; using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; var asymmetricAlgorithm = RSA.Create(); var encryptionMaterial = new EncryptionMaterialsV2(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1); var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial); ``` ## Update V2 Clients to No Longer Read V1 Formats Eventually, all objects will have been encrypted or re-encrypted using a V2 client. *After this conversion is complete*, you can disable V1 compatibility in the V2 clients by setting the `SecurityProfile` property to `SecurityProfile.V2`, as shown in the following snippet. ``` //var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy); var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2); ``` # Amazon S3 Encryption Client Migration (V2 to V4) **Note** If you are using V1 and want to migrate to V4, you must first migrate to V2. See [Amazon S3 Encryption Client Migration (V1 to V2)](s3-encryption-migration-v1-v2.md). This topic shows how to migrate your applications from Version 2 (V2) of the Amazon Simple Storage Service (Amazon S3) encryption client to Version 4 (V4), and ensure application availability throughout the migration process. V4 uses AES-GCM with key commitment for content encryption and introduces Commitment Policies to enhance security against key substitution attacks. The V4 client is available in the [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet package. **Important** **Breaking Changes:** V4 clients configured with `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` policy cannot decrypt objects encrypted with V1 or V2 clients. Only the latest V2 clients can decrypt V4-encrypted objects with key commitment. Before moving to the `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` policy, you must re-encrypt all your existing data using V4 clients with key commitment enabled. ## Understanding V4 Concepts V4 uses AES-GCM with key commitment for content encryption and introduces key security concepts that enhance the protection of your encrypted data: ### Commitment Policy Commitment Policy controls how the encryption client handles key commitment during encryption and decryption operations. V4 supports three commitment policies: `FORBID_ENCRYPT_ALLOW_DECRYPT` *Encryption:* Without commitment *Decryption:* Allows non-committing objects *Security:* Does not enforce commitment and may allow tampering *Compatibility:* All V2 and V4 implementations can read objects encrypted with this policy `REQUIRE_ENCRYPT_ALLOW_DECRYPT` *Encryption:* With key commitment *Decryption:* Allows both committing and non-committing objects *Security:* New objects are protected against key substitution attacks, old objects still readable *Compatibility:* Only V4 supports this policy `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`(Default for V4) *Encryption:* With key commitment *Decryption:* Only committing objects *Security:* Full commitment enforcement for maximum security *Compatibility:* Only V4 supports this policy ### AES GCM with Key Commitment V4 uses AES-GCM with key commitment for content encryption, which provides enhanced security: + *Tampering Protection:* It protects against key substitution attacks by cryptographically binding the key to the encrypted data. + *Version Compatibility:* Objects encrypted with key commitment can only be decrypted by V4 clients and newer versions. **Warning** Before enabling key commitment encryption in production, ensure that all applications that need to decrypt your objects have been upgraded to V4 or newer as V2 client is being deprecated. ## Update Existing Clients to Read V4 Formats The V4 encryption client uses encryption algorithms that older versions of the client don't support. The first step in the migration is to update your V2 clients so that they can read the new V4 format. ### Update NuGet Package Dependencies Update your applications to use the latest version of the [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet package that includes V4 support. Perform the following steps on each of your applications: 1. Update to the latest [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) package. If your project depends directly on the **AWSSDK.S3** or **AWSSDK.KeyManagementService** packages, you must either update those dependencies or remove them so that their updated versions will be pulled in with this new package. 1. Ensure your `using` statements reference the correct namespace: ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; ``` 1. Rebuild and redeploy your application. Your existing V2 clients will continue to work with the updated package and will be able to decrypt objects encrypted by V4 clients (depending on the commitment policy used). ### Build and Deploy Applications After updating your NuGet package dependencies: 1. Build your application to ensure all dependencies are resolved correctly. 1. Test your application in a development environment to verify that existing functionality continues to work. 1. Deploy the updated application to your production environment. This update enables your existing V2 clients to decrypt objects that will be encrypted by V4 clients, ensuring compatibility during the migration process. ## Migrate to V4 Clients After updating your existing clients to read the new encryption format, you can proceed to safely update your applications to use V4 encryption and decryption clients. The V4 client provides enhanced security through key commitment while maintaining compatibility with existing encrypted objects. ### 4-Step Migration Process The migration from V2 to V4 follows a structured 4-step process to ensure compatibility and security. Each step represents a specific configuration that should be deployed across all your applications before proceeding to the next step. 1. **Step 0: V2 Client (Starting Point)** - Your existing V2 implementation 1. **Step 1: V4 with V2 Compatibility** - Migrate to V4 client while maintaining V2-compatible encryption behavior 1. **Step 2: V4 with Key Commitment Writes** - Start encrypting with key commitment while allowing decryption of legacy objects 1. **Step 3: V4 with Full Enforcement** - Require key commitment for both encryption and decryption ### Step 0: V2 Client (Starting Point) This represents your existing V2 client configuration. This step demonstrates the starting state before migration. ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; using Amazon.S3.Model; // Step 0: V2 Client - Starting configuration var encryptionContext = new Dictionary(); var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext); #pragma warning disable 0618 var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2); #pragma warning enable 0618 var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial); // Use the client for PutObject and GetObject operations await encryptionClient.PutObjectAsync(new PutObjectRequest { BucketName = bucket, Key = objectKey, ContentBody = content }); ``` ### Step 1: V4 with V2 Compatibility Migrate to the V4 client while maintaining identical behavior to V2. This step uses `FORBID_ENCRYPT_ALLOW_DECRYPT` policy to encrypt without commitment and allow decryption of all objects. ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; using Amazon.S3.Model; // Step 1: V4 Client with V2 compatibility var encryptionContext = new Dictionary(); var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext); var configuration = new AmazonS3CryptoConfigurationV4( SecurityProfile.V4, CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, ContentEncryptionAlgorithm.AesGcm); var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial); // Use the client for PutObject and GetObject operations await encryptionClient.PutObjectAsync(new PutObjectRequest { BucketName = bucket, Key = objectKey, ContentBody = content }); ``` **Behavior:** Encrypts without commitment, can decrypt both committing and non-committing objects. Identical to V2 behavior. ### Step 2: V4 with Key Commitment Writes Start encrypting with key commitment while maintaining backward compatibility for decryption. This step uses `REQUIRE_ENCRYPT_ALLOW_DECRYPT` policy. **Warning** Before deploying Step 2, ensure all readers have been updated to Step 1 or later to handle key commitment encryption. ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; using Amazon.S3.Model; // Step 2: V4 Client with key commitment writes var encryptionContext = new Dictionary(); var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext); var configuration = new AmazonS3CryptoConfigurationV4( SecurityProfile.V4, CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, ContentEncryptionAlgorithm.AesGcmWithCommitment); var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial); // Use the client for PutObject and GetObject operations await encryptionClient.PutObjectAsync(new PutObjectRequest { BucketName = bucket, Key = objectKey, ContentBody = content }); ``` **Behavior:** Encrypts with commitment, can decrypt both committing and non-committing objects. New objects are protected against key substitution attacks. ### Step 3: V4 with Full Enforcement Require key commitment for both encryption and decryption. This step uses `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` policy for maximum security. **Warning** Before deploying Step 3, ensure all objects in your system have been re-encrypted with key commitment (Step 2). This step will fail to decrypt objects encrypted without commitment. ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; using Amazon.S3.Model; // Step 3: V4 Client with full key commitment enforcement var encryptionContext = new Dictionary(); var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext); var configuration = new AmazonS3CryptoConfigurationV4( SecurityProfile.V4, CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, ContentEncryptionAlgorithm.AesGcmWithCommitment); var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial); // Use the client for PutObject and GetObject operations await encryptionClient.PutObjectAsync(new PutObjectRequest { BucketName = bucket, Key = objectKey, ContentBody = content }); ``` **Behavior:** Encrypts with commitment, only decrypts objects encrypted with commitment. Maximum security against key substitution attacks. ## Additional Configuration Examples This section provides additional examples for configuring V4 clients with different options during migration. ### Enabling Legacy Support To enable V4 clients to read objects encrypted by V1 and V2 clients, configure the client with a commitment policy that allows legacy decryption: ``` using Amazon.Extensions.S3.Encryption; using Amazon.Extensions.S3.Encryption.Primitives; // Configure V4 client to read V1/V2 objects var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT) { StorageMode = CryptoStorageMode.ObjectMetadata }; // This configuration allows: // - Encryption: With commitment (secure) // - Decryption: Both V2 (non-committing) and V4 (committing) objects ``` Use this configuration during migration when you need to decrypt objects encrypted by older clients while ensuring new objects are encrypted with enhanced security. ### Configuring Storage Method V4 supports two storage methods for encryption metadata. Choose the method that best fits your use case: **Object Metadata (Default)** ``` var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT) { StorageMode = CryptoStorageMode.ObjectMetadata }; // Encryption metadata is stored in S3 object metadata ``` **Instruction File** ``` var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT) { StorageMode = CryptoStorageMode.InstructionFile }; // Encryption metadata is stored in a separate S3 object (instruction file) ``` Use `InstructionFile` when you need to preserve object metadata for other purposes or when working with objects that have metadata size limitations. ### Configuring Commitment Policy Choose the appropriate commitment policy based on your security requirements and migration phase: **Migration Phase (V2 Compatibility)** ``` // For migration: encrypt without commitment, allow all decryption var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT); ``` **Transition Phase (Recommended)** ``` // For transition: encrypt with commitment, allow legacy decryption var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT); ``` **Full Security Phase** ``` // For maximum security: require commitment for both encryption and decryption var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT); ``` Start with `FORBID_ENCRYPT_ALLOW_DECRYPT` during initial migration, move to `REQUIRE_ENCRYPT_ALLOW_DECRYPT` for the transition phase, and finally use `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` when all clients have been upgraded and all objects have been re-encrypted with commitment.