Share via

CryptEncodeObjectEx (Compact 2013)

  • Article

3/28/2014

This function encodes a structure of the type indicated by the value of the lpszStructType parameter. This function offers a significant performance improvement over the CryptEncodeObject function by supporting memory allocation with the CRYPT_ENCODE_ALLOC_FLAG value.

Syntax

BOOL WINAPI CryptEncodeObjectEx(
  DWORD dwCertEncodingType, 
  LPCSTR lpszStructType, 
  const void* pvStructInfo, 
  DWORD dwFlags, 
  PCRYPT_ENCODE_PARA pEncodePara, 
  void* pvEncoded, 
  DWORD* pcbEncoded
);

Parameters

  • dwCertEncodingType
    [in] Specifies the type of encoding used. Only X509_ASN_ENCODING is used.

    Either a certificate or message encoding type is required. X509_ASN_ENCODING is the default. If that type is indicated, it is used. Otherwise, if the PKCS7_ASN_ENCODING type is indicated, it is used.

  • lpszStructType
    [in] Pointer to an OID defining the structure type. If the high-order word of the lpszStructType parameter is zero, the low-order word specifies an integer identifier for the type of the specified structure. Otherwise, this parameter is a long pointer to a NULL-terminated string.
  • pvStructInfo
    [in] Pointer to the structure to be encoded. The structure must be of the type specified by the lpszStructType parameter.

  • dwFlags
    [in] Bitmask of flags. The following table shows the flags that can be combined with bitwise OR operations.

    Value

    Description

    CRYPT_ENCODE_ALLOC_FLAG

    The called encoding function allocates memory for the encoded bytes. A pointer to the allocated bytes is returned in the pvEncoded parameter.

    If pEncodePara or pEncodePara->pfnAlloc is NULL, then the LocalAlloc function is called for the allocation and the LocalFree function must be called to free the memory.

    If pEncodePara and pEncodePara->pfnAlloc are non-NULL, then pEncodePara->pfnAlloc is called for the allocation and the function pointed to by pEncodePara->pfnFree must be called to free the memory.

    CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG

    This flag is applicable when encoding X509_UNICODE_NAME. If this flag is set and all the Unicode characters are less than or equal to 0xFF, CERT_RDN_T61_STRING is selected instead of CERT_RDN_UNICODE_STRING.

    CRYPT_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG

    This flag is applicable when encoding X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE, or X509_UNICODE_ANY_STRING. If this flag is set, the characters are not checked to see if they are valid for the specified value type.

    CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG

    This flag is applicable when encoding an X509_UNICODE_NAME. When set, CERT_RDN_UTF8_STRING is selected instead of CERT_RDN_UNICODE_STRING.
  • pEncodePara
    [in] Optional. Pointer to a CRYPT_ENCODE_PARA structure containing encoding information. If the pEncodePara parameter is set to NULL, the LocalAlloc and LocalFree functions are used to allocate and free memory. If the pEncodePara parameter points to a CRYPT_ENCODE_PARA structure, that structure passes in callback functions to allocate and free memory. These functions override the default memory allocation of the LocalAlloc and LocalFree functions.

  • pvEncoded
    [out] Pointer to a buffer to receive the encoded structure. When the buffer that is specified is not large enough to receive the decoded structure, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, in the variable pointed to by the pcbEncoded parameter.

    The pvEncoded parameter can be NULL to retrieve the size of the buffer for memory allocation purposes.

    If the dwFlags parameter is set to CRYPT_ENCODE_ALLOC_FLAG, the pvEncoded parameter is not a pointer to a buffer but is the address of a pointer to the buffer. Because memory is allocated inside the function and the pointer is stored at *pvEncoded, the pvEncoded parameter must always be non-NULL.

  • pcbEncoded
    [in, out] On input, pointer to a DWORD that contains the size, in bytes, of the buffer pointed to by the pvEncoded parameter. On output, the variable pointed to by the pcbEncoded parameter contains the number of allocated, encoded bytes stored in the buffer.

    When CRYPT_ENCODE_ALLOC_FLAG is set, the pcbEncoded parameter is the address of a pointer to the DWORD that is updated.

    When processing the data returned in the buffer, applications must 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 fits 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, or TRUE.

If the function fails, the return value is zero, or FALSE.

For extended error information, call the GetLastError function. The following table shows a list of possible error codes.

Value

Description

CRYPT_E_BAD_ENCODE

An error was encountered while decoding.

ERROR_FILE_NOT_FOUND

A decoding function could not be found for the specified dwCertEncodingType and lpszStructType parameters.

ERROR_MORE_DATA

If the buffer specified by the pvStructInfo 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, in the variable pointed to by the pcbStructInfo parameter.

Remarks

This function first looks for an installable extended encoding function. If no extended encoding function is found, the old, nonextended, installable function is located.

The desktop operating system supports the flag PKCS_7_ASN_ENCODING, but Windows Embedded Compact does not and ignores the flag when it is specified.

Requirements

Header

wincrypt.h

Library

crypt32.lib

See Also

Reference

Certificates Functions
CryptDecodeObjectEx
LocalAlloc
LocalFree
CRYPT_ENCODE_PARA