# Configuring service clients in the AWS SDK for C\$1\$1
To programmatically access AWS services, the AWS SDK for C\$1\$1 uses a client class for each AWS service. For example, if your application needs to access Amazon EC2, your application creates an Amazon EC2 client object to interface with that service. You then use the service client to make requests to that AWS service.
To make a request to an AWS service, you must first create a service client. For each AWS service your code uses, it has its own library and its own dedicated type for interacting with it. The client exposes one method for each API operation exposed by the service.
There are many alternative ways to configure SDK behavior, but ultimately everything has to do with the behavior of service clients. Any configuration has no effect until a service client that is created from them is used.
You must establish how your code authenticates with AWS when you develop with AWS services. You must also set the AWS Region you want to use.
The [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/) also contains settings, features, and other foundational concepts common among many of the AWS SDKs.
**Topics**
+ [SDK configuration](sdkoptions.md)
+ [Client configuration externally](config-external.md)
+ [Client configuration in code](client-config.md)
+ [AWS Region](region.md)
+ [Credential providers](credproviders.md)
+ [CMake parameters](cmake-params.md)
+ [Logging](logging.md)
+ [HTTP](overriding-http-client.md)
+ [Controlling iostreams used by the `HttpClient` and the `AWSClient`](configuring-iostreams.md)
+ [Using a custom libcrypto](libcrypto.md)
# General configuration using `Aws::SDKOptions` in the AWS SDK for C\$1\$1
The [https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_s_d_k_options.html](https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_s_d_k_options.html) struct contains SDK configuration options. `Aws::SDKOptions` focuses on general SDK configuration, whereas the [`ClientConfiguration`](client-config.md) struct focuses on configuration of communicating with AWS services.
An instance of [https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_s_d_k_options.html](https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_s_d_k_options.html) is passed to the [`Aws::InitAPI` and `Aws::ShutdownAPI` methods](basic-use.md). The same instance should be sent to both methods.
The following samples demonstrate some of the available options.
+ Turn logging on using the default logger
```
Aws::SDKOptions options;
options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Info;
Aws::InitAPI(options);
{
// make your SDK calls here.
}
Aws::ShutdownAPI(options);
```
+ Override the default HTTP client factory
```
Aws::SDKOptions options;
options.httpOptions.httpClientFactory_create_fn = [](){
return Aws::MakeShared(
"ALLOC_TAG", arg1);
};
Aws::InitAPI(options);
{
// make your SDK calls here.
}
Aws::ShutdownAPI(options);
```
**Note**
`httpOptions` takes a closure (also called an anonymous function or lambda expression) rather than a `std::shared_ptr`. Each of the SDK factory functions operates in this manner because at the time at which the factory memory allocation occurs, the memory manager has not yet been installed. By passing a closure to the method, the memory manager will be called to perform the memory allocation when it is safe to do so. A simple technique to accomplish this procedure is by using a Lambda expression.
+ Use a global `SIGPIPE` handler
If you build the SDK for C\$1\$1 with curl and OpenSSL, you must specify a signal handler. If you don’t use your own custom signal handler, set `installSigPipeHandler` to `true`.
```
Aws::SDKOptions options;
options.httpOptions.installSigPipeHandler = true;
Aws::InitAPI(options);
{
// make your SDK calls here.
}
Aws::ShutdownAPI(options);
```
When `installSigPipeHandler` is `true`, the SDK for C\$1\$1 uses a handler that ignores `SIGPIPE` signals. For more information on `SIGPIPE`, see [Operation Error Signals](https://www.gnu.org/software/libc/manual/html_node/Operation-Error-Signals.html) on the GNU Operating System website. For more information on the curl handler, see [CURLOPT\$1NOSIGNAL explained](https://curl.se/libcurl/c/CURLOPT_NOSIGNAL.html) on the curl website.
The underlying libraries of curl and OpenSSL can send a `SIGPIPE` signal to notify when the remote side closes a connection. These signals must be handled by the application. For more information this curl functionality, see [libcurl thread safety](https://curl.se/libcurl/c/threadsafe.html) on the curl website. This behavior is not automatically built-in to the SDK because signal handlers are global for each application and the library is a dependency for the SDK.
# Configuring AWS SDK for C\$1\$1 service clients externally
Many configuration settings can be handled outside of your code. When configuration is handled externally, the configuration is applied across all of your applications. Most configuration settings can be set as either environment variables or in a separate shared AWS `config` file. The shared `config` file can maintain separate sets of settings, called profiles, to provide different configurations for different environments or tests.
Environment variables and shared `config` file settings are standardized and shared across AWS SDKs and tools to support consistent functionality across different programming languages and applications.
See the *AWS SDKs and Tools Reference Guide* to learn about configuring your application through these methods, plus details on each cross-sdk setting. To see all the all settings that the SDK can resolve from the environment variables or configuration files, see the [Settings reference](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) in the *AWS SDKs and Tools Reference Guide*.
To make a request to an AWS service, you first instantiate a client for that service. You can configure common settings for service clients such as timeouts, the HTTP client, and retry configuration.
Each service client requires an AWS Region and a credential provider. The SDK uses these values to send requests to the correct Region for your resources and to sign requests with the correct credentials. You can specify these values programmatically in code or have them automatically loaded from the environment.
The SDK has a series of places (or sources) that it checks in order to find a value for configuration settings.
1. Any explicit setting set in the code or on a service client itself takes precedence over anything else.
1. Environment variables
+ For details on setting environment variables, see [environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) in the *AWS SDKs and Tools Reference Guide*.
+ Note that you can configure environment variables for a shell at different levels of scope: system-wide, user-wide, and for a specific terminal session.
1. Shared `config` and `credentials` files
+ For details on setting up these files, see the [Shared `config` and `credentials` files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*.
1. Any default value provided by the SDK source code itself is used last.
+ Some properties, such as Region, don't have a default. You must specify them either explicitly in code, in an environment setting, or in the shared `config` file. If the SDK can't resolve required configuration, API requests can fail at runtime.
**Note**
To see all the all settings that the SDK can resolve from the environment variables or configuration files, see the [Settings reference](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) in the *AWS SDKs and Tools Reference Guide*.
# Configuring AWS SDK for C\$1\$1 service clients in code
When configuration is handled directly in code, the configuration scope is limited to the application that uses that code. Within that application, there are options for the global configuration of all service clients, the configuration to all clients of a certain AWS service type, or the configuration to a specific service client instance.
The AWS SDK for C\$1\$1 includes AWS service client classes that provide functionality for interacting with the AWS services that you use in your application. In the SDK for C\$1\$1, you can change the default client configuration, which is helpful when you want to do things like:
+ Connect to the Internet through proxy
+ Change HTTP transport settings, such as connection timeout and request retries
+ Specify TCP socket buffer size hints
`ClientConfiguration` is a structure in the SDK for C\$1\$1 that you can instantiate and utilize in your code. The following snippet illustrates using this class to access Amazon S3 through a proxy.
```
Aws::Client::ClientConfiguration clientConfig;
clientConfig.proxyHost = "localhost";
clientConfig.proxyPort = 1234;
clientConfig.proxyScheme = Aws::Http::Scheme::HTTPS;
Aws::S3::S3Client(clientConfig);
```
## Configuration variable declarations
The `ClientConfiguration` struct declares the following member variables:
```
Aws::String accountId;
Aws::String accountIdEndpointMode = "preferred";
bool allowSystemProxy = false;
Aws::String appId;
Aws::String caPath;
Aws::String caFile;
struct {
RequestChecksumCalculation requestChecksumCalculation = RequestChecksumCalculation::WHEN_SUPPORTED;
ResponseChecksumValidation responseChecksumValidation = ResponseChecksumValidation::WHEN_SUPPORTED;
} checksumConfig;
ProviderFactories configFactories = ProviderFactories::defaultFactories;
long connectTimeoutMs = 1000;
struct CredentialProviderConfiguration {
Aws::String profile;
Aws::String region;
struct {
long metadataServiceNumAttempts = 1;
long metadataServiceTimeout = 1;
std::shared_ptr imdsRetryStrategy;
bool disableImdsV1;
bool disableImds;
} imdsConfig;
struct STSCredentialsCredentialProviderConfiguration {
Aws::String roleArn;
Aws::String sessionName;
Aws::String tokenFilePath;
std::chrono::milliseconds retrieveCredentialsFutureTimeout = std::chrono::seconds(10);
} stsCredentialsProviderConfig;
} credentialProviderConfig;
bool disableExpectHeader = false;
bool disableIMDS = false;
bool disableImdsV1 = false;
bool enableClockSkewAdjustment = true;
Aws::Crt::Optional enableEndpointDiscovery;
bool enableHostPrefixInjection = true;
bool enableHttpClientTrace = false;
bool enableTcpKeepAlive = true;
Aws::String endpointOverride;
std::shared_ptr executor = nullptr;
FollowRedirectsPolicy followRedirects;
Aws::Http::TransferLibType httpLibOverride;
Aws::Http::TransferLibPerformanceMode httpLibPerfMode = Http::TransferLibPerformanceMode::LOW_LATENCY;
long httpRequestTimeoutMs = 0;
unsigned long lowSpeedLimit = 1;
unsigned maxConnections = 25;
Aws::Utils::Array nonProxyHosts;
Aws::String profileName;
Aws::String proxyCaFile;
Aws::String proxyCaPath;
Aws::Http::Scheme proxyScheme;
Aws::String proxyHost;
unsigned proxyPort = 0;
Aws::String proxyUserName;
Aws::String proxyPassword;
Aws::String proxySSLCertPath;
Aws::String proxySSLCertType;
Aws::String proxySSLKeyPath;
Aws::String proxySSLKeyType;
Aws::String proxySSLKeyPassword;
std::shared_ptr readRateLimiter = nullptr;
Aws::String region;
Aws::Client::RequestCompressionConfig requestCompressionConfig;
long requestTimeoutMs = 0;
std::shared_ptr retryStrategy = nullptr;
Aws::Http::Scheme scheme;
unsigned long tcpKeepAliveIntervalMs = 30000;
std::shared_ptr telemetryProvider;
Aws::String userAgent;
bool useDualStack = false;
bool useFIPS = false;
bool verifySSL = true;
Aws::Http::Version version = Http::Version::HTTP_VERSION_2TLS;
struct WinHTTPOptions {
bool useAnonymousAuth = false;
} winHTTPOptions;
std::shared_ptr writeRateLimiter = nullptr;
static Aws::String LoadConfigFromEnvOrProfile(const Aws::String& envKey, const Aws::String& profile,
const Aws::String& profileProperty, const Aws::Vector& allowedValues,
const Aws::String& defaultValue);
```
## Configuration variable descriptions
The following list describes the `ClientConfiguration` member variables that you can use to customize client behavior.
**accountId**
Specifies the AWS account ID for account-based endpoint routing. Use the format 111122223333. Account-based endpoint routing improves request performance for some services.
**accountIdEndpointMode**
Controls account-based endpoint routing behavior. Valid values are "required", "disabled", or "preferred". The default value is "preferred". Set to "disabled" to turn off account-based endpoint routing when necessary.
**allowSystemProxy**
Controls whether the HTTP client discovers system proxy settings. The default setting is false. Set to true to enable automatic proxy discovery.
**appId**
Specifies an optional application-specific identifier. When set, this value is appended to the `User-Agent` header in the format `App/{appId}`. You can set this value using the `AWS_SDK_UA_APP_ID` environment variable or the `sdk_ua_app_id` shared config profile attribute.
**caPath, caFile**
Instructs the HTTP client where to find your SSL certificate trust store. An example trust store might be a directory prepared with the OpenSSL `c_rehash` utility. These variables should not need to be set unless your environment uses symlinks. These variables have no effect on Windows and macOS systems.
**checksumConfig**
Contains checksum calculation and validation settings. Includes `requestChecksumCalculation` and `responseChecksumValidation` with default value WHEN\$1SUPPORTED.
**configFactories**
Specifies factory methods for initializing client utility classes such as `Executor` and `RetryStrategy`. Uses default factories unless overridden.
**requestTimeoutMs and connectTimeoutMs**
Specifies the amount of time in milliseconds to wait before timing out an HTTP request. For example, consider increasing these times when transferring large files.
**credentialProviderConfig**
Contains configuration settings for credential providers. Use this structure to customize how the SDK obtains AWS credentials.
**disableExpectHeader**
Applicable only for CURL HTTP clients. By default, CURL adds an "Expect: 100-Continue" header in an HTTP request to avoid sending the HTTP payload in situations where the server responds with an error immediately after receiving the header. This behavior can save a round-trip and is useful in situations where the payload is small and network latency is relevant. The variable's default setting is false. If set to true, CURL is instructed to send both the HTTP request header and body payload together.
**disableIMDS**
Controls whether Instance Metadata Service (IMDS) calls are disabled. The default setting is false. Set to true to disable IMDS calls when running outside of EC2 instances.
**disableImdsV1**
Controls whether IMDSv1 calls are disabled while allowing IMDSv2. The default setting is false. Set to true to disable only IMDSv1 calls for enhanced security.
**enableClockSkewAdjustment**
Controls whether clock skew is adjusted after each HTTP attempt. The default setting is false.
**enableEndpointDiscovery**
Controls whether endpoint discovery is used. By default, regional or overridden endpoints are used. To enable endpoint discovery, set the variable to true.
**enableHostPrefixInjection**
Controls whether the HTTP host adds a "data-" prefix to DiscoverInstances requests. By default, this behavior is enabled. To disable it, set the variable to false.
**enableHttpClientTrace**
Controls whether HTTP client tracing is enabled for debugging purposes. The default setting is false. Set to true to enable detailed HTTP request and response logging.
**enableTcpKeepAlive**
Controls whether to send TCP keep-alive packets. The default setting is true. Use in conjunction with the `tcpKeepAliveIntervalMs` variable. This variable is not applicable for WinINet and the IXMLHTTPRequest2 client.
**endpointOverride**
Specifies an overriding HTTP endpoint with which to communicate with a service.
**executor**
References the implementation of the asynchronous Executor handler. The default behavior is to create and detach a thread for each async call. To change this behavior, implement a subclass of the `Executor` class and assign an instance to this variable.
**followRedirects**
Controls the behavior when handling HTTP 300 redirect codes.
**httpLibOverride**
Specifies the HTTP implementation returned by the default HTTP factory. The default HTTP client for Windows is WinHTTP. The default HTTP client for all other platforms is CURL.
**httpLibPerfMode**
Specifies the HTTP library performance mode. The default setting is LOW\$1LATENCY. You can adjust this setting to optimize for different performance characteristics.
**httpRequestTimeoutMs**
Specifies the HTTP request timeout in milliseconds. The default value is 0 (no timeout). Consider increasing this value when transferring large files.
**lowSpeedLimit**
Specifies the minimum allowed transfer speed in bytes per second. If the transfer speed falls below the specified speed, the transfer operation is aborted. The default setting is 1 byte/second. This variable is applicable only for CURL clients.
**maxConnections**
Specifies the maximum number of HTTP connections to a single server. The default value is 25. No maximum allowed value exists other than what your bandwidth can reasonably support.
**nonProxyHosts**
Specifies an array of hostnames that should bypass proxy settings. Use this setting to exclude specific hosts from proxy configuration.
**profileName**
Specifies the AWS profile name to use for configuration. The SDK loads settings from the specified profile in the AWS configuration file.
**proxyCaFile**
Specifies the path to the certificate authority file for proxy connections when it differs from the default.
**proxyCaPath**
Specifies the path to the certificate authority trust store for proxy connections when it differs from the default.
**proxyScheme, proxyHost, proxyPort, proxyUserName, and proxyPassword**
Used to set up and configure a proxy for all communications with AWS. Examples of when this functionality might be useful include debugging in conjunction with the Burp suite, or using a proxy to connect to the Internet.
**proxySSLCertPath**
Specifies the path to the SSL certificate file for proxy connections that require client certificates.
**proxySSLCertType**
Specifies the SSL certificate type for proxy connections. Common types include PEM and DER.
**proxySSLKeyPassword**
Specifies the password for the SSL private key used in proxy connections when the key is password-protected.
**proxySSLKeyPath**
Specifies the path to the SSL private key file for proxy connections that require client certificates.
**proxySSLKeyType**
Specifies the SSL private key type for proxy connections. Common types include PEM and DER.
**writeRateLimiter and readRateLimiter**
References to the implementations of read and write rate limiters which are used to throttle the bandwidth used by the transport layer. By default, the read and write rates are not throttled. To introduce throttling, implement a subclass of the `RateLimiterInterface` and assign an instance to these variables.
**region**
Specifies the AWS Region to use, such as *us-east-1*. By default, the Region used is the default Region configured in the applicable AWS credentials.
**requestCompressionConfig**
Contains configuration settings for request compression. Use this structure to control when and how requests are compressed before transmission.
**retryStrategy**
References the implementation of the retry strategy. The default strategy implements an exponential backoff policy. To perform a different strategy, implement a subclass of the `RetryStrategy` class and assign an instance to this variable.
**scheme**
Specifies the URI addressing scheme, either HTTP or HTTPS. The default scheme is HTTPS.
**tcpKeepAliveIntervalMs**
Specifies the time interval in milliseconds at which to send a keep-alive packet over a TCP connection. The default interval is 30 seconds. The minimum setting is 15 seconds. This variable is not applicable for WinINet and the IXMLHTTPRequest2 client.
**telemetryProvider**
References the telemetry provider implementation for collecting metrics and tracing data. Configure this setting to enable observability features.
**userAgent**
For internal use only. Do not change the setting of this variable.
**useDualStack**
Controls whether to use dual stack IPv4 and IPv6 endpoints. Note that not all AWS services support IPv6 in all Regions.
**useFIPS**
Controls whether to use Federal Information Processing Standards (FIPS) 140-2 validated cryptographic modules. The default setting is false. Set to true when FIPS compliance is required.
**verifySSL**
Controls whether to verify SSL certificates. By default SSL certificates are verified. To disable verification, set the variable to false.
**version**
Specifies the HTTP version to use for requests. The default setting is HTTP\$1VERSION\$12TLS (HTTP/2 over TLS).
**winHTTPOptions**
Contains Windows-specific HTTP configuration options. Includes useAnonymousAuth with default setting false.
# Setting the AWS Region for the AWS SDK for C\$1\$1
You can access AWS services that operate in a specific geographic area by using AWS Regions. This can be useful both for redundancy and to keep your data and applications running close to where you and your users access them.
**Important**
Most resources reside in a specific AWS Region and you must supply the correct Region for the resource when using the SDK.
For examples on how to set the default region through the shared AWS `config` file or environment variables, see [AWS Region](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) in the *AWS SDKs and Tools Reference Guide*.
You must set a default AWS Region for the AWS SDK for C\$1\$1 to use for AWS requests. This default is used for any SDK service method calls that aren't specified with a Region. In the SDK for C\$1\$1, you can also set the default region using the [Client configuration in code](client-config.md).
# Using AWS SDK for C\$1\$1 credential providers
All requests to AWS must be cryptographically signed by using credentials issued by AWS. At runtime, the SDK retrieves configuration values for credentials by checking several locations.
Authentication with AWS can be handled outside of your codebase. Many authentication methods can be automatically detected, used, and refreshed by the SDK using the credential provider chain.
For guided options for getting started on AWS authentication for your project, see [Authentication and access](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) in the *AWS SDKs and Tools Reference Guide*.
## The credential provider chain
If you don't explicitly specify a credential provider when constructing a client, the SDK for C\$1\$1 uses a credential provider chain that checks a series of places where you can supply credentials. Once the SDK finds credentials in one of these locations, the search stops.
### Credential retrieval order
All SDKs have a series of places (or sources) that they check in order to get valid credentials to use to make a request to an AWS service. After valid credentials are found, the search is stopped. This systematic search is called the credential provider chain.
For each step in the chain, there are different ways to set the values. Setting values directly in code always takes precedence, followed by setting as environment variables, and then in the shared AWS `config` file. For more information, see [Precedence of settings](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#precedenceOfSettings) in the *AWS SDKs and Tools Reference Guide*.
The SDK attempts to load credentials from the `[default]` profile in the shared AWS `config` and `credentials` files. You can use the `AWS_PROFILE` environment variable to choose a named profile you want the SDK to load instead of using `[default]`. The `config` and `credentials` files are shared by AWS SDKs and tools. The *AWS SDKs and Tools Reference Guide* has information on SDK configuration settings used by all AWS SDKs and the AWS CLI. To learn more about how to configure the SDK through the shared AWS `config` file, see [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). To learn more about how to configure the SDK through setting environment variables, see [Environment variables support](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html).
To authenticate with AWS, the SDK for C\$1\$1 checks the credential providers in the following order.
1. **AWS access keys (temporary and long-term credentials)**
The SDK attempts to load credentials from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables, or from the shared AWS `credentials` file.
+ For guidance on configuring this provider, see [AWS access keys](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html) in the *AWS SDKs and Tools Reference Guide*.
+ For details on SDK configuration properties for this provider, see [AWS access keys](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
1. **AWS STS web identity**
When creating mobile applications or client-based web applications that require access to AWS, AWS Security Token Service (AWS STS) returns a set of temporary security credentials for federated users who are authenticated through a public identity provider (IdP).
+ When you specify this in a profile, the SDK or tool attempts to retrieve temporary credentials using AWS STS `AssumeRoleWithWebIdentity` API method. For details on this method, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) in the *AWS Security Token Service API Reference*.
+ For guidance on configuring this provider, see [Federate with web identity or OpenID Connect](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity) in the *AWS SDKs and Tools Reference Guide*.
+ For details on SDK configuration properties for this provider, see [Assume role credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
1. **IAM Identity Center**
If you use IAM Identity Center to authenticate, this is when the SDK for C\$1\$1 uses the single sign-on token that was set up by running AWS CLI command `aws sso login`. The SDK uses the temporary credentials that the IAM Identity Center exchanged for a valid token. The SDK then uses the temporary credentials when it calls AWS services. For detailed information about this process, see [Understand SDK credential resolution for AWS services](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres) in the *AWS SDKs and Tools Reference Guide*.
+ For guidance on configuring this provider, see [IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) in the *AWS SDKs and Tools Reference Guide*.
+ For details on SDK configuration properties for this provider, see [IAM Identity Center credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
1. **Login credential identity resolver with AWS Signin**
If you use AWS sign in and console credentials to authenticate, this is when the SDK for C\$1\$1 uses the console credentials set up by running `aws login` or `aws login --profile` in the CLI. The SDK uses these credentials when it calls AWS services.
+ For detailed information about this process, see [Login for AWS local development using console credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) in the *AWS SDKs and Tools Reference Guide*.
1. **External process provider**
This provider can be used to provide custom implementations, such as retrieving credentials from an on-premises credentials store or integrating with your on-premises identify provider.
+ For guidance on one way to configure this provider, see [IAM Roles Anywhere](https://docs.aws.amazon.com/sdkref/latest/guide/access-rolesanywhere.html) in the *AWS SDKs and Tools Reference Guide*.
+ For details on SDK configuration properties for this provider, see [Process credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
1. **Amazon ECS and Amazon EKS container credentials **
Your Amazon Elastic Container Service tasks and Kubernetes service accounts can have an IAM role associated with them. The permissions granted in the IAM role are assumed by the containers running in the task or containers of the pod. This role allows your SDK for C\$1\$1 application code (on the container) to use other AWS services.
The SDK attempts to retrieve credentials from the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or `AWS_CONTAINER_CREDENTIALS_FULL_URI` environment variables, which can be set automatically by Amazon ECS and Amazon EKS.
+ For details on setting up this role for Amazon ECS, see [ Amazon ECS task IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) in the *Amazon Elastic Container Service Developer Guide*.
+ For Amazon EKS setup information, see [Setting up the Amazon EKS Pod Identity Agent](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) in the **Amazon EKS User Guide**.
+ For details on SDK configuration properties for this provider, see [Container credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
1. **Amazon EC2 Instance Metadata Service **
Create an IAM role and attach it to your instance. The SDK for C\$1\$1 application on the instance attempts to retrieve the credentials provided by the role from the instance metadata.
+ For details on setting up this role and using metadata, [IAM roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) and [Work with instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) in the *Amazon EC2 User Guide*.
+ For details on SDK configuration properties for this provider, see [IMDS credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html) in the *AWS SDKs and Tools Reference Guide*.
The credential provider chain can be reviewed at [https://github.com/aws/aws-sdk-cpp/blob/main/src/aws-cpp-sdk-core/source/auth/AWSCredentialsProviderChain.cpp#L43-L86](https://github.com/aws/aws-sdk-cpp/blob/main/src/aws-cpp-sdk-core/source/auth/AWSCredentialsProviderChain.cpp#L43-L86) in the AWS SDK for C\$1\$1 source code on GitHub.
If you followed the recommended approach for new users to get started, you set up AWS Login Credentials authentication during [Authenticating with AWS using AWS SDK for C\$1\$1](credentials.md) of the Getting started topic. Other authentication methods are useful for different situations. To avoid security risks, we recommend always using short-term credentials. For other authentication method procedures, see [Authentication and access](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) in the *AWS SDKs and Tools Reference Guide*.
## Explicit credential provider
Instead of relying on the credential provider chain to detect your authentication method, you can specify a specific credential provider that the SDK should use. You can do this by providing credentials in your service client's constructor.
The following example creates an Amazon Simple Storage Service client by directly providing temporary access credentials instead of using the chain.
```
SDKOptions options;
Aws::InitAPI(options);
{
const auto cred_provider = Aws::MakeShared("TestAllocationTag",
"awsAccessKeyId",
"awsSecretKey",
"sessionToken");
S3Client client{cred_provider};
}
Aws::ShutdownAPI(options);
```
## Identity caching
The SDK will cache credentials and other identity types such as SSO tokens. By default, the SDK uses a lazy cache implementation that loads credentials upon first request, caches them, and then attempts to refresh them during another request when they are close to expiring. Clients created from the same [https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_client_1_1_client_configuration.html](https://docs.aws.amazon.com/sdk-for-cpp/latest/api/aws-cpp-sdk-core/html/struct_aws_1_1_client_1_1_client_configuration.html) share a cache.
# CMake parameters for building the AWS SDK for C\$1\$1
Use the [CMake](https://cmake.org/) parameters listed in this section to customize how your SDK builds.
You can set these options with CMake GUI tools or the command line by using *-D*. For example:
```
cmake -DENABLE_UNITY_BUILD=ON -DREGENERATE_CLIENTS=1
```
## General CMake Variables and Options
The following are general ** `cmake` ** variables and options that affect the build process of the SDK source code.
**Note**
Use these parameters when building the SDK source code for the SDK for C\$1\$1 itself.
**Topics**
+ [ADD\$1CUSTOM\$1CLIENTS](#cmake-add-custom-clients)
+ [AUTORUN\$1UNIT\$1TESTS](#cmake-AUTORUN_UNIT_TESTS)
+ [AWS\$1AUTORUN\$1LD\$1LIBRARY\$1PATH](#cmake-AWS_AUTORUN_LD_LIBRARY_PATH)
+ [AWS\$1SDK\$1WARNINGS\$1ARE\$1ERRORS](#cmake-AWS_SDK_WARNINGS_ARE_ERRORS)
+ [AWS\$1USE\$1CRYPTO\$1SHARED\$1LIBS](#cmake-use-crypto)
+ [AWS\$1TEST\$1REGION](#cmake-AWS_TEST_REGION)
+ [BUILD\$1BENCHMARKS](#cmake-BUILD_BENCHMARKS)
+ [BUILD\$1DEPS](#cmake-BUILD_DEPS)
+ [BUILD\$1ONLY](#cmake-build-only)
+ [BUILD\$1OPTEL](#cmake-BUILD_OPTEL)
+ [BUILD\$1SHARED\$1LIBS](#cmake-build-shared-libs)
+ [BYPASS\$1DEFAULT\$1PROXY](#cmake-BYPASS_DEFAULT_PROXY)
+ [CPP\$1STANDARD](#cmake-cpp-standard)
+ [CURL\$1INCLUDE\$1DIR](#cmake-curl-include-dir)
+ [CURL\$1LIBRARY](#cmake-curl-library)
+ [CUSTOM\$1MEMORY\$1MANAGEMENT](#cmake-custom-memory-management)
+ [DISABLE\$1INTERNAL\$1IMDSV1\$1CALLS](#cmake-DISABLE_INTERNAL_IMDSV1_CALLS)
+ [ENABLE\$1ADDRESS\$1SANITIZER](#cmake-ENABLE_ADDRESS_SANITIZER)
+ [ENABLE\$1CURL\$1LOGGING](#cmake-enable-curl-logging)
+ [ENABLE\$1HTTP\$1CLIENT\$1TESTING](#cmake-ENABLE_HTTP_CLIENT_TESTING)
+ [ENABLE\$1RTTI](#cmake-enable-rtti)
+ [ENABLE\$1TESTING](#cmake-enable-testing)
+ [ENABLE\$1UNITY\$1BUILD](#cmake-enable-unity-build)
+ [ENABLE\$1VIRTUAL\$1OPERATIONS](#cmake-virtual-op)
+ [ENABLE\$1ZLIB\$1REQUEST\$1COMPRESSION](#cmake-ENABLE_ZLIB_REQUEST_COMPRESSION)
+ [FORCE\$1CURL](#cmake-force-curl)
+ [FORCE\$1SHARED\$1CRT](#cmake-force-shared-crt)
+ [G](#cmake-g)
+ [MINIMIZE\$1SIZE](#cmake-minimize-size)
+ [NO\$1ENCRYPTION](#cmake-no-encryption)
+ [NO\$1HTTP\$1CLIENT](#cmake-no-http-client)
+ [REGENERATE\$1CLIENTS](#cmake-regenerate-clients)
+ [REGENERATE\$1DEFAULTS](#cmake-regenerate-defaults)
+ [SIMPLE\$1INSTALL](#cmake-simple-install)
+ [TARGET\$1ARCH](#cmake-target-arch)
+ [USE\$1CRT\$1HTTP\$1CLIENT](#cmake-USE_CRT_HTTP_CLIENT)
+ [USE\$1IXML\$1HTTP\$1REQUEST\$12](#cmake-USE_IXML_HTTP_REQUEST_2)
+ [USE\$1OPENSSL](#cmake-use-openssl)
+ [USE\$1TLS\$1V1\$12](#cmake-USE_TLS_V1_2)
+ [USE\$1TLS\$1V1\$13](#cmake-USE_TLS_V1_3)
### ADD\$1CUSTOM\$1CLIENTS
Builds any arbitrary clients based on the API definition. Place your definition in the `code-generation/api-definitions` folder, and then pass this argument to ** `cmake` **. The ** `cmake` ** configure step generates your client and includes it as a subdirectory in your build. This is particularly useful to generate a C\$1\$1 client for using one of your [API Gateway](https://aws.amazon.com/api-gateway) services. For example:
```
-DADD_CUSTOM_CLIENTS="serviceName=myCustomService,version=2015-12-21;serviceName=someOtherService,version=2015-08-15"
```
**Note**
To use the `ADD_CUSTOM_CLIENTS` parameter, you must have [Python 2.7](https://www.python.org/downloads/), Java ([JDK 1.8\$1](http://openjdk.java.net/install/)), and [Maven](https://maven.apache.org/) installed and in your `PATH`.
### AUTORUN\$1UNIT\$1TESTS
If `ON`, run unit tests automatically after building.
Values
*ON* \$1 *OFF*
Default
*ON*
### AWS\$1AUTORUN\$1LD\$1LIBRARY\$1PATH
The path to append into LD\$1LIBRARY\$1PATH for unit tests autorun by CMake. Set this path if custom runtime libraries are required for overridden dependencies.
Values
*String.*
Default
*N/A*
### AWS\$1SDK\$1WARNINGS\$1ARE\$1ERRORS
If `ON`, treat compiler warnings as errors. Try turning this `OFF` if observing errors on a new or uncommon compiler.
Values
*ON* \$1 *OFF*
Default
*ON*
### AWS\$1USE\$1CRYPTO\$1SHARED\$1LIBS
Forces FindCrypto to use a shared crypto library if found. Turn this `OFF` to use [BUILD\$1SHARED\$1LIBS](#cmake-build-shared-libs)'s setting instead.
Values
*ON* \$1 *OFF*
Default
*OFF*
### AWS\$1TEST\$1REGION
The AWS Region to use for integration tests.
Values
*String.*
Default
*N/A*
### BUILD\$1BENCHMARKS
If `ON`, build the benchmark executable.
Values
*ON* \$1 *OFF*
Default
*OFF*
### BUILD\$1DEPS
If `ON`, build third-party dependencies.
Values
*ON* \$1 *OFF*
Default
*ON*
### BUILD\$1ONLY
Builds only the clients you want to use. If set to a high-level SDK such as `aws-cpp-sdk-transfer`, *BUILD\$1ONLY* resolves any low-level client dependencies. It also builds integration and unit tests related to the projects you select, if they exist. This is a list argument, with values separated by semicolon (`;`) characters. For example:
```
-DBUILD_ONLY="s3;cognito-identity"
```
**Note**
The core SDK module, `aws-sdk-cpp-core`, is *always* built, regardless of the value of the *BUILD\$1ONLY* parameter.
### BUILD\$1OPTEL
If `ON`, builds the open telemetry implementation of tracing.
Values
*ON* \$1 *OFF*
Default
*OFF*
### BUILD\$1SHARED\$1LIBS
A built-in CMake option, re-exposed here for visibility. If `ON`, it builds shared libraries; otherwise, it builds only static libraries.
**Note**
To dynamically link to the SDK, you must define the `USE_IMPORT_EXPORT` symbol for all build targets using the SDK.
Values
*ON* \$1 *OFF*
Default
*ON*
### BYPASS\$1DEFAULT\$1PROXY
If `ON`, bypass the machine's default proxy settings when using IXmlHttpRequest2.
Values
*ON* \$1 *OFF*
Default
*ON*
### CPP\$1STANDARD
Specifies a custom C\$1\$1 standard for use with C\$1\$1 14 and 17 code bases.
Values
*11* \$1 *14* \$1 *17*
Default
*11*
### CURL\$1INCLUDE\$1DIR
Path to curl include directory containing `libcurl` headers.
Values
*String path to selected `include` directory. For example, `D:/path/to/dir/with/curl/include`.*
Default
*N/A*
### CURL\$1LIBRARY
Path to curl library file to link against. This library can be a static library or an import library, depending on the needs of your application.
Values
*String path to the curl library file. For example, `D:/path/to/static/libcur/file/ie/libcurl.lib.a`.*
Default
*N/A*
### CUSTOM\$1MEMORY\$1MANAGEMENT
To use a custom memory manager, set the value to `1`. You can install a custom allocator so that all STL types use the custom allocation interface. If you set the value `0`, you still might want to use the STL template types to help with DLL safety on Windows.
If static linking is `ON`, custom memory management defaults to *off* (`0`). If dynamic linking is `ON`, custom memory management defaults to *on* (`1`) and avoids cross-DLL allocation and deallocation.
**Note**
To prevent linker mismatch errors, you must use the same value (`0` or `1`) throughout your build system.
To install your own memory manager to handle allocations made by the SDK, you must set `-DCUSTOM_MEMORY_MANAGEMENT` and define `USE_AWS_MEMORY_MANAGEMENT` for all build targets that depend on the SDK.
### DISABLE\$1INTERNAL\$1IMDSV1\$1CALLS
If `ON`, no internal calls are made to the V1 API of the [Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). If `OFF`, IMDSv2 calls will fallback to using IMDSv1 if the IMDSv2 call fails. For more information on IMDSv1 and IMDSv2, see [Use the Instance Metadata Service to access instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) in the *Amazon EC2 User Guide*.
Values
*ON* \$1 *OFF*
Default
*OFF*
### ENABLE\$1ADDRESS\$1SANITIZER
If `ON`, turns on Address Sanitizer for gcc or clang.
Values
*ON* \$1 *OFF*
Default
*OFF*
### ENABLE\$1CURL\$1LOGGING
If `ON`, pipe the internal log for curl to the SDK logger.
Values
*ON* \$1 *OFF*
Default
*OFF*
### ENABLE\$1HTTP\$1CLIENT\$1TESTING
If `ON`, build and run corresponding HTTP client test suites.
Values
*ON* \$1 *OFF*
Default
*OFF*
### ENABLE\$1RTTI
Controls whether the SDK is built to enable run-time type information (RTTI).
Values
*ON* \$1 *OFF*
Default
*ON*
### ENABLE\$1TESTING
Controls whether unit and integration test projects are built during the SDK build.
Values
*ON* \$1 *OFF*
Default
*ON*
### ENABLE\$1UNITY\$1BUILD
If `ON`, most SDK libraries are built as a single, generated `.cpp` file. This can significantly reduce static library size and speed up compilation time.
Values
*ON* \$1 *OFF*
Default
*OFF*
### ENABLE\$1VIRTUAL\$1OPERATIONS
This parameter usually works together with `REGENERATE_CLIENTS` for code generation.
If `ENABLE_VIRTUAL_OPERATIONS` is `ON` and `REGENERATE_CLIENTS` is `ON`, operation-related functions in service clients will be marked as `virtual`.
If `ENABLE_VIRTUAL_OPERATIONS` is `OFF` and `REGENERATE_CLIENTS` is `ON`, `virtual` won't be added to operation functions and service client classes will be marked as `final`.
If `ENABLE_VIRTUAL_OPERATIONS` is `OFF`, the SDK will also add `-ffunction-sections` and `-fdata-sections` compiler flags for gcc and clang when compiling.
For more information, see [CMake Parameters](https://github.com/aws/aws-sdk-cpp/blob/main/docs/CMake_Parameters.md#enable_virtual_operations) on GitHub.
Values
*ON* \$1 *OFF*
Default
*ON*
### ENABLE\$1ZLIB\$1REQUEST\$1COMPRESSION
For services that support it, request content will be compressed. On by default if dependency is available.
Values
*ON* \$1 *OFF*
Default
*ON*
### FORCE\$1CURL
Windows only. If `ON`, forces usage of the curl client instead of the default [WinHTTP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa382925%28v=vs.85%29.aspx) data transfer provider.
Values
*ON* \$1 *OFF*
Default
*OFF*
### FORCE\$1SHARED\$1CRT
If `ON`, the SDK links to the C runtime *dynamically*; otherwise, it uses the *BUILD\$1SHARED\$1LIBS* setting (sometimes necessary for backward compatibility with earlier versions of the SDK).
Values
*ON* \$1 *OFF*
Default
*ON*
### G
Generates build artifacts, such as Visual Studio solutions and Xcode projects.
For example, on Windows:
```
-G "Visual Studio 12 Win64"
```
For more information, see the CMake documentation for your platform.
### MINIMIZE\$1SIZE
A superset of [ENABLE\$1UNITY\$1BUILD](#cmake-enable-unity-build). If `ON`, this option turns on *ENABLE\$1UNITY\$1BUILD* and additional binary size reduction settings.
Values
*ON* \$1 *OFF*
Default
*OFF*
### NO\$1ENCRYPTION
If `ON`, prevents the default platform-specific cryptography implementation from being built into the library. Turn this *ON* to inject your own cryptography implementation.
Values
*ON* \$1 *OFF*
Default
*OFF*
### NO\$1HTTP\$1CLIENT
If `ON`, prevents the default platform-specific HTTP client from being built into the library. If *ON*, you will need to provide your own platform-specific HTTP client implementation.
Values
*ON* \$1 *OFF*
Default
*OFF*
### REGENERATE\$1CLIENTS
If `ON`, this parameter deletes all generated code and generates the client directories from the `code-generation/api-definitions` folder. For example:
```
-DREGENERATE_CLIENTS=1
```
**Note**
To use the `REGENERATE_CLIENTS` parameter, you must have [Python 2.7](https://www.python.org/downloads/), Java ([JDK 1.8\$1](http://openjdk.java.net/install/)), and [Maven](https://maven.apache.org/) installed and in your `PATH`.
### REGENERATE\$1DEFAULTS
If `ON`, this parameter deletes all generated defaults code and generates it again from the `code-generation/defaults` folder. For example:
```
-DREGENERATE_DEFAULTS=1
```
**Note**
To use the `REGENERATE_DEFAULTS` parameter, you must have [Python 2.7](https://www.python.org/downloads/), Java ([JDK 1.8\$1](http://openjdk.java.net/install/)), and [Maven](https://maven.apache.org/) installed and in your `PATH`.
### SIMPLE\$1INSTALL
If `ON`, the install process does not insert platform-specific intermediate directories underneath `bin/` and `lib/`. Turn `OFF` if you need to make multiplatform releases under a single install directory.
Values
*ON* \$1 *OFF*
Default
*ON*
### TARGET\$1ARCH
To cross-compile or build for a mobile platform, you must specify the target platform. By default, the build detects the host operating system and builds for the detected operating system.
**Note**
When *TARGET\$1ARCH* is *ANDROID*, additional options are available. See [Android CMake Variables and Options](#cmake-android-variables).
Values
*WINDOWS* \$1 *LINUX* \$1 *APPLE* \$1 *ANDROID*
### USE\$1CRT\$1HTTP\$1CLIENT
If `ON`, use the common runtime HTTP client, and the legacy systems such as WinHttp and libcurl are not built or included.
Values
*ON* \$1 *OFF*
Default
*OFF*
### USE\$1IXML\$1HTTP\$1REQUEST\$12
Windows only. If `ON`, use the com object IXmlHttpRequest2 for the HTTP stack.
Values
*ON* \$1 *OFF*
Default
*OFF*
### USE\$1OPENSSL
If `ON`, the SDK builds using OpenSSL; otherwise, it uses [https://github.com/awslabs/aws-lc](https://github.com/awslabs/aws-lc). `AWS-LC` is a general-purpose cryptographic library maintained by the AWS Cryptography team for AWS and their customers. Turning `OFF` the parameter installs `AWS-LC` as replacement of OpenSSL in the system default directory. Don't use if you already have an OpenSSL installation in your system.
Values
*ON* \$1 *OFF*
Default
*ON*
### USE\$1TLS\$1V1\$12
If `ON`, the HTTP client enforces TLS 1.2.
Values
*ON* \$1 *OFF*
Default
*ON*
### USE\$1TLS\$1V1\$13
If `ON`, the HTTP client enforces TLS 1.3.
Values
*ON* \$1 *OFF*
Default
*OFF*
## Android CMake Variables and Options
Use the following variables when you are creating an Android build of the SDK (when [TARGET\$1ARCH](#cmake-target-arch) is set to *ANDROID*).
**Topics**
+ [ANDROID\$1ABI](#cmake-android-abi)
+ [ANDROID\$1BUILD\$1CURL](#cmake-ANDROID_BUILD_CURL)
+ [ANDROID\$1BUILD\$1OPENSSL](#cmake-ANDROID_BUILD_OPENSSL)
+ [ANDROID\$1BUILD\$1ZLIB](#cmake-ANDROID_BUILD_ZLIB)
+ [ANDROID\$1NATIVE\$1API\$1LEVEL](#cmake-android-native-api-level)
+ [ANDROID\$1STL](#cmake-android-stl)
+ [ANDROID\$1TOOLCHAIN\$1NAME](#cmake-android-toolchain-name)
+ [DISABLE\$1ANDROID\$1STANDALONE\$1BUILD](#cmake-disable-android-standalone-build)
+ [NDK\$1DIR](#cmake-ndk-dir)
### ANDROID\$1ABI
Android only. Controls which Application Binary Interface (ABI) to output code for.
**Note**
Not all valid Android ABI values are currently supported.
Values
*arm64* \$1 *armeabi-v7a* \$1 *x86\$164* \$1 *x86* \$1 *mips64* \$1 *mips*
Default
*armeabi-v7a*
### ANDROID\$1BUILD\$1CURL
Android only. If `ON`, build curl also.
Values
*ON* \$1 *OFF*
Default
*ON*
### ANDROID\$1BUILD\$1OPENSSL
Android only. If `ON`, build Openssl also.
Values
*ON* \$1 *OFF*
Default
*ON*
### ANDROID\$1BUILD\$1ZLIB
Android only. If `ON`, build Zlib also.
Values
*ON* \$1 *OFF*
Default
*ON*
### ANDROID\$1NATIVE\$1API\$1LEVEL
Android only. Controls what API level the SDK builds against. If you set [ANDROID\$1STL](#cmake-android-stl) to *gnustl*, you can choose any API level. If you use *libc\$1\$1*, you must use an API level of at least *21*.
Default
Varies by STL choice.
### ANDROID\$1STL
Android only. Controls what flavor of the C\$1\$1 standard library the SDK uses.
**Important**
Performance problems can occur within the SDK if the `gnustl` options are used; we strongly recommend using *libc\$1\$1\$1shared* or *libc\$1\$1\$1static*.
Values
*libc\$1\$1\$1shared* \$1 *libc\$1\$1\$1static* \$1 *gnustl\$1shared* \$1 *gnustl\$1static*
Default
*libc\$1\$1\$1shared*
### ANDROID\$1TOOLCHAIN\$1NAME
Android only. Controls which compiler is used to build the SDK.
**Note**
With GCC being deprecated by the Android NDK, we recommend using the default value.
Default
*standalone-clang*
### DISABLE\$1ANDROID\$1STANDALONE\$1BUILD
Android only. By default, Android builds use a standalone clang-based toolchain constructed via NDK scripts. To use your own toolchain, turn this option *ON*.
Values
*ON* \$1 *OFF*
Default
*OFF*
### NDK\$1DIR
Android only. Specifies an override path where the build system should find the Android NDK. By default, the build system checks environment variables (`ANDROID_NDK`) if this variable is not set.
# Configuring and using logging in the AWS SDK for C\$1\$1
The AWS SDK for C\$1\$1 includes configurable logging that generates a record of actions performed by the SDK during execution. To enable logging, set the `LogLevel` of `SDKOptions` to the appropriate verbosity for your application.
```
Aws::SDKOptions options;
options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Info;
```
There are seven levels of verbosity to choose from. The default value is `Off` and no logs will be generated. `Trace` will generate the most level of detail, and `Fatal` will generate the least messages reporting only fatal error conditions.
Once logging is enabled in your application, the SDK will generate log files in your executable directory following the default naming pattern of `aws_sdk_.log`. The log file generated by the prefix-naming option rolls over once per hour to allow for archiving or deleting log files.
The later versions of the SDK increasingly depend on the underlying AWS Common Runtime (CRT) libraries. These libraries provide common functionality and basic operations among SDKs. All log messages from the CRT libraries will be redirected to the SDK for C\$1\$1 by default. The log level and logging system you specify for the SDK for C\$1\$1 also applies to the CRT.
In the previous example, the CRT will inherit `LogLevel::Info` and also log messages at the `Info` level to the same file.
You can independently control the logging for the CRT libraries, either by redirecting its output to a separate log file, or by setting a different log level for messages from the CRT. Often it can be beneficial to reduce the verbosity of the CRT libraries so that they don’t overwhelm the logs. For example, the log level for *only* the CRT output can be set to `Warn` as follows:
```
options.loggingOptions.crt_logger_create_fn =
[](){ return Aws::MakeShared("CRTLogSystem", Aws::Utils::Logging::LogLevel::Warn); };
```
By optionally using the method `InitializeAWSLogging`, you can control the verbosity level and the log output of the `DefaultLogSystem`. You can configure the log filename prefix, or redirect the output to a stream instead of a file.
```
Aws::Utils::Logging::InitializeAWSLogging(
Aws::MakeShared(
"RunUnitTests", Aws::Utils::Logging::LogLevel::Trace, "aws_sdk_"));
```
Alternatively, instead of using the `DefaultLogSystem`, you can also use this method to provide your own logging implementation.
```
InitializeAWSLogging(Aws::MakeShared());
```
If you call method `InitializeAWSLogging`, free resources at the end of your program by calling `ShutdownAWSLogging`.
```
Aws::Utils::Logging::ShutdownAWSLogging();
```
**Example integration test with logging**
```
#include
#include
#include
#include
#include
int main(int argc, char** argv)
{
Aws::Utils::Logging::InitializeAWSLogging(
Aws::MakeShared(
"RunUnitTests", Aws::Utils::Logging::LogLevel::Trace, "aws_sdk_"));
::testing::InitGoogleTest(&argc, argv);
int exitCode = RUN_ALL_TESTS();
Aws::Utils::Logging::ShutdownAWSLogging();
return exitCode;
}
```
**Example subclass of `Aws::Utils::Logging::DefaultLogSystem` for custom logging**
The following code demonstrates how to subclass the `Aws::Utils::Logging::DefaultLogSystem` class, which is part of the AWS SDK for C\$1\$1. This example overrides the `ProcessFormattedStatement` virtual function to customize logging.
`Aws::Utils::Logging::DefaultLogSystem` is one of several classes in the AWS SDK for C\$1\$1 that subclass `Aws::Utils::Logging::LogSystemInterface` for custom logging.
```
class LogSystemOverride : public Aws::Utils::Logging::DefaultLogSystem {
public:
explicit LogSystemOverride(Aws::Utils::Logging::LogLevel logLevel,
const Aws::String &logPrefix)
: DefaultLogSystem(logLevel, logPrefix), mLogToStreamBuf(false) {}
const Aws::Utils::Stream::SimpleStreamBuf &GetStreamBuf() const {
return mStreamBuf;
}
void setLogToStreamBuf(bool logToStreamBuf) {
mLogToStreamBuf = logToStreamBuf;
}
protected:
void ProcessFormattedStatement(Aws::String &&statement) override {
if (mLogToStreamBuf) {
std::lock_guard lock(mStreamMutex);
mStreamBuf.sputn(statement.c_str(), statement.length());
}
DefaultLogSystem::ProcessFormattedStatement(std::move(statement));
}
private:
Aws::Utils::Stream::SimpleStreamBuf mStreamBuf;
// Use a mutex when writing to the buffer because
// ProcessFormattedStatement can be called from multiple threads.
std::mutex mStreamMutex;
std::atomic mLogToStreamBuf;
};
```
```
int main(int argc, char **argv) {
Aws::SDKOptions options;
options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Trace;
auto logSystemOverride = Aws::MakeShared("AllocationTag",
options.loggingOptions.logLevel,
options.loggingOptions.defaultLogPrefix);
options.loggingOptions.logger_create_fn = [logSystemOverride]() {
return logSystemOverride;
};
Aws::InitAPI(options); // Call Aws::InitAPI only once in an application.
{
Aws::Client::ClientConfiguration clientConfig;
// Optional: Set to the AWS Region (overrides config file).
// clientConfig.region = "us-east-1";
Aws::S3::S3Client s3Client(clientConfig);
logSystemOverride->setLogToStreamBuf(true);
auto outcome = s3Client.ListBuckets();
if (!outcome.IsSuccess()) {
std::cerr << "ListBuckets error: " <<
outcome.GetError().GetExceptionName() << " " <<
outcome.GetError().GetMessage() << std::endl;
}
logSystemOverride->setLogToStreamBuf(false);
std::cout << "Log for ListBuckets" << std::endl;
std::cout << logSystemOverride->GetStreamBuf().str() << std::endl;
}
Aws::ShutdownAPI(options);
return 0;
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/sdk-customization/override_default_logger.cpp) on GitHub.
# Overriding your HTTP client in the AWS SDK for C\$1\$1
The default HTTP client for Windows is [WinHTTP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa382925%28v=vs.85%29.aspx). The default HTTP client for all other platforms is [curl](https://curl.haxx.se/).
Optionally, you can override the HTTP client default by creating a custom `HttpClientFactory` to pass to any service client’s constructor. To override the HTTP client, the SDK must be built with curl support. Curl support is built by default in Linux and macOS, but additional steps are required to build on Windows. For more information about building the SDK on Windows with curl support, see [Building the AWS SDK for C\$1\$1 on Windows](setup-windows.md).
# Controlling iostreams used by the `HttpClient` and the `AWSClient` in the AWS SDK for C\$1\$1
By default, all responses use an input stream backed by a `stringbuf`. If needed, you can override the default behavior. For example, if you are using an Amazon S3 `GetObject` and don’t want to load the entire file into memory, you can use `IOStreamFactory` in `AmazonWebServiceRequest` to pass a lambda to create a file stream.
**Example file stream request**
```
//! Use a custom response stream when downloading an object from an Amazon Simple
//! Storage Service (Amazon S3) bucket.
/*!
\param bucketName: The Amazon S3 bucket name.
\param objectKey: The object key.
\param filePath: File path for custom response stream.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::SdkCustomization::customResponseStream(const Aws::String &bucketName,
const Aws::String &objectKey,
const Aws::String &filePath,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::S3::S3Client s3_client(clientConfiguration);
Aws::S3::Model::GetObjectRequest getObjectRequest;
getObjectRequest.WithBucket(bucketName).WithKey(objectKey);
getObjectRequest.SetResponseStreamFactory([filePath]() {
return Aws::New(
"FStreamAllocationTag", filePath, std::ios_base::out);
});
Aws::S3::Model::GetObjectOutcome getObjectOutcome = s3_client.GetObject(
getObjectRequest);
if (getObjectOutcome.IsSuccess()) {
std::cout << "Successfully retrieved object to file " << filePath << std::endl;
}
else {
std::cerr << "Error getting object. "
<< getObjectOutcome.GetError().GetMessage() << std::endl;
}
return getObjectOutcome.IsSuccess();
}
```
**Note**
There's more on GitHub. Find the complete example in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/sdk-customization#code-examples).
# Using a custom libcrypto library in the AWS SDK for C\$1\$1
By default, the AWS SDK for C\$1\$1 uses the default system cryptographic library for transport layer security. However, the SDK for C\$1\$1 can optionally be configured to use a different libcrypto library when building the SDK from source. This functionally means that all cryptographic operations will be diverted to a custom implementation of OpenSSL. For example, you might want to use the [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc) library in [FIPS mode](https://aws.amazon.com/blogs/security/aws-lc-is-now-fips-140-3-certified/) to achieve a FIPS standard in your application.
## How to build a custom libcrypto into the SDK for C\$1\$1
### Step 1: Build or obtain your libcrypto library
The [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc) is one example of an alternative libcrypto library, but any distribution of OpenSSL or OpenSSL-equivalent would work.
The SDK for C\$1\$1, and its dependency the CRT, both use libcrypto for their cryptographic functions and both need to handle dependencies the same. The SDK for C\$1\$1 depends on two different HTTP clients depending on if the request uses the SDK’s `CRT S3` functionality. The CRT specifically is dependent on [s2n](https://github.com/aws/s2n-tls), a TLS implementation that is initialized at start up time. Both the SDK and the s2n team have a cmake parameter to force the use of a shared libcrypto library regardless of the value of [BUILD\$1SHARED\$1LIBS](cmake-params.md#cmake-build-shared-libs). Typically, you want the CRT HTTP client and the regular HTTP client to use the same libcrypto. In this case, that would mean both referencing OpenSSL in the dependency tree. The SDK provides this via [AWS\$1USE\$1CRYPTO\$1SHARED\$1LIBS](cmake-params.md#cmake-use-crypto) and s2n (for CRT-based calls) provides this through [https://github.com/aws/s2n-tls/blob/20010e6b75a09ab5a0fc69a86265d3cc4c103b91/CMakeLists.txt#L39](https://github.com/aws/s2n-tls/blob/20010e6b75a09ab5a0fc69a86265d3cc4c103b91/CMakeLists.txt#L39). Dependency resolution is the same between these two libraries, and typically these are set to match, though you can explicitly set them to be different.
For example, to use `AWS-LC` as the libcrypto library, you would build it as follows:
```
git clone --depth 1 -b fips-2022-11-02 https://github.com/aws/aws-lc && \
cd aws-lc && \
mkdir build && \
cd build && \
cmake -G Ninja \
-DCMAKE_INSTALL_LIBDIR=lib \
-DCMAKE_INSTALL_PREFIX=/lc-install .. && \
cmake --build . && \
cmake --install . && \
rm -rf ./* && \
cmake -G Ninja \
-DBUILD_SHARED_LIBS=ON \
-DCMAKE_INSTALL_LIBDIR=lib \
-DCMAKE_INSTALL_PREFIX=/lc-install .. && \
cmake --build . && \
cmake --install .
```
### Step 2: Build curl from source or use a curl distribution with your libcrypto library
The SDK for C\$1\$1 requires that an HTTP client is installed on the system that will be used to make HTTP requests. The HTTP client must be built with the libcrypto that you intend to use. The HTTP client is responsible for TLS operations and, thus, uses your libcrypto library.
In the following example, the curl library is rebuilt using an installed version of `AWS-LC`.
```
git clone --depth 1 -b curl-8_5_0 https://github.com/curl/curl && \
cd curl && \
autoreconf -fi && \
mkdir build && \
cd build && \
../configure \
--enable-warnings \
--enable-werror \
--with-openssl=/lc-install \
--prefix=/curl-install && \
make && \
make install
```
### Step 3: Build the SDK using libcrypto and curl libraries
The SDK for C\$1\$1 can now be built using the previously created libcrypto and curl artifacts. This build of the SDK will use the custom libcrypto library for all cryptographic functionality.
```
git clone --depth 1 --recurse-submodules https://github.com/aws/aws-sdk-cpp \
cd aws-sdk-cpp && \
mkdir build && \
cd build && \
cmake -G Ninja \
-DCMAKE_PREFIX_PATH="/curl-install;/lc-install;" \
-DBUILD_ONLY="s3" \
-DCMAKE_INSTALL_PREFIX=/sdk-install \
-DAUTORUN_UNIT_TESTS=OFF .. && \
cmake --build . && \
cmake --install .
```
## Bringing it all together in a docker image
The following sample Docker file shows how to implement these steps in Amazon Linux 2023 environment.
```
# User AL2023 Base image
FROM public.ecr.aws/amazonlinux/amazonlinux:2023
# Install Dev Tools
RUN yum groupinstall -y "Development Tools"
RUN yum install -y cmake3 ninja-build
# Build and install AWS-LC on the fips branch both statically and dynamically.
RUN git clone --depth 1 -b fips-2022-11-02 https://github.com/aws/aws-lc && \\
cd aws-lc && \\
mkdir build && \\
cd build && \\
cmake -G Ninja \\
-DCMAKE_INSTALL_LIBDIR=lib \\
-DCMAKE_INSTALL_PREFIX=/lc-install .. && \\
cmake --build . && \\
cmake --install . && \\
rm -rf ./* && \\
cmake -G Ninja \\
-DBUILD_SHARED_LIBS=ON \\
-DCMAKE_INSTALL_LIBDIR=lib \\
-DCMAKE_INSTALL_PREFIX=/lc-install .. && \\
cmake --build . && \\
cmake --install .
# Build and install curl targeting AWS-LC as openssl
RUN git clone --depth 1 -b curl-8_5_0 https://github.com/curl/curl && \\
cd curl && \\
autoreconf -fi && \\
mkdir build && \\
cd build && \\
../configure \\
--enable-warnings \\
--enable-werror \\
--with-openssl=/lc-install \\
--prefix=/curl-install && \\
make && \\
make install
# Build and install SDK using the Curl and AWS-LC targets previously built
RUN git clone --depth 1 --recurse-submodules https://github.com/aws/aws-sdk-cpp \\
cd aws-sdk-cpp && \\
mkdir build && \\
cd build && \\
cmake -G Ninja \\
-DCMAKE_PREFIX_PATH="/curl-install;/lc-install;" \\
-DBUILD_ONLY="s3" \\
-DCMAKE_INSTALL_PREFIX=/sdk-install \\
-DAUTORUN_UNIT_TESTS=OFF .. && \\
cmake --build . && \\
cmake --install .
```