RSA_EncodeMsg

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).

VB6/VBA Syntax

nRet = RSA_EncodeMsg(abOutput(0), nOutputLen, abMessage(0), nMsgLen, nOptions)

Parameters

abOutput

[out] Byte array to receive the encoded output.

nOutputLen

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

abMessage

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

nMsgLen

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

nOptions

[in] Long option flags. Include one of the following:-
PKI_EME_PKCSV1_5 (0) to encode for encryption using PKCS#1 v1.5 method (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
and, if you have selected PKI_EMSIG_PKCSV1_5, then add one of these advanced options:
PKI_HASH_SHA1 (0) to use SHA-1 for the signature message digest (default).
PKI_HASH_MD5 to use MD5 for the signature message digest (PKI_EMSIG_PKCSV1_5 only).
PKI_HASH_MD2 to use MD2 for the signature message digest (PKI_EMSIG_PKCSV1_5 only).
and, optionally, add:-
PKI_EMSIG_DIGESTONLY to pass the message digest only as input (default = pass entire message)

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.

C/C++ Syntax

Returns (VB6/C)

Long: 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.

.NET Equivalent

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

Remarks

There are two distinct operations available here. 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, set

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

If you need to be compatible with a legacy application that uses, say, MD5, do this

nOptions = PKI_EMSIG_PKCSV1_5 + PKI_HASH_MD5

The default message digest algorithm SHA-1 is recommended in all new applications.

If you have already computed the message digest in byte format, say, as the byte array abDigest(), set

nOptions = PKI_EMSIG_PKCSV1_5 + PKI_EMSIG_DIGESTONLY
abMessage = abDigest

For full details of the background and mechanics, please refer to the original specification document [PKCS1].

Example

    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.

See Also

RSA_DecodeMsg RSA_RawPublic RSA_RawPrivate Raw RSA Techniques

[Contents] [Index]