Edit

Share via

CryptSignAndEncodeCertificate function (wincrypt.h)

  • Article

The CryptSignAndEncodeCertificate function encodes and signs a certificate, certificate revocation list (CRL), certificate trust list (CTL), or certificate request.

This function performs the following operations:

  • Calls CryptEncodeObject using lpszStructType to encode the "to be signed" information.
  • Calls CryptSignCertificate to sign this encoded information.
  • Calls CryptEncodeObject again, with lpszStructType set to X509_CERT, to further encode the resulting signed, encoded information.

Syntax

BOOL CryptSignAndEncodeCertificate(
  [in]      BCRYPT_KEY_HANDLE           hBCryptKey,
  [in]      DWORD                       dwKeySpec,
  [in]      DWORD                       dwCertEncodingType,
  [in]      LPCSTR                      lpszStructType,
  [in]      const void                  *pvStructInfo,
  [in]      PCRYPT_ALGORITHM_IDENTIFIER pSignatureAlgorithm,
  [in]      const void                  *pvHashAuxInfo,
  [out]     BYTE                        *pbEncoded,
  [in, out] DWORD                       *pcbEncoded
);

Parameters

[in] hBCryptKey

A handle of the cryptographic service provider (CSP) to do the signature. This handle is an HCRYPTPROV handle that has been created by using the CryptAcquireContext function or an NCRYPT_KEY_HANDLE handle that has been created by using the NCryptOpenKey function. New applications should always pass in a NCRYPT_KEY_HANDLE handle of a CNG CSP.

[in] dwKeySpec

Identifies the private key to use from the provider's container. This must be one of the following values. This parameter is ignored if a CNG key is passed in the hCryptProvOrNCryptKey parameter.

Value Meaning
AT_KEYEXCHANGE
 Use the key exchange key.
AT_SIGNATURE
 Use the digital signature key.

[in] dwCertEncodingType

Specifies the encoding type used. This can be the following value.

Value Meaning
X509_ASN_ENCODING
 Specifies X.509 certificate encoding.

[in] lpszStructType

A pointer to a null-terminated ANSI string that contains the type of data to be encoded and signed. The following predefined lpszStructType constants are used with encode operations.

Value Meaning
X509_CERT_CRL_TO_BE_SIGNED
 pvStructInfo is the address of a CRL_INFO structure.
X509_CERT_REQUEST_TO_BE_SIGNED
 pvStructInfo is the address of a CERT_REQUEST_INFO structure.
X509_CERT_TO_BE_SIGNED
 pvStructInfo is the address of a CERT_INFO structure.
X509_KEYGEN_REQUEST_TO_BE_SIGNED
 pvStructInfo is the address of a CERT_KEYGEN_REQUEST_INFO structure.

[in] pvStructInfo

The address of a structure that contains the data to be signed and encoded. The format of this structure is determined by the lpszStructType parameter.

[in] pSignatureAlgorithm

A pointer to a CRYPT_ALGORITHM_IDENTIFIER structure that contains the object identifier (OID) of the signature algorithm and any additional parameters needed. This function uses the following algorithm OIDs:

  • szOID_RSA_MD5RSA
  • szOID_RSA_SHA1RSA
  • szOID_X957_SHA1DSA
If the signature algorithm is a hash algorithm, the signature contains only the unencrypted hash octets. A private key is not used to encrypt the hash. dwKeySpec is not used and hCryptProvOrNCryptKey can be NULL if an appropriate default CSP can be used for hashing.

[in] pvHashAuxInfo

Reserved. Must be NULL.

[out] pbEncoded

A pointer to a buffer to receive the signed and encoded output.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Retrieving Data of Unknown Length.

[in, out] pcbEncoded

A pointer to a DWORD that contains the size, in bytes, of the buffer pointed to by the pbEncoded parameter. When the function returns, the DWORD contains the number of bytes stored or to be stored in the buffer.

Note  When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.
 

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.

Note  Errors from the called functions CryptCreateHash, CryptSignHash and CryptHashData might be propagated to this function.
 
Possible error codes include, but are not limited to, the following.
Return code Description
ERROR_MORE_DATA
 If the buffer specified by the pbEncoded parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, into the variable pointed to by pcbEncoded.
ERROR_FILE_NOT_FOUND
 Invalid certificate encoding type. Currently only X509_ASN_ENCODING is supported.
NTE_BAD_ALGID
 The signature algorithm's OID does not map to a known or supported hash algorithm.
CRYPT_E_BAD_ENCODE
 An error was encountered while encoding or decoding. The most likely cause of this error is the improper initialization of the fields in the structure pointed to by pvStructInfo.
 

If the function fails, GetLastError may return an Abstract Syntax Notation One (ASN.1) encoding/decoding error. For information about these errors, see ASN.1 Encoding/Decoding Return Values.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

See also

CryptSignCertificate

Data Management Functions