SIG_SignFile

Compute a signature value over data in a file.

VBA/VB6 Syntax

nRet = SIG_SignFile(strOutput, nOutChars, strDataFile, strKeyFile, strPassword, strAlgName, nOptions)

C/C++ Syntax

Parameters

szOutput

[out] string of sufficient length to receive the output.

nOutChars

[in] specifying the maximum number of characters to be received.

szDataFile

[in] specifying the file containing the input data to be signed.

szKeyFile

[in] specifying the name of the private key file (or a string containing the key in PEM format, or a valid internal private key string).

szPassword

[in] containing the password for the private key, or "" if not required.

szAlgName

[in] specifying the signature algorithm (case insensitive):
"sha1WithRSAEncryption" (default - CAUTION)
"sha224WithRSAEncryption"
"sha256WithRSAEncryption" [minimum recommended]
"sha384WithRSAEncryption"
"sha512WithRSAEncryption"
"md5WithRSAEncryption" [for legacy applications - not recommended for new implementations]
"ecdsaWithSHA1"
"ecdsaWithSHA224"
"ecdsaWithSHA256"
"ecdsaWithSHA384"
"ecdsaWithSHA512"
"RSA-PSS-SHA1"
"RSA-PSS-SHA224"
"RSA-PSS-SHA256"
"RSA-PSS-SHA384"
"RSA-PSS-SHA512"
(Note that Ed25519 and Ed448 are not available with this function - see Remarks)
or "" to use the signature algorithm flag in nOptions, see Specifying the signature algorithm in a SIG_ function.

nOptions

[in] Zero (0) for defaults.

To change the format of the output (default base64 encoded), add one of:

• PKI_ENCODE_BASE64URL to encode the output in the URL-safe "base64url" encoding of [RFC4648]; or
• PKI_ENCODE_HEX to encode the output in hexadecimal (base16) encoding

Options for ECDSA signatures only:

• PKI_SIG_DETERMINISTIC to use the deterministic digital signature generation procedure of [RFC6979] for ECDSA signatures (default=random k)
• PKI_SIG_ASN1DER to form the signature value as a DER-encoded ASN.1 structure (as used by Bitcoin); (default=simple concatenation r||s)

Options for RSA-PSS signatures only: [New in v12.0] (see RSA signature and encryption schemes)
Add one of the following to specify the salt length:

• PKI_PSS_SALTLEN_HLEN (0) to set the salt length to hLen, the length of the output of the hash function (default).
• PKI_PSS_SALTLEN_MAX to set the salt length to the maximum possible (OpenSSL does this by default)
• PKI_PSS_SALTLEN_20 to set the salt length to be exactly 20 bytes regardless of the hash algorithm
• PKI_PSS_SALTLEN_ZERO to set the salt length to be zero

Returns (VBA/C)

If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

Sig.SignFile Method

C++ (STL) Equivalent

Python Equivalent

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This function is identical to SIG_SignData except the data to be signed is in a file.

The Ed25519 and Ed448 signature algorithms are not available with this function. To sign using Ed25519 or Ed448, read in the file to a byte array and use SIG_SignData.

Example (VBA core function)

Dim strSignature As String
Dim strDataFile As String
Dim strKeyFile As String
Dim strPassword As String
Dim nChars As Long
Dim nOption As Long

'Input data = file containing the three bytes 'a', 'b', 'c'
strDataFile = "abc.txt"
strKeyFile = "AlicePrivRSASign.p8e"
strPassword = "password" ' CAUTION: do not hard-code passwords!
nOption = PKI_SIG_SHA256RSA ' Use option instead of string

' Find required length of output string
nChars = SIG_SignFile("", 0, strDataFile, strKeyFile, strPassword, "", nOption)
Debug.Print "SIG_SignFile returns " & nChars & " (expected >0)"
' Allocate memory for output string
strSignature = String(nChars, " ")
nChars = SIG_SignFile(strSignature, Len(strSignature), strDataFile, strKeyFile, strPassword, "", nOption)
' Output base64 signature value
Debug.Print "SIG=" & strSignature

This uses Alice's encrypted private key to sign a file using sha256WithRSAEncryption. The output should be

SIG_SignFile returns 172 (expected >0)
SIG=tLy6hJadL4w9JI/A/qLCG0V...peD1VHSzgu/qirjOaA=

Example (VBA wrapper function)

Dim strSig As String
strSig = sigSignFile("abc.txt", "AlicePrivRSASign.p8e", "password", "", PKI_SIG_SHA256RSA)
Debug.Print "SIG=" & strSig
Debug.Print "OK =" & "tLy6hJadL4w9JI/A/qLCG0V...peD1VHSzgu/qirjOaA="

See Also

SIG_SignData

[Contents] [Index]