AwsSignatureVersion4 5.0.0
dotnet add package AwsSignatureVersion4 --version 5.0.0
NuGet\Install-Package AwsSignatureVersion4 -Version 5.0.0
<PackageReference Include="AwsSignatureVersion4" Version="5.0.0" />
paket add AwsSignatureVersion4 --version 5.0.0
#r "nuget: AwsSignatureVersion4, 5.0.0"
// Install AwsSignatureVersion4 as a Cake Addin #addin nuget:?package=AwsSignatureVersion4&version=5.0.0 // Install AwsSignatureVersion4 as a Cake Tool #tool nuget:?package=AwsSignatureVersion4&version=5.0.0
AwsSignatureVersion4
The buttoned-up and boring, but deeply analyzed, implementation of Signature Version 4 (SigV4) in .NET.
Package: AwsSignatureVersion4
Platforms: .NET Standard 2.0, .NET 6
Table of contents
Introduction
This project is unique for me. It's my first that isn't a labor of love.
Having to sign requests in AWS I went through a series of emotions. My first was disappointment, directed at Amazon for not including a Signature Version 4 signer in their AWS SDK for .NET. The functionality is listed on Open Feature Requests for the AWS SDK for .NET but I haven't seen any actions towards an implementation yet.
My second emotion was being overwhelmed. The signing algorithm involved many more steps than I'd thought be possible, and I knew I'd have to spend a lot of time getting conformable with the algorithm.
So here we are, my attempt at implementing the Signature Version 4 algorithm in .NET. Please lets hope that AWS SDK soon releases this functionality so we can deprecate this piece of code...
Super simple to use
The best API is the one you already know. By extending both HttpClient
and IHttpClientFactory
we hope you'll get an easy integration.
Integration with HttpClient
This project extends the class HttpClient
by providing additional overloads to DeleteAsync
, GetAsync
, GetStringAsync
, PatchAsync
, PostAsync
, PutAsync
, SendAsync
, and the new synchronous addition to .NET 5 and onwards, Send
. These overloads accept the following additional arguments.
regionName
- The name of the AWS region, e.g.us-west-1
serviceName
- The name of the service, e.g.execute-api
for an AWS API Gatewaycredentials
- The AWS credentials of the principal sending the request
These overloads are built to integrate with HttpClient
, i.e. HttpClient.BaseAddress
and HttpClient.DefaultRequestHeaders
will be respected when sending the request.
The following example is demonstrating how one would send a GET /resources
request to an IAM authenticated AWS API Gateway on host www.acme.com
.
// Don't specify credentials in source code, this is for demo only! See next chapter for more
// information.
var credentials = new ImmutableCredentials("<access key id>", "<secret access key>", null);
var client = new HttpClient();
var response = await client.GetAsync(
"https://www.acme.com/resources",
regionName: "us-west-1",
serviceName: "execute-api",
credentials: credentials);
Please see the tests directory for other examples.
Integration with IHttpClientFactory
This project supports IHttpClientFactory
by means of providing a custom HTTP message handler called AwsSignatureHandler
. Once injected into the pipeline of the HTTP client factory it will sign your requests before sending them over the network.
AwsSignatureHandler
takes an instance of AwsSignatureHandlerSettings
as its only constructor argument, thus you will have to configure your dependency injection container to sufficiently resolve both these classes.
The following example is demonstrating how one would configure the ASP .NET Core service collection to acknowledge a HTTP client named my-client
. For more information regarding configuration, please see Dependency injection in ASP.NET Core.
// Don't specify credentials in source code, this is for demo only! See next chapter for more
// information.
var credentials = new ImmutableCredentials("<access key id>", "<secret access key>", null);
services
.AddTransient<AwsSignatureHandler>()
.AddTransient(_ => new AwsSignatureHandlerSettings("us-west-1", "execute-api", credentials));
services
.AddHttpClient("my-client")
.AddHttpMessageHandler<AwsSignatureHandler>();
Please see the tests directory for other examples.
Credentials
We've come a long way, but let's back up a step. Credentials should not be specified in source code, so where do they come from?
It all starts with a principal, i.e. an entity identifying itself using authentication. In some situations the principal is a IAM user and in other situations it is an entity assuming a IAM role. Whatever your principal is, it has the capability of providing credentials.
How the credentials are provided depend on where you run your code. If you run your code in a ECS Task you get your credentials using ECSTaskCredentials. Other runtime will require other credential providers, all of them are listed in the namespace Amazon.Runtime.
The pledge
This project comes with a pledge, providing transparency on supported and unsupported scenarios.
- ✅ ~200 unit tests are passing before a release
- ✅ ~700 integration tests targeting an IAM authenticated AWS API Gateway are passing before a release
- ✅ ~300 integration tests targeting an IAM authenticated AWS S3 bucket are passing before a release
- ✅ No steps of the signing algorithm have deliberately been left out
- ✅ AWSSDK.Core is reused as much as possible, thus the dependency
- ✅ Signature Version 4 Test Suite scenarios are passing, with the following exceptions:
- General
- ❌
get-utf8
- The signing algorithm states the following: 'Each path segment must be URI-encoded twice except for Amazon S3 which only gets URI-encoded once.'. This scenario does not URL encode the path segments twice, only once. - ❌
normalize-path/get-space
- The signing algorithm states the following: 'Each path segment must be URI-encoded twice except for Amazon S3 which only gets URI-encoded once.'. This scenario does not URL encode the path segments twice, only once. - ❌
post-x-www-form-urlencoded
- This scenario is based on the fact that we need to specify the charset in theContent-Type
header, e.g.Content-Type:application/x-www-form-urlencoded; charset=utf-8
. This is not necessary because .NET will add this encoding if omitted by us. We can safely skip this test and rely on integration tests where actual content is sent to an AWS API Gateway. - ❌
post-x-www-form-urlencoded-parameters
- This scenario is based on the fact that we need to specify the charset in theContent-Type
header, e.g.Content-Type:application/x-www-form-urlencoded; charset=utf-8
. This is not necessary because .NET will add this encoding if omitted by us. We can safely skip this test and rely on integration tests where actual content is sent to an AWS API Gateway.
- ❌
- API Gateway
- ❌
get-vanilla-query-unreserved
- This scenario defines a request that isn't supported by AWS API Gateway - ❌
post-sts-token/post-sts-header-before
- This scenario is based on the fact that the signing algorithm should support STS tokens, e.g. by assuming a role. This scenario is already covered by numerous other integration tests and can because of this safely be ignored.
- ❌
- S3
- ❌
normalize-path/get-slash-pointless-dot
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-header-key-case
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-header-key-sort
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-header-value-case
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-sts-token/post-sts-header-after
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-sts-token/post-sts-header-before
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-vanilla
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-vanilla-empty-query-value
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-vanilla-query
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-x-www-form-urlencoded
- This scenario defines a request that isn't supported by AWS S3. - ❌
post-x-www-form-urlencoded-parameters
- This scenario defines a request that isn't supported by AWS S3.
- ❌
- General
- ✅ All characters are supported in S3 object keys with the following exceptions:
- ❌ Plus (
+
) - ❌ Backslash (
\
) - ❌ Left curly brace (
{
) - ❌ Right curly brace (
}
) - ❌ Left square bracket (
[
) - ❌ Right square bracket (
]
) - ❌ 'Less Than' symbol (
<
) - ❌ 'Greater Than' symbol (
>
) - ❌ Grave accent / back tick (
`
) - ❌ 'Pound' character (
#
) - ❌ Caret (
^
) - ❌ Percent character (
%
) - ❌ Tilde (
~
) - ❌ Vertical bar / pipe (
|
) - ❌ Non-printable ASCII characters (128–255 decimal characters)
- ❌ Quotation marks
- ❌ Plus (
- Authentication method
- ✅ HTTP header authentication is supported
- ❌ Query string authentication is not supported
- HTTP version
- ✅ HTTP/1.1 is supported
- ❌ HTTP/2 is not supported, please create an issue if you wish it to be supported
Install via NuGet
If you want to include AwsSignatureVersion4 in your project, you can install it directly from NuGet.
To install AwsSignatureVersion4, run the following command in the Package Manager Console.
PM> Install-Package AwsSignatureVersion4
You can also install AwsSignatureVersion4 using the dotnet
command line interface.
dotnet add package AwsSignatureVersion4
Credit
Thank you JetBrains for your important initiative to support the open source community with free licenses to your products.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- AWSSDK.Core (>= 3.7.400.64)
-
net8.0
- AWSSDK.Core (>= 3.7.400.64)
NuGet packages (21)
Showing the top 5 NuGet packages that depend on AwsSignatureVersion4:
Package | Downloads |
---|---|
ImageApi.Platform.AuthorizationLayer
This pacakage is used to authorize access to actions. |
|
ImageApi.Platform.ExternalApis
This pacakage is used for external ImageAPI calls |
|
ApricusIt.SizmekCrawler.Contracts
Contains conracts for sizmek crawler |
|
ApricusIt.SizmekCrawler.Sdk
Package Description |
|
ApricusIt.FacebookCrawler.Sdk
Contains Facebook Crawler Sdk |
GitHub repositories (2)
Showing the top 2 popular GitHub repositories that depend on AwsSignatureVersion4:
Repository | Stars |
---|---|
nager/Nager.AmazonProductAdvertising
.NET Amazon Product Advertising Client
|
|
wubbl0rz/FiatChamp
FIAT (uconnect) Home Assistant Addon 🚗
|
Version | Downloads | Last updated |
---|---|---|
5.0.0 | 181 | 12/22/2024 |
4.0.6 | 64,334 | 9/18/2024 |
4.0.5 | 171,076 | 4/30/2024 |
4.0.1 | 706,720 | 3/29/2023 |
4.0.0 | 520,713 | 6/29/2022 |
4.0.0-beta.2 | 136 | 6/25/2022 |
4.0.0-beta.1 | 138 | 6/25/2022 |
3.0.1 | 763,482 | 3/25/2022 |
3.0.0 | 25,063 | 3/18/2022 |
2.1.1 | 319,854 | 9/7/2021 |
2.1.0 | 1,226 | 8/29/2021 |
2.1.0-beta.1 | 202 | 8/28/2021 |
2.0.0 | 210,699 | 7/31/2021 |
1.4.1 | 63,038 | 6/9/2021 |
1.4.0 | 284,518 | 11/25/2020 |
1.3.1 | 282,913 | 8/14/2020 |
1.3.0 | 106,017 | 6/29/2020 |
1.2.0 | 1,172,882 | 7/15/2019 |
1.1.0 | 628 | 7/13/2019 |
1.0.2 | 1,720 | 6/27/2019 |
1.0.2-sha-2b78963 | 448 | 6/26/2019 |
1.0.1 | 1,033 | 5/28/2019 |
1.0.0 | 4,786 | 5/27/2019 |
0.0.6 | 543 | 6/30/2020 |
0.0.5 | 531 | 6/30/2020 |
0.0.3 | 642 | 5/24/2019 |
0.0.2 | 600 | 5/24/2019 |
0.0.1 | 3,443 | 5/24/2019 |
For release notes, please see the change log on GitHub.