sigv4.h File Reference

Interface for the SigV4 Client Utility 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_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_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 Utility 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 Client Utility 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]	pParams	Parameters for generating the SigV4 signature.
[out]	pAuthBuf	Buffer to hold the generated Authorization header value.
[in,out]	authBufLen	Input: the length of pAuthBuf, output: the length of the authorization value written to the buffer.
[out]	pSignature	Location of the signature in the authorization string.
[out]	signatureLen	The 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.
 
SigV4Status_t status = SigV4Success;
 
// 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.
}

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]	pDate	The 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]	dateLen	The 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]	pDateISO8601	The 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]	dateISO8601Len	The 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.
 
SigV4Status_t status = SigV4Success;
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
}