Skip to content

Commit

Permalink
Update SigV4_EncodeURI in doxygen (#100)
Browse files Browse the repository at this point in the history 
* Update SigV4_EncodeURI in doxygen

* Fix formatting

* Disable EXPAND_ONLY_PREDEF in doxygen config file to expand macro
  • Loading branch information
@kar-rahul-aws
kar-rahul-aws authored May 17, 2024
1 parent 78f1a14 commit 27e0ed4
Show file tree
Hide file tree
Showing 4 changed files with 117 additions and 83 deletions.
2 changes: 1 addition & 1 deletion docs/doxygen/config.doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2257,7 +2257,7 @@ MACRO_EXPANSION = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

EXPAND_ONLY_PREDEF = YES
EXPAND_ONLY_PREDEF = NO

# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
Expand Down
5 changes: 5 additions & 0 deletions docs/doxygen/pages.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ compiler option such as -D in gcc.
@brief Primary functions of the AWS SigV4 library:<br><br>
@subpage sigV4_generateHTTPAuthorization_function <br>
@subpage sigV4_awsIotDateToIso8601_function <br>
@subpage sigV4_encodeURI_function <br>

@page sigV4_generateHTTPAuthorization_function SigV4_GenerateHTTPAuthorization
@snippet sigv4.h declare_sigV4_generateHTTPAuthorization_function
Expand All @@ -80,6 +81,10 @@ compiler option such as -D in gcc.
@page sigV4_awsIotDateToIso8601_function SigV4_AwsIotDateToIso8601
@snippet sigv4.h declare_sigV4_awsIotDateToIso8601_function
@copydoc SigV4_AwsIotDateToIso8601

@page sigV4_encodeURI_function SigV4_EncodeURI
@snippet sigv4.h declare_sigV4_encodeURI_function
@copydoc SigV4_EncodeURI
*/

<!-- We do not use doxygen ALIASes here because there have been issues in the past versions with "^^" newlines within the alias definition. -->
Expand Down
6 changes: 5 additions & 1 deletion source/include/sigv4.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,7 @@ typedef enum SigV4Status
* Functions that may return this value:
* - #SigV4_GenerateHTTPAuthorization
* - #SigV4_AwsIotDateToIso8601
* - #SigV4_EncodeURI
*/
SigV4Success,

Expand All @@ -175,6 +176,7 @@ typedef enum SigV4Status
*
* Functions that may return this value:
* - #SigV4_GenerateHTTPAuthorization
* - #SigV4_EncodeURI
*/
SigV4InsufficientMemory,

Expand Down Expand Up @@ -588,8 +590,10 @@ SigV4Status_t SigV4_AwsIotDateToIso8601( const char * pDate,
* output: the length of the generated canonical URI.
* @param[in] encodeSlash Option to indicate if slashes should be encoded.
* @param[in] doubleEncodeEquals Option to indicate if equals should be double-encoded.
*
* @return #SigV4Success code if successful, error code otherwise.
*/
/* @[declare_sigV4_EncodeURI_function] */
/* @[declare_sigV4_encodeURI_function] */
SigV4Status_t SigV4_EncodeURI( const char * pUri,
size_t uriLen,
char * pCanonicalURI,
Expand Down
187 changes: 106 additions & 81 deletions source/sigv4.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1298,87 +1298,6 @@ static void generateCredentialScope( const SigV4Parameters_t * pSigV4Params,
return ret;
}

/*-----------------------------------------------------------*/

SigV4Status_t SigV4_EncodeURI( const char * pUri,
size_t uriLen,
char * pCanonicalURI,
size_t * canonicalURILen,
bool encodeSlash,
bool doubleEncodeEquals )
{
size_t uriIndex = 0U, bytesConsumed = 0U;
size_t bufferLen = 0U;
SigV4Status_t returnStatus = SigV4Success;

assert( pUri != NULL );
assert( pCanonicalURI != NULL );
assert( canonicalURILen != NULL );

bufferLen = *canonicalURILen;

while( ( uriIndex < uriLen ) && ( returnStatus == SigV4Success ) )
{
if( doubleEncodeEquals && ( pUri[ uriIndex ] == '=' ) )
{
if( ( bufferLen - bytesConsumed ) < URI_DOUBLE_ENCODED_EQUALS_CHAR_SIZE )
{
returnStatus = SigV4InsufficientMemory;
LOG_INSUFFICIENT_MEMORY_ERROR( "double encode '=' character in canonical query",
( bytesConsumed + URI_DOUBLE_ENCODED_EQUALS_CHAR_SIZE - bufferLen ) );
}
else
{
bytesConsumed += writeDoubleEncodedEquals( &( pCanonicalURI[ bytesConsumed ] ), bufferLen - bytesConsumed );
}
}
else if( isAllowedChar( pUri[ uriIndex ], encodeSlash ) )
{
/* If the output buffer has space, add the character as-is in URI encoding as it
* is neither a special character nor an '=' character requiring double encoding. */
if( bytesConsumed < bufferLen )
{
pCanonicalURI[ bytesConsumed ] = pUri[ uriIndex ];
++bytesConsumed;
}
else
{
returnStatus = SigV4InsufficientMemory;
LogError( ( "Failed to encode URI in buffer due to insufficient memory" ) );
}
}
else if( pUri[ uriIndex ] == '\0' )
{
/* The URI path beyond the NULL terminator is not encoded. */
uriIndex = uriLen;
}
else
{
if( ( bufferLen - bytesConsumed ) < URI_ENCODED_SPECIAL_CHAR_SIZE )
{
returnStatus = SigV4InsufficientMemory;
LOG_INSUFFICIENT_MEMORY_ERROR( "encode special character in canonical URI",
( bytesConsumed + URI_ENCODED_SPECIAL_CHAR_SIZE - bufferLen ) );
}
else
{
bytesConsumed += writeHexCodeOfChar( &( pCanonicalURI[ bytesConsumed ] ), bufferLen - bytesConsumed, pUri[ uriIndex ] );
}
}

uriIndex++;
}

if( returnStatus == SigV4Success )
{
/* Set the output parameter of the number of URI encoded bytes written
* to the buffer. */
*canonicalURILen = bytesConsumed;
}

return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t generateCanonicalURI( const char * pUri,
Expand Down Expand Up @@ -2408,6 +2327,8 @@ static SigV4Status_t completeHashAndHexEncode( const char * pInput,
return returnStatus;
}

/*-----------------------------------------------------------*/

static int32_t hmacAddKey( HmacContext_t * pHmacContext,
const char * pKey,
size_t keyLen,
Expand Down Expand Up @@ -2598,6 +2519,8 @@ static int32_t hmacFinal( HmacContext_t * pHmacContext,
return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t writeLineToCanonicalRequest( const char * pLine,
size_t lineLen,
CanonicalContext_t * pCanonicalContext )
Expand Down Expand Up @@ -2628,6 +2551,8 @@ static SigV4Status_t writeLineToCanonicalRequest( const char * pLine,
return returnStatus;
}

/*-----------------------------------------------------------*/

static int32_t completeHmac( HmacContext_t * pHmacContext,
const char * pKey,
size_t keyLen,
Expand Down Expand Up @@ -2664,6 +2589,8 @@ static int32_t completeHmac( HmacContext_t * pHmacContext,
return returnStatus;
}

/*-----------------------------------------------------------*/

static size_t writeStringToSignPrefix( char * pBufStart,
const char * pAlgorithm,
size_t algorithmLen,
Expand Down Expand Up @@ -2693,6 +2620,8 @@ static size_t writeStringToSignPrefix( char * pBufStart,
return algorithmLen + 1U + SIGV4_ISO_STRING_LEN + 1U;
}

/*-----------------------------------------------------------*/

static SigV4Status_t writeStringToSign( const SigV4Parameters_t * pParams,
const char * pAlgorithm,
size_t algorithmLen,
Expand Down Expand Up @@ -2771,6 +2700,8 @@ static SigV4Status_t writeStringToSign( const SigV4Parameters_t * pParams,
return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t generateCanonicalRequestUntilHeaders( const SigV4Parameters_t * pParams,
CanonicalContext_t * pCanonicalContext,
char ** pSignedHeaders,
Expand Down Expand Up @@ -2869,6 +2800,7 @@ static SigV4Status_t generateCanonicalRequestUntilHeaders( const SigV4Parameters
return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t generateAuthorizationValuePrefix( const SigV4Parameters_t * pParams,
const char * pAlgorithm,
Expand Down Expand Up @@ -2961,6 +2893,7 @@ static SigV4Status_t generateAuthorizationValuePrefix( const SigV4Parameters_t *
return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t generateSigningKey( const SigV4Parameters_t * pSigV4Params,
HmacContext_t * pHmacContext,
Expand Down Expand Up @@ -3062,6 +2995,8 @@ static SigV4Status_t generateSigningKey( const SigV4Parameters_t * pSigV4Params,
return returnStatus;
}

/*-----------------------------------------------------------*/

static SigV4Status_t writePayloadHashToCanonicalRequest( const SigV4Parameters_t * pParams,
CanonicalContext_t * pCanonicalContext )
{
Expand Down Expand Up @@ -3101,6 +3036,7 @@ static SigV4Status_t writePayloadHashToCanonicalRequest( const SigV4Parameters_t
return returnStatus;
}

/*-----------------------------------------------------------*/

SigV4Status_t SigV4_AwsIotDateToIso8601( const char * pDate,
size_t dateLen,
Expand Down Expand Up @@ -3178,6 +3114,8 @@ SigV4Status_t SigV4_AwsIotDateToIso8601( const char * pDate,
return returnStatus;
}

/*-----------------------------------------------------------*/

SigV4Status_t SigV4_GenerateHTTPAuthorization( const SigV4Parameters_t * pParams,
char * pAuthBuf,
size_t * authBufLen,
Expand Down Expand Up @@ -3286,3 +3224,90 @@ SigV4Status_t SigV4_GenerateHTTPAuthorization( const SigV4Parameters_t * pParams

return returnStatus;
}

/*-----------------------------------------------------------*/

#if ( SIGV4_USE_CANONICAL_SUPPORT == 1 )

SigV4Status_t SigV4_EncodeURI( const char * pUri,
size_t uriLen,
char * pCanonicalURI,
size_t * canonicalURILen,
bool encodeSlash,
bool doubleEncodeEquals )
{
size_t uriIndex = 0U, bytesConsumed = 0U;
size_t bufferLen = 0U;
SigV4Status_t returnStatus = SigV4Success;

assert( pUri != NULL );
assert( pCanonicalURI != NULL );
assert( canonicalURILen != NULL );

bufferLen = *canonicalURILen;

while( ( uriIndex < uriLen ) && ( returnStatus == SigV4Success ) )
{
if( doubleEncodeEquals && ( pUri[ uriIndex ] == '=' ) )
{
if( ( bufferLen - bytesConsumed ) < URI_DOUBLE_ENCODED_EQUALS_CHAR_SIZE )
{
returnStatus = SigV4InsufficientMemory;
LOG_INSUFFICIENT_MEMORY_ERROR( "double encode '=' character in canonical query",
( bytesConsumed + URI_DOUBLE_ENCODED_EQUALS_CHAR_SIZE - bufferLen ) );
}
else
{
bytesConsumed += writeDoubleEncodedEquals( &( pCanonicalURI[ bytesConsumed ] ), bufferLen - bytesConsumed );
}
}
else if( isAllowedChar( pUri[ uriIndex ], encodeSlash ) )
{
/* If the output buffer has space, add the character as-is in URI encoding as it
* is neither a special character nor an '=' character requiring double encoding. */
if( bytesConsumed < bufferLen )
{
pCanonicalURI[ bytesConsumed ] = pUri[ uriIndex ];
++bytesConsumed;
}
else
{
returnStatus = SigV4InsufficientMemory;
LogError( ( "Failed to encode URI in buffer due to insufficient memory" ) );
}
}
else if( pUri[ uriIndex ] == '\0' )
{
/* The URI path beyond the NULL terminator is not encoded. */
uriIndex = uriLen;
}
else
{
if( ( bufferLen - bytesConsumed ) < URI_ENCODED_SPECIAL_CHAR_SIZE )
{
returnStatus = SigV4InsufficientMemory;
LOG_INSUFFICIENT_MEMORY_ERROR( "encode special character in canonical URI",
( bytesConsumed + URI_ENCODED_SPECIAL_CHAR_SIZE - bufferLen ) );
}
else
{
bytesConsumed += writeHexCodeOfChar( &( pCanonicalURI[ bytesConsumed ] ), bufferLen - bytesConsumed, pUri[ uriIndex ] );
}
}

uriIndex++;
}

if( returnStatus == SigV4Success )
{
/* Set the output parameter of the number of URI encoded bytes written
* to the buffer. */
*canonicalURILen = bytesConsumed;
}

return returnStatus;
}

#endif /* #if (SIGV4_USE_CANONICAL_SUPPORT == 1) */

/*-----------------------------------------------------------*/

0 comments on commit 27e0ed4

Please sign in to comment.