Función CryptMsgOpenToEncode (wincrypt.h)

Artículo
08/27/2023

La función CryptMsgOpenToEncode abre un mensaje criptográfico para codificar y devuelve un identificador del mensaje abierto. El mensaje permanece abierto hasta que se llama a CryptMsgClose .

Sintaxis

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

Parámetros

[in] dwMsgEncodingType

Especifica el tipo de codificación utilizado. Siempre es aceptable especificar los tipos de codificación de certificados y mensajes mediante su combinación con una operación OR bit a bit, como se muestra en el ejemplo siguiente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Los tipos de codificación definidos actualmente son:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

DwFlags definidos actualmente se muestran en la tabla siguiente.

Valor	Significado
CMSG_BARE_CONTENT_FLAG	La salida transmitida no tendrá un contenedor ContentInfo externo (según lo definido por PKCS #7). Esto hace que sea adecuado transmitirse en un mensaje envolvente.
CMSG_DETACHED_FLAG	Se proporcionan datos desasociados para las llamadas posteriores a CryptMsgUpdate.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Los atributos autenticados se ven obligados a incluirse en SignerInfo (como se define en PKCS #7) en los casos en los que no se requieran de otro modo.
CMSG_CONTENTS_OCTETS_FLAG	Se usa al calcular el tamaño de un mensaje que se ha codificado mediante reglas de codificación distinguida (DER) y que está anidado dentro de un mensaje sobre. Esto es especialmente útil al realizar streaming.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Cuando se establece, el contenido interno que no es de tipo de datos se encapsula dentro de una CADENA OCTET. Aplicable a los mensajes firmados y sobres.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Si se establece, el hCryptProv que se pasa a esta función se libera en el CryptMsgUpdate final. El identificador no se libera si se produce un error en la función. Nota Los hCryptProvde los destinatarios del sobre no se liberan.

[in] dwMsgType

Indica el tipo de mensaje. Debe ser uno de los valores siguientes.

Valor	Significado
CMSG_DATA	Este valor no se utiliza.
CMSG_SIGNED	El parámetro pvMsgEncodeInfo es la dirección de una estructura de CMSG_SIGNED_ENCODE_INFO que contiene la información de codificación.
CMSG_ENVELOPED	El parámetro pvMsgEncodeInfo es la dirección de una estructura de CMSG_ENVELOPED_ENCODE_INFO que contiene la información de codificación.
CMSG_SIGNED_AND_ENVELOPED	Este valor no está implementado actualmente.
CMSG_HASHED	El parámetro pvMsgEncodeInfo es la dirección de una estructura de CMSG_HASHED_ENCODE_INFO que contiene la información de codificación.

[in] pvMsgEncodeInfo

Dirección de una estructura que contiene la información de codificación. El tipo de datos depende del valor del parámetro dwMsgType . Para más información, consulte dwMsgType.

[in, optional] pszInnerContentObjID

Si se llama a CryptMsgCalculateEncodedLength y los datos de CryptMsgUpdate ya se han codificado en el mensaje, el identificador de objeto adecuado (OID) se pasa en pszInnerContentObjID. Si pszInnerContentObjID es NULL, se supone que el tipo de contenido interno no se ha codificado previamente y, por tanto, se codifica como una cadena de octeto y se le asigna el tipo CMSG_DATA.

Nota Cuando se usa el streaming, pszInnerContentObjID debe ser NULL o szOID_RSA_data.

Normalmente se usan los siguientes identificadores de identificadores de algoritmo. Un usuario puede definir un nuevo uso de contenido interno asegurándose de que el remitente y el receptor del mensaje aceptan la semántica asociada al OID.

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

Cuando se usa el streaming, este parámetro es la dirección de una estructura de CMSG_STREAM_INFO . Se llama a la función de devolución de llamada especificada por el miembro pfnStreamOutput de la estructura CMSG_STREAM_INFO cuando se ejecuta CryptMsgUpdate . La devolución de llamada se pasa a los bytes codificados que resultan de la codificación. Para obtener más información sobre cómo usar la devolución de llamada, consulte CMSG_STREAM_INFO.

Nota Cuando se usa el streaming, la aplicación no debe liberar ningún identificador de datos que se pase en el parámetro pvMsgEncodeInfo , como el identificador de proveedor en el miembro hCryptProv de la estructura de CMSG_SIGNER_ENCODE_INFO , hasta que se cierre el identificador de mensaje devuelto por esta función mediante la función CryptMsgClose .

Cuando no se usa el streaming, este parámetro se establece en NULL.

El streaming no se usa con el tipo de mensaje CMSG_HASHED . Al tratar con datos con hash, este parámetro debe establecerse en NULL.

Considere el caso de que un mensaje firmado se incluya en un mensaje sobre. La salida codificada de la codificación transmitida del mensaje firmado se introduce en otra codificación de streaming del mensaje sobre. La devolución de llamada de la codificación de streaming llama a CryptMsgUpdate para codificar el mensaje sobre. La devolución de llamada del mensaje sobre recibe los bytes codificados del mensaje firmado anidado.

Valor devuelto

Si la función se ejecuta correctamente, devuelve un identificador al mensaje abierto. Este identificador debe cerrarse cuando ya no sea necesario pasándolo a la función CryptMsgClose .

Si se produce un error en esta función, se devuelve NULL .

Para recuperar información de error extendida, use la función GetLastError .

En la tabla siguiente se enumeran los códigos de error devueltos normalmente por la función GetLastError .

Código devuelto	Descripción
CRYPT_E_INVALID_MSG_TYPE	Tipo de mensaje no válido.
CRYPT_E_OID_FORMAT	El OID tiene un formato incorrecto.
CRYPT_E_UNKNOWN_ALGO	El algoritmo criptográfico es desconocido.
E_INVALIDARG	Uno o varios argumentos no son válidos.
E_OUTOFMEMORY	No hay suficiente memoria.

Además, si dwMsgType es CMSG_SIGNED, los errores se pueden propagar desde CryptCreateHash.

Si dwMsgType es CMSG_ENVELOPED, los errores se pueden propagar desde CryptGenKey, CryptImportKey y CryptExportKey.

Si dwMsgType es CMSG_HASHED, los errores se pueden propagar desde CryptCreateHash.

Comentarios

En el caso de las funciones que realizan el cifrado, las claves simétricas cifradas se invierten del formato little-endian al formato big-endian después de llamar a CryptExportKey internamente. En el caso de las funciones que realizan el descifrado, las claves simétricas cifradas se invierten del formato big-endian al formato little-endian antes de llamar a CryptImportKey .

CRYPT_NO_SALT se especifica cuando se generan e importan claves simétricas con CryptGenKey y CryptImportKey.

Los mensajes cifrados con el algoritmo de cifrado RC2 usan KP_EFFECTIVE_KEYLEN con CryptGetKeyParam para determinar la longitud de clave efectiva de la clave RC2 importando o exportando claves.

En el caso de los mensajes cifrados con el algoritmo de cifrado RC2, se han actualizado las operaciones de codificación y descodificación para controlar los parámetros de ASN RC2 para el miembro ContentEncryptionAlgorithm de la estructura CMSG_ENVELOPED_ENCODE_INFO .

Para los mensajes cifrados con los algoritmos de cifrado RC4, DES y 3DES, las operaciones de codificación y descodificación ahora controlan el parámetro de cadena de octeto ASN IV para el miembro ContentEncryptionAlgorithm de la estructura CMSG_ENVELOPED_ENCODE_INFO .

Ejemplos

Para obtener ejemplos que usan esta función, vea Programa C de ejemplo: Firma, Codificación, Descodificación y Comprobación de un mensaje, Código alternativo para codificar un mensaje sobre, Ejemplo C Programa: Codificación de un mensaje con sobre, Mensaje firmado y Programa C de ejemplo: Codificación y Descodificación de un mensaje con hash.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll