SigV4 v1.2.0
SigV4 Library for AWS Authentication
sigv4.h File Reference

Interface for the SigV4 Library. More...

#include <stdint.h>
#include <stddef.h>
#include "sigv4_config.h"
#include "sigv4_config_defaults.h"

Go to the source code of this file.

Data Structures

struct  SigV4CryptoInterface_t
 The cryptography interface used to supply the user-defined hash implementation. More...
 
struct  SigV4HttpParameters_t
 Configurations of the HTTP request used to create the Canonical Request. More...
 
struct  SigV4Credentials_t
 Configurations for the AWS credentials used to generate the Signing Key. More...
 
struct  SigV4Parameters_t
 Complete configurations required for generating "String to Sign" and "Signing Key" values. More...
 

Macros

#define SIGV4_AWS4_HMAC_SHA256   "AWS4-HMAC-SHA256"
 
#define SIGV4_AWS4_HMAC_SHA256_LENGTH   ( sizeof( SIGV4_AWS4_HMAC_SHA256 ) - 1U )
 
#define SIGV4_HTTP_X_AMZ_DATE_HEADER   "x-amz-date"
 
#define SIGV4_HTTP_X_AMZ_SECURITY_TOKEN_HEADER   "x-amz-security-token"
 
#define SIGV4_STREAMING_AWS4_HMAC_SHA256_PAYLOAD   "STREAMING-AWS4-HMAC-SHA256-PAYLOAD"
 
#define SIGV4_HTTP_X_AMZ_CONTENT_SHA256_HEADER   "x-amz-content-sha256"
 
#define SIGV4_HTTP_X_AMZ_CONTENT_SHA256_HEADER_LENGTH   ( sizeof( SIGV4_HTTP_X_AMZ_CONTENT_SHA256_HEADER ) - 1U )
 
#define SIGV4_HTTP_X_AMZ_STORAGE_CLASS_HEADER   "x-amz-storage-class"
 
#define SIGV4_ACCESS_KEY_ID_LENGTH   20U
 
#define SIGV4_SECRET_ACCESS_KEY_LENGTH   40U
 
#define SIGV4_ISO_STRING_LEN   16U
 
#define SIGV4_EXPECTED_LEN_RFC_3339   20U
 
#define SIGV4_EXPECTED_LEN_RFC_5322   29U
 
#define SIGV4_HTTP_PATH_IS_CANONICAL_FLAG   0x1U
 Set this flag to indicate that the HTTP request path input is already canonicalized. More...
 
#define SIGV4_HTTP_QUERY_IS_CANONICAL_FLAG   0x2U
 Set this flag to indicate that the HTTP request query input is already canonicalized. More...
 
#define SIGV4_HTTP_HEADERS_ARE_CANONICAL_FLAG   0x4U
 Set this flag to indicate that the HTTP request headers input is already canonicalized. More...
 
#define SIGV4_HTTP_PAYLOAD_IS_HASH   0x8U
 Set this flag to indicate that the HTTP request payload is already hashed. More...
 
#define SIGV4_HTTP_ALL_ARE_CANONICAL_FLAG   0x7U
 Set this flag to indicate that the HTTP request path, query, and headers are all already canonicalized. More...
 

Enumerations

enum  SigV4Status_t {
  SigV4Success , SigV4InvalidParameter , SigV4InsufficientMemory , SigV4ISOFormattingError ,
  SigV4MaxHeaderPairCountExceeded , SigV4MaxQueryPairCountExceeded , SigV4HashError , SigV4InvalidHttpHeaders
}
 Return status of the SigV4 Library. More...
 

Functions

SigV4Status_t SigV4_GenerateHTTPAuthorization (const SigV4Parameters_t *pParams, char *pAuthBuf, size_t *authBufLen, char **pSignature, size_t *signatureLen)
 Generates the HTTP Authorization header value. More...
 
SigV4Status_t SigV4_AwsIotDateToIso8601 (const char *pDate, size_t dateLen, char *pDateISO8601, size_t dateISO8601Len)
 Parse the date header value from the AWS IoT response, and generate the formatted ISO 8601 date required for authentication. More...
 

Detailed Description

Interface for the SigV4 Library.

Function Documentation

◆ SigV4_GenerateHTTPAuthorization()

SigV4Status_t SigV4_GenerateHTTPAuthorization ( const SigV4Parameters_t pParams,
char *  pAuthBuf,
size_t *  authBufLen,
char **  pSignature,
size_t *  signatureLen 
)

Generates the HTTP Authorization header value.

Note
The API does not support HTTP headers containing empty HTTP header keys or values.
Parameters
[in]pParamsParameters for generating the SigV4 signature.
[out]pAuthBufBuffer to hold the generated Authorization header value.
[in,out]authBufLenInput: the length of pAuthBuf, output: the length of the authorization value written to the buffer.
[out]pSignatureLocation of the signature in the authorization string.
[out]signatureLenThe length of pSignature.
Returns
SigV4Success if successful, error code otherwise.

Example

// The following example shows how to use the SigV4_GenerateHTTPAuthorization
// function to generate the HTTP Authorization header value for HTTP requests
// to AWS services requiring SigV4 authentication.
// Buffer to hold the authorization header.
char pSigv4Auth[ 2048U ];
size_t sigv4AuthLen = sizeof( pSigv4Auth );
// Pointer to signature in the Authorization header that will be populated in
// pSigv4Auth by the SigV4_GenerateHTTPAuthorization API function.
char * signature = NULL;
size_t signatureLen = 0;
SigV4Parameters_t sigv4Params =
{
// Parsed temporary credentials obtained from AWS IoT Credential Provider.
.pCredentials = &sigv4Creds,
// Date in ISO8601 format.
.pDateIso8601 = pDateISO8601,
// The AWS region for the request.
.pRegion = AWS_REGION,
.regionLen = strlen( AWS_REGION ),
// The AWS service for the request.
.pService = AWS_SERVICE_NAME,
.serviceLen = strlen( AWS_SERVICE_NAME ),
// SigV4 crypto interface. See SigV4CryptoInterface_t interface documentation.
.pCryptoInterface = &cryptoInterface,
// HTTP parameters for the HTTP request to generate a SigV4 authorization header for.
.pHttpParameters = &sigv4HttpParams
};
status = SigV4_GenerateHTTPAuthorization( &sigv4Params, pSigv4Auth, &sigv4AuthLen, &signature, &signatureLen );
if( status != SigV4Success )
{
// Failed to generate authorization header.
}
SigV4Status_t
Return status of the SigV4 Library.
Definition: sigv4.h:142
@ SigV4Success
The SigV4 library function completed successfully.
Definition: sigv4.h:150
SigV4Status_t SigV4_GenerateHTTPAuthorization(const SigV4Parameters_t *pParams, char *pAuthBuf, size_t *authBufLen, char **pSignature, size_t *signatureLen)
Generates the HTTP Authorization header value.
Definition: sigv4.c:3186
Complete configurations required for generating "String to Sign" and "Signing Key" values.
Definition: sigv4.h:384
SigV4Credentials_t * pCredentials
The AccessKeyId, SecretAccessKey, and SecurityToken used to generate the Authorization header.
Definition: sigv4.h:389

◆ SigV4_AwsIotDateToIso8601()

SigV4Status_t SigV4_AwsIotDateToIso8601 ( const char *  pDate,
size_t  dateLen,
char *  pDateISO8601,
size_t  dateISO8601Len 
)

Parse the date header value from the AWS IoT response, and generate the formatted ISO 8601 date required for authentication.

This is an optional utility function available to the application, to assist with formatting of the date header obtained from AWS IoT (when requesting a temporary token or sending a POST request).

AWS SigV4 authentication requires an ISO 8601 date to be present in the "x-amz-date" request header, as well as in the credential scope (must be identical). For additional information on date handling, please see https://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html.

Acceptable Input Formats:

  • RFC 5322 (ex. "Thu, 18 Jan 2018 09:18:06 GMT"), the preferred format in HTTP 'Date' response headers. If using this format, the date parameter should match "***, DD 'MMM' YYYY hh:mm:ss GMT" exactly.
  • RFC 3339 (ex. "2018-01-18T09:18:06Z"), found occasionally in 'Date' and expiration headers. If using this format, the date parameter should match "YYYY-MM-DD'T'hh:mm:ss'Z'" exactly.

Formatted Output:

  • The ISO8601-formatted date will be returned in the form "YYYYMMDD'T'HHMMSS'Z'" (ex. "20180118T091806Z").
Parameters
[in]pDateThe date header (in RFC 3339 or RFC 5322 formats). An acceptable date header can be found in the HTTP response returned by AWS IoT. This value should use UTC (with no time-zone offset), and be exactly 20 or 29 characters in length (excluding the null character), to comply with RFC 3339 and RFC 5322 formats, respectively.
[in]dateLenThe length of the pDate header value. Must be either SIGV4_EXPECTED_LEN_RFC_3339 or SIGV4_EXPECTED_LEN_RFC_5322, for valid input parameters.
[out]pDateISO8601The formatted ISO8601-compliant date. The date value written to this buffer will be exactly 16 characters in length, to comply with the ISO8601 standard required for SigV4 authentication.
[in]dateISO8601LenThe length of buffer pDateISO8601. Must be at least SIGV4_ISO_STRING_LEN bytes, for valid input parameters.
Returns
SigV4Success code if successful, error code otherwise.

Example

// The following example shows how to use the SigV4_AwsIotDateToIso8601
// function to convert an AWS IoT date header value to a ISO 8601 date.
char pDateISO8601[SIGV4_ISO_STRING_LEN] = {0};
size_t pDateISO8601Len = SIGV4_ISO_STRING_LEN;
// pDate and dateLen are the date header and length which are parsed from
// an AWS IoT Credential Provider HTTP response, using an HTTP library.
status = SigV4_AwsIotDateToIso8601( pDate, dateLen, pDateISO8601, pDateISO8601Len );
if( status != SigV4Success )
{
// Failed to parse date
}
#define SIGV4_ISO_STRING_LEN
Definition: sigv4.h:76
SigV4Status_t SigV4_AwsIotDateToIso8601(const char *pDate, size_t dateLen, char *pDateISO8601, size_t dateISO8601Len)
Parse the date header value from the AWS IoT response, and generate the formatted ISO 8601 date requi...
Definition: sigv4.c:3110