RSA_EncodeMsg

Creates an EME or EMSA encoded message block according to PKCS#1 (EME = Encoding Method for Encryption, EMSA = Encoding Method for Signature with Appendix).

VBA/VB6 Syntax

nRet = RSA_EncodeMsg(lpOutput(0), nOutputLen, lpMessage(0), nMsgLen, nOptions)

C/C++ Syntax

Parameters

lpOutput

[out] array to receive the encoded output.

nOutBytes

[in] specifying the maximum length of the output array.

lpInput

[in] array containing the message to be encoded (or the message digest).

nInputLen

[in] specifying the number of bytes in the message.

nOptions

[in] option flags. Include one of the following:-
PKI_EME_PKCSV1_5 (0) to encode for encryption using PKCS#1 v1.5 method (RSAES-PKCS1-v1_5) (default)
PKI_EME_OAEP to encode for encryption using OAEP method
PKI_EMSIG_PKCSV1_5 to encode for signature using PKCS#1 v1.5 method (RSASSA-PKCS1-v1_5)

If you have selected PKI_EMSIG_PKCSV1_5, then add one of these options to set the hash function for the signature message digest:
PKI_HASH_SHA1 (0) to use SHA-1 (default).
PKI_HASH_SHA224 to use SHA-224
PKI_HASH_SHA256 to use SHA-256
PKI_HASH_SHA384 to use SHA-384
PKI_HASH_SHA512 to use SHA-512
PKI_HASH_MD5 to use MD5 [legacy, not recommended]
PKI_HASH_MD2 to use MD2 [legacy, definitely not recommended]
and, optionally, add:-
PKI_EMSIG_DIGESTONLY as a flag to pass the message digest only as input to-be-signed (default = pass entire message)

If you have selected PKI_EME_OAEP, then add one of these options to set the hash function for EME-OAEP encoding:
PKI_HASH_SHA1 (0) to use SHA-1 (default).
PKI_HASH_SHA224 to use SHA-224
PKI_HASH_SHA256 to use SHA-256
PKI_HASH_SHA384 to use SHA-384
PKI_HASH_SHA512 to use SHA-512
and, optionally, add:-
PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above)

Alternatively, ignore all the above and use the specialist option
PKI_EMSIG_ISO9796 to use the ISO9796-1 encoding for a signature. See AUTACK messages and ISO/IEC 9796-1 signatures for more details.

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a negative error code.
CAUTION: This function assumes you know the required length of the output. It does not return the length.

VBA Wrapper Syntax

.NET Equivalent

Rsa.EncodeMsgForEncryption Method
Rsa.EncodeMsgForSignature Method
Rsa.EncodeDigestForSignature Method
Rsa.EncodeMsgIso9796 Method

Python Equivalent

Remarks

There are two distinct operations available here (a design decision that we regret, in hindsight). One operation creates an 'Encoded Message for Encryption' (EME) block which you would then encrypt with an RSA public key using the RSA_RawPublic() function. The other creates an 'Encoded Message for Signature with Appendix' (EMSA) block which you would then sign by encrypting with an RSA private key using the RSA_RawPrivate() function.

To Encode an EME Block

Set either

nOptions = PKI_EME_PKCSV1_5

or

nOptions = PKI_EME_OAEP

The default operation PKI_EME_PKCSV1_5 will create an encoded EME message block according to PKCS#1 v1.5. The PKI_EME_OAEP alternative uses a more secure algorithm (OAEP = Optimal Asymmetric Encryption Padding).

To Encode an EMSA Block

To encode the message "Hello world" ready for signing, use the PKI_EMSIG_PKCSV1_5 option and set

nOptions = PKI_EMSIG_PKCSV1_5
abInput = StrConv("Hello world", vbFromUnicode)
nInputLen = UBound(abMessage) - LBound(abMessage) + 1

nOptions = PKI_EMSIG_PKCSV1_5;
input = "Hello world";
nInputLen = strlen(input);

If you need to be compatible with a legacy application that uses, say, MD5, add the hash flag to the option

nOptions = PKI_EMSIG_PKCSV1_5 + PKI_HASH_MD5

If you have already computed the message digest in byte array form, then pass this as input and set

nOptions = PKI_EMSIG_PKCSV1_5 + PKI_EMSIG_DIGESTONLY

The algorithm RSA-PSS is not available for this function. Use SIG_SignData instead.

Example (VBA core function)

Dim abData(3) As Byte
Dim abBlock() As Byte
Dim abCheck() As Byte
Dim nDataLen As Long
Dim nBlockLen As Long
Dim nLen As Long
Dim nRet As Long

' Our message data, 4 bytes long
abData(0) = &HDE
abData(1) = &HAD
abData(2) = &HBE
abData(3) = &HEF
nDataLen = 4
Debug.Print "DATA   =" & cnvHexStrFromBytes(abData)
' Set up output block with correct size
nBlockLen = 64
ReDim abBlock(nBlockLen - 1)
' Encode ready for encryption with default algorithm
nRet = RSA_EncodeMsg(abBlock(0), nBlockLen, abData(0), nDataLen, PKI_EME_PKCSV1_5)
If (nRet < 0) Then
	MsgBox "Encoding Error"
	Exit Function
End If
Debug.Print "BLOCK  =" & cnvHexStrFromBytes(abBlock)

' Now encrypt this block using RSA_RawPublic
' ...
' ... and send to recipient ...
' ...
' who decrypts using RSA_RawPrivate to get the encoded block

' Recover the message from the encoded block
' How long is it?
nLen = RSA_DecodeMsg(0, 0, abBlock(0), nBlockLen, PKI_EME_PKCSV1_5)
If (nLen < 0) Then
	MsgBox "Decryption Error"
	Exit Function
End If
ReDim abCheck(nLen - 1)
nLen = RSA_DecodeMsg(abCheck(0), nLen, abBlock(0), nBlockLen, PKI_EME_PKCSV1_5)
Debug.Print "DECODED=" & cnvHexStrFromBytes(abCheck)

 ' Alternative using more-secure OAEP algorithm
nRet = RSA_EncodeMsg(abBlock(0), nBlockLen, abData(0), nDataLen, PKI_EME_OAEP)
If (nRet < 0) Then
	MsgBox "Encoding Error"
	Exit Function
End If
Debug.Print "BLOCK  =" & cnvHexStrFromBytes(abBlock)
' ...
nLen = RSA_DecodeMsg(0, 0, abBlock(0), nBlockLen, PKI_EME_OAEP)
If (nLen < 0) Then
	MsgBox "Decryption Error"
	Exit Function
End If
ReDim abCheck(nLen - 1)
nLen = RSA_DecodeMsg(abCheck(0), nLen, abBlock(0), nBlockLen, PKI_EME_OAEP)
Debug.Print "DECODED=" & cnvHexStrFromBytes(abCheck)

More detailed examples are given in the section Raw RSA Techniques.

Example (VBA wrapper function)

Dim lpData() As Byte
Dim lpBlock() As Byte
Dim lpDecoded() As Byte
Dim nBlockLen As Long
nBlockLen = 512 \ 8

lpData = cnvBytesFromHexStr("DEADBEEF")

lpBlock = rsaEncodeMsg(nBlockLen, lpData, PKI_EME_PKCSV1_5)
Debug.Print cnvHexStrFromBytes(lpBlock)
lpDecoded = rsaDecodeMsg(lpBlock, PKI_EME_PKCSV1_5)
Debug.Print "DECODED=" & cnvHexStrFromBytes(lpDecoded)

lpBlock = rsaEncodeMsg(nBlockLen, lpData, PKI_EME_OAEP)
Debug.Print cnvHexStrFromBytes(lpBlock)
lpDecoded = rsaDecodeMsg(lpBlock, PKI_EME_OAEP)
Debug.Print "DECODED=" & cnvHexStrFromBytes(lpDecoded)

lpBlock = rsaEncodeMsg(nBlockLen, lpData, PKI_EMSIG_PKCSV1_5 Or PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpBlock)
lpDecoded = rsaDecodeMsg(lpBlock, PKI_EMSIG_PKCSV1_5)
Debug.Print "DECODED=" & cnvHexStrFromBytes(lpDecoded)

Debug.Print "DIGEST =" & hashHexFromBytes(lpData, PKI_HASH_SHA256)

See Also

RSA_DecodeMsg RSA_RawPublic RSA_RawPrivate Raw RSA Techniques

[Contents] [Index]