RXS_HMAC()

Performs HMAC calculation.

Requires both a secret as well as a configured RXS_HMACDS_t data structure to be passed in as parameters.

New in RXS 3.5.3

Enhancements

Enhanced RXS_HMACDS_t with new subfield ReturnMode which accepts the constants RXS_RETURN_MODE_BYTES, RXS_RETURN_MODE_CHAR_UPPER, and RXS_RETURN_MODE_CHAR_LOWER to allow the value returned from RXS_HMAC to be returned as raw bytes, uppercase characters, or lowercase characters. ReturnMode replaces/overlays the existing subfield ReturnAsChar which only allowed raw bytes or uppercase characters to be returned by RXS_HMAC

Subprocedure Prototype

`D RXS_HMAC... D PR Extproc('RXS_HMAC') Opdesc D Like(RXS_Var1Kv_t)`	Returns a calculated HMAC string. Note that if OutputStmf is set to an IFS path in the configuration data structure, the HMAC string will be written there instead.
`D pInput Like(RXS_Var16Mv_t) Const D Options(Varsize:Omit)`	Holds the data to be encrypted as part of HMAC calculation. Note that if InputStmf is set to an IFS path in the configuration data structure, the input will be read from there instead.
`D pSecret Like(RXS_Var1Kv_t) Const D Options(*Varsize)`	The secret used for HMAC calculation.
`D pDS LikeDS(RXS_HMACDS_t) D Options(*Varsize)`	Controls how HMAC calculation is performed. Uses RXS_HMACDS_t as a template.

Example Code

SHA 1 Calculation


*--------------------------------------------------------------
* This example demonstrates how to perform a simple SHA-1 HMAC
* calculation with RXS_HMAC. This example returns the HMAC string
* as text.
* This example is based on a test case from RFC 2202: 
*  https://www.rfc-editor.org/rfc/rfc2202
*--------------------------------------------------------------
Ctl-Opt ActGrp(*New) BndDir('RXSBND');

/COPY QRPGLECPY,RXSCB

Dcl-Ds HMACDS LikeDS(RXS_HMACDS_t);

Dcl-S Input Like(RXS_Var1Kv_t) Inz;
Dcl-S Secret Like(RXS_Var1Kv_t) Inz;
Dcl-S Output Like(RXS_Var1Kv_t) Inz;

RXS_ResetDS( HMACDS : RXS_DS_TYPE_HMAC );

Input = 'what do ya want for nothing?';
Secret = 'Jefe';

HMACDS.InputCcsid = RXS_CCSID_EBCDIC;
HMACDS.SecretCcsid = RXS_CCSID_EBCDIC;
HMACDS.EncryptAsCcsid = RXS_CCSID_ISO88591;

HMACDS.Algorithm = RXS_HMAC_SHA1;

Output = RXS_HMAC( Input : Secret : HMACDS );

Data Structures

RXS_HMAC_t

`D RXS_HMACDS_t... D DS Qualified Template Inz`
`D ReturnedErrorInfo... D LikeDS(RXS_ReturnedErrorInfoDS_t) Inz`	If an error occurs during processing, additional error information may be returned in this data structure.
`D DataStructureType... D 5I 0 Inz(RXS_DS_TYPE_HMAC)`	Internal use only
`D OnErrorMessageType... D 5I 0`
`D Algorithm 3I 0`	Determines which algorithm to use when encrypting. Valid Values: `RXS_HMAC_MD5` `RXS_HMAC_SHA1` `RXS_HMAC_SHA256` `RXS_HMAC_SHA384` `RXS_HMAC_SHA512`
`D InputCcsid 10I 0 Inz(RXS_CCSID_JOB)`	CCSID of input data. Used when the input data is of a different CCSID than the job CCSID. Not necessary if using InputStmf. Default Value: `RXS_CCSID_JOB`
`D SecretCcsid 10I 0 Inz(RXS_CCSID_JOB)`	CCSID of secret used for HMAC calculation. Used when the secret is of a different CCSID than the job CCSID. Default Value: `RXS_CCSID_JOB`
`D EncryptAsCcsid... D 10I 0 Inz(RXS_CCSID_ISO88591)`	When performing HMAC calculation, this field will specify the CCSID in which the data should be encrypted. If this value is different than the InputCcsid value, the data will be converted before encryption. Default Value: `RXS_CCSID_ISO88591`
`D ReturnAsChar... D N Inz(RXS_YES)`	Deprecated as of RXS 3.5.3, replaced by ReturnMode Specifies whether to return the character representation of the hexadecimal binary data. Valid Values: `RXS_YES` `RXS_NO` Default Value: `RXS_YES`
`D InputStmf Like(RXS_Var1Kv_t)`	Optional IFS stream file to use as input data for HMAC calculation.
`D OutputStmf Like(RXS_Var1Kv_t)`	Optional IFS stream file where HMAC output will be written.
`D InputPointer... D *`	Internal use only
`D InputLength 10I 0`	Internal use only
`D OutputPointer... D *`	Internal use only
`D OutputLength 10I 0`	Internal use only
`D ReturnMode... D 1A Overlay(ReturnAsChar) D Inz(RXS_RETURN_MODE_CHAR_UPPER)`	Specifies the method used to handle returned. Added in RXS 3.5.3. Replaces ReturnAsChar. Valid Values: `RXS_RETURN_MODE_CHAR_UPPER` `RXS_RETURN_MODE_CHAR_LOWER` `RXS_RETURN_MODE_BYTES` Default Value: `RXS_RETURN_MODE_CHAR_UPPER`