CryptEncodeObjectEx

[This is preliminary documentation and subject to change.]

The CryptEncodeObjectEx function encodes a structure of type lpszStructType. CryptEncodeObjectEx offers a significant performance improvement over CryptEncodeObject by supporting the memory allocation with the CRYPT_ENCODE_ALLOC_FLAG.

#include <wincrypt.h>
BOOL WINAPI CryptEncodeObjectEx(
  DWORD dwCertEncodingType,        // in
  LPCSTR lpszStructType,           // in
  const void *pvStructInfo,        // in
  DWORD dwFlags,                   // in
  PCRYPT_ENCODE_PARA pEncodePara,  // in, optional
  void *pvEncoded,                 // out
  DWORD *pcbEncoded                // in, out
);

Parameters

dwCertEncodingType

The type of encoding used. If the low-order word containing the certificate encoding type is nonzero, then it is used. Otherwise, the high-order word containing the message encoding type is used. If both are specified, the certificate encoding type in the low-order word is used.

The following encoding types can be combined with a bitwise OR operation:

Certificate Encoding type Value

CRYPT_ASN_ENCODING 0x00000001

X509_ASN_ENCODING 0x00000001

PKCS_7_ASN_ENCODING 0x00010000

lpszStructType

Certificate Encoding type	Value
CRYPT_ASN_ENCODING	0x00000001
X509_ASN_ENCODING	0x00000001
PKCS_7_ASN_ENCODING	0x00010000

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 given structure. Otherwise, this parameter is a long pointer to a null-terminated string.

For more details, see the table in CryptEncodeObject/CryptDecodeObject Functions that relates object identifier strings and predefined constants to their corresponding data structures.

pvStructInfo

Pointer to the structure to be encoded. The structure must be of the type specified by lpszStructType.

dwFlags

Flag values.

The following flags can be combined with a bitwise OR operation into CryptEncodeObjectEx dwFlags.

CRYPT_ENCODE_ALLOC_FLAG

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

If pEncodePara or pEncodePara->pfnAlloc is NULL, then, LocalAlloc is called for the allocation and LocalFree 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 <= 0xFF, the CERT_RDN_T61_STRING is selected instead of the 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.

pEncodePara

Pointer to the CRYPT_ENCODE_PARA structure containing the encoded paragraph information. If pEncodePara is set to NULL, the LocalAlloc and LocalFree are used to allocate and free memory. If pEncodePara points to a CRYPT_ENCODE_PARA structure that function can pass in the callback function to allocate and free memory. This function overrides the default memory allocation of LocalAlloc and LocalFree.

pvEncoded

Pointer to a buffer that receives the encoded structure. When the buffer that is specified is not large enough to receive the decoded structure, the function sets ERROR_MORE_DATA and stores the required buffer size, in bytes, into the variable pointed to by pcbEncoded.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Common In/Out Parameter Conventions.

When the CRYPT_ENCODE_ALLOC_FLAG is set, pvEncoded is the address of a pointer to the buffer that will be updated. Because memory is allocated and the pointer is stored at *pvEncoded, pvEncoded must always be non-NULL.

pcbEncoded

Pointer to a DWORD that contains the size, in bytes, of the buffer pointed to by the pvEncoded parameter. When the function returns, the variable pointed to by the pcbEncoded parameter contains the number of allocated, encoded bytes stored in the buffer. This parameter can be NULL, only if pvEncoded is NULL.

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

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may 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 Values

TRUE if the function succeeded, FALSE if the function failed.

Call GetLastError to see the reason for any failures. This function has the following error codes.

Error code	Description
CRYPT_E_BAD_ENCODE	An error was encountered while encoding.
CRYPT_E_OSS_ERROR	ASN.1 encoding error. Note, to get the OSS error subtract the value in CRYPT_E_OSS_ERROR from the returned error value and see asn1code.h for details on the error.
ERROR_FILE_NOT_FOUND	An encoding function could not be found for the specified dwCertEncodingType and lpszStructType.
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, in the variable pointed to by pcbEncoded.

Remarks

CryptEncodeObjectEx first looks for an installable Ex encode function. If no Ex encode function is found, then the old non-Ex installable function is located.

Example

// EXAMPLE CODE FOR USING CryptEncodeObjectEx().
char *Cert_Sub_Name ="Elizabeth Jackson";
#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

// Initialize a single RDN struture.
CERT_RDN_ATTR rgNameAttr = {
   "2.5.4.3",                 // pszObjId
   CERT_RDN_PRINTABLE_STRING, // dwValueType
   strlen(Cert_Sub_Name),     // value.cbData
   (BYTE *)Cert_Sub_Name};    // value.pbData

// Initialize a structure that includes an array of RDN structures.
CERT_RDN rgRDN[] = {
      1,                      // rgRDN.cRDNAttr
      &rgNameAttr};           // rgRDN.rgRDNAttr

// Initialize a CERT_NAME_INFO structure that includes a CERT_RND.
CERT_NAME_INFO CertName = {
       1,                     // CertName. cRDN = number of elements
                              //   in the CERT_RND's array.
       rgRDN};                // CertName.rgRDN

VOID *pvEncoded;
DWORD cbEncoded;
BOOL fResult;

// CryptEncodeObjectEx function call.
fResult= CryptEncodeObjectEx(
           MY_ENCODING_TYPE,  // in- Encoding/decoding type.
           X509_NAME,         // in- Struct type
           &CertName,         // in- Address of CERT_NAME_INFO
                              //   struct.
           CRYPT_ENCODE_ALLOC_FLAG,
                              // in- dwFlags
           NULL,              // in, optional- EncodePara set to NULL.
                              //   to use default memory allocation of
                              //   LocalAlloc and LocalFree.
           (void*) &pvEncoded,// out- address of a pointer to be
                              //   updated.
           &cbEncoded);       // in, out address of a DWORD to be
                              //   updated.
if (!fResult) {               // FALSE returned- function failed.
    printf("The call to CryptEncodeObjectEx failed.\n\n");
    }
else {                        // TRUE returned- function successful.
    printf("The call to CryptEncodeObjectEx succeeded.\n\n");
    }

// Free the memory.
LocalFree(pvEncoded);
printf("The function ran to completion.\n\n");

QuickInfo