CryptDecodeObjectEx

[This is preliminary documentation and subject to change.]

The CryptDecodeObjectEx function decodes a structure of type lpszStructType. CryptDecodeObjectEx offers a significant performance improvement over CryptDecodeObject by supporting the memory allocation with the CRYPT_DECODE_ALLOC_FLAG.

#include <wincrypt.h>
BOOL WINAPI CryptDecodeObjectEx(
  DWORD dwCertEncodingType,        // in
  LPCSTR lpszStructType,           // in
  const BYTE *pbEncoded,           // in
  DWORD cbEncoded,                 // in
  DWORD dwFlags,                   // in
  PCRYPT_DECODE_PARA pDecodePara,  // in, optional
  void *pvStructInfo,              // out, optional
  DWORD *pcbStructInfo             // in, out
);
 

Parameters

dwCertEncodingType

Type of encoding used. If the low-order word containing the certificate encoding type is nonzero, 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.

Currently defined encoding types are shown in the following table:

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

lpszStructType

Pointer to an OID defining the structure type. If the high-order word of the lpszStructType parameter is zero, the low-order word specifies the 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.

pbEncoded

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

cbEncoded

Number of bytes pointed to by pbEncoded. This is the number of bytes to be decoded.

dwFlags

Flag values.

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

CRYPT_DECODE_ALLOC_FLAG

The called decoding function allocates memory for the decoded structure. A pointer to the allocated structure is returned in pvStructInfo.

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

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

CRYPT_DECODE_NOCOPY_FLAG

This flag can be set to enable a "no copy" optimization. This optimization updates the pvStructInfo fields to point to content residing within pbEncoded instead of making a copy of the content and appending it to pvStructInfo. The calling application needs to allocate less memory and execution is faster because a copy is not made. Note that when performing a "no copy" decoding, pbEncoded can't be freed until pvStructInfo is freed.

CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG

This flag is applicable when decoding X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE, or X509_UNICODE_ANY_STRING. By default, CERT_RDN_T61_STRING encoded values are initially decoded as UTF8. If the UTF8 decoding fails, then the value is decoded as 8 bit characters. If this flag is set, it skips the initial attempt to decode the value as UTF8, and decodes the value as 8 bit characters.

pDecodePara

Pointer to the CRYPT_DECODE_PARA structure containing the encoded paragraph information. If pDecodePara is set to NULL, the LocalAlloc and LocalFree are used to allocate and free memory. If pDecodePara points to a CRYPT_DECODE_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.

pvStructInfo

Pointer to a buffer that receives the decoded 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 pcbStructInfo.

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_DECODE_ALLOC_FLAG is set, pvStructInfo is the address of a pointer to the buffer that will be updated. Because memory is allocated and its pointer is stored at *pvStructInfo, pvStructInfo must always be non-NULL.

pcbStructInfo

Pointer to a DWORD that contains the size, in bytes, of the buffer pointed to by the pvStructInfo parameter. When the function returns, the variable pointed to by the pcbStructInfo parameter contains the number of bytes stored in the buffer. The size contained in the variable pointed to by pcbStructInfo may indicate a size larger than the decoded structure, as the decoded structure may have pointers to auxiliary data. This size will be the sum of the size needed by the decoded structure and the auxiliary data. This parameter can be NULL, only if pvStructInfo is NULL.

When the CRYPT_DECODE_ALLOC_FLAG is set, pcbStructInfo 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. The function has the following error codes:

Example

// EXAMPLE CODE FOR USING CryptDecodeObjectEx().
// Assume that pointers to the data to be decoded
// (pbEncoded) and the # of bytes to be decoded (cbEncoded)
// are initialized elsewhere.
#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

// Declare and initialize.
const BYTE *pbEncoded;         // Initialized elsewhere
DWORD cbEncoded;               // Initialized elsewhere
PCRYPT_DECODE_PARA DecodePara;
void *pvStructInfo;
DWORD cbStructInfo;
BOOL fResult;
DecodePara->cbSize= sizeof(PCRYPT_DECODE_PARA);

// CryptDecodeObjectEx function call.
fResult= CryptDecodeObjectEx(
          MY_ENCODING_TYPE,    // in- Encoding/decoding type.
          X509_NAME,           // in- Struct type
          pbEncoded,           // in- Data to be decoded.
          cbEncoded,           // in- # of bytes of pbEncoded.
          CRYPT_DECODE_ALLOC_FLAG,
                               // in- dwFlags
          NULL,                // in, optional- DecodePara set to NULL
                               //   to use default memory allocation
                               //   of+ LocalAlloc and LocalFree.
          (void*) &pvStructInfo,
                               // out, optional- pvStructInfo
          &cbStructInfo);      // in, out- pvStructInfo size

if(!fResult) {                 // FALSE returned- function failed.
    printf("The call to CryptDecodeObjectEx failed.\n");
}

else {                         // TRUE returned- function successful.
    printf("The call to CryptDecodeObjectEx successful.\n");
}

// Free the memory.
LocalFree(pvStructInfo);
 

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.

See Also

CryptEncodeObject, CryptEncodeObjectEx, CryptDecodeObject