sigv4.h

Go to the documentation of this file.

/*
 * SigV4 Library v1.3.0
 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * SPDX-License-Identifier: MIT
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
#ifndef SIGV4_H_
#define SIGV4_H_
 
/* Standard includes. */
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    extern "C" {
#endif
/* *INDENT-ON* */
 
/* SIGV4_DO_NOT_USE_CUSTOM_CONFIG allows building of the SigV4 library without a
 * config file. If a config file is provided, the SIGV4_DO_NOT_USE_CUSTOM_CONFIG
 * macro must not be defined.
 */
#ifndef SIGV4_DO_NOT_USE_CUSTOM_CONFIG
    #include "sigv4_config.h"
#endif
 
/* Include config defaults header to get default values of configurations not
 * defined in sigv4_config.h file. */
#include "sigv4_config_defaults.h"
 
/* Convenience macros for library optimization */
 
#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"                            
/* MISRA Ref 5.4.1 [Macro identifiers] */
/* More details at: https://github.com/aws/SigV4-for-AWS-IoT-embedded-sdk/blob/main/MISRA.md#rule-54 */
/* coverity[other_declaration] */
#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
 
#define SIGV4_HTTP_QUERY_IS_CANONICAL_FLAG       0x2U
 
#define SIGV4_HTTP_HEADERS_ARE_CANONICAL_FLAG    0x4U
 
#define SIGV4_HTTP_PAYLOAD_IS_HASH               0x8U
 
#define SIGV4_HTTP_IS_PRESIGNED_URL              0x10U
 
#define SIGV4_HTTP_ALL_ARE_CANONICAL_FLAG        0x7U
 
typedef enum SigV4Status
{
    SigV4Success,
 
    SigV4InvalidParameter,
 
    SigV4InsufficientMemory,
 
    SigV4ISOFormattingError,
 
    SigV4MaxHeaderPairCountExceeded,
 
    SigV4MaxQueryPairCountExceeded,
 
    SigV4HashError,
 
    SigV4InvalidHttpHeaders
} SigV4Status_t;
 
typedef struct SigV4CryptoInterface
{
    int32_t ( * hashInit )( void * pHashContext );
 
    int32_t ( * hashUpdate )( void * pHashContext,
                              const uint8_t * pInput,
                              size_t inputLen );
 
    int32_t ( * hashFinal )( void * pHashContext,
                             uint8_t * pOutput,
                             size_t outputLen );
 
    void * pHashContext;
 
    size_t hashBlockLen;
 
    size_t hashDigestLen;
} SigV4CryptoInterface_t;
 
typedef struct SigV4HttpParameters
{
    const char * pHttpMethod; 
    size_t httpMethodLen;     
    uint32_t flags;
 
    const char * pPath;
    size_t pathLen; 
    const char * pQuery;
    size_t queryLen; 
    const char * pHeaders;
    size_t headersLen; 
    const char * pPayload;
    size_t payloadLen; 
} SigV4HttpParameters_t;
 
typedef struct SigV4Credentials
{
    const char * pAccessKeyId;
    size_t accessKeyIdLen; 
    const char * pSecretAccessKey;
    size_t secretAccessKeyLen; 
} SigV4Credentials_t;
 
typedef struct SigV4Parameters
{
    SigV4Credentials_t * pCredentials;
 
    const char * pDateIso8601;
 
    const char * pAlgorithm;
 
    size_t algorithmLen; 
    const char * pRegion;
    size_t regionLen; 
    const char * pService;
    size_t serviceLen; 
    SigV4CryptoInterface_t * pCryptoInterface;
 
    SigV4HttpParameters_t * pHttpParameters;
} SigV4Parameters_t;
 
/* @[declare_sigV4_generateHTTPAuthorization_function] */
SigV4Status_t SigV4_GenerateHTTPAuthorization( const SigV4Parameters_t * pParams,
                                               char * pAuthBuf,
                                               size_t * authBufLen,
                                               char ** pSignature,
                                               size_t * signatureLen );
/* @[declare_sigV4_generateHTTPAuthorization_function] */
 
/* @[declare_sigV4_awsIotDateToIso8601_function] */
SigV4Status_t SigV4_AwsIotDateToIso8601( const char * pDate,
                                         size_t dateLen,
                                         char * pDateISO8601,
                                         size_t dateISO8601Len );
/* @[declare_sigV4_awsIotDateToIso8601_function] */
 
#if ( SIGV4_USE_CANONICAL_SUPPORT == 1 )
 
/* @[declare_sigV4_encodeURI_function] */
    SigV4Status_t SigV4_EncodeURI( const char * pUri,
                                   size_t uriLen,
                                   char * pCanonicalURI,
                                   size_t * canonicalURILen,
                                   bool encodeSlash,
                                   bool doubleEncodeEquals );
/* @[declare_sigV4_encodeURI_function] */
 
#endif /* #if (SIGV4_USE_CANONICAL_SUPPORT == 1) */
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    }
#endif
/* *INDENT-ON* */
 
#endif /* SIGV4_H_ */