Função CryptMsgOpenToEncode (wincrypt.h)

Artigo
03/03/2024

A função CryptMsgOpenToEncode abre uma mensagem criptográfica para codificação e retorna um identificador da mensagem aberta. A mensagem permanece aberta até que CryptMsgClose seja chamado.

Sintaxe

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 o tipo de codificação usado. É sempre aceitável especificar os tipos de codificação de certificado e mensagem combinando-os com uma operação OR bit a bit, conforme mostrado no exemplo a seguir:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Os tipos de codificação definidos no momento são:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

DwFlags definidos no momento são mostrados na tabela a seguir.

Valor	Significado
CMSG_BARE_CONTENT_FLAG	A saída transmitida não terá um wrapper ContentInfo externo (conforme definido pelo PKCS nº 7). Isso torna adequado ser transmitido para uma mensagem delimitada.
CMSG_DETACHED_FLAG	Há dados desanexados sendo fornecidos para as chamadas subsequentes para CryptMsgUpdate.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Os atributos autenticados são forçados a serem incluídos no SignerInfo (conforme definido pelo PKCS nº 7) nos casos em que não seriam necessários de outra forma.
CMSG_CONTENTS_OCTETS_FLAG	Usado ao calcular o tamanho de uma mensagem que foi codificada usando Distinguished Encoding Rules (DER) e que está aninhada dentro de uma mensagem enveloped. Isso é particularmente útil ao executar streaming.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Quando definido, o conteúdo interno do tipo não de dados é encapsulado em uma CADEIA DE CARACTERES OCTET. Aplicável a mensagens assinadas e envelopes.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Se definido, o hCryptProv que é passado para essa função é liberado no CryptMsgUpdate final. O identificador não será liberado se a função falhar. Nota Os hCryptProvdos destinatários do envelope não são liberados.

[in] dwMsgType

Indica o tipo de mensagem. Esse deve ser um dos valores a seguir.

Valor	Significado
CMSG_DATA	Este valor não é usado.
CMSG_SIGNED	O parâmetro pvMsgEncodeInfo é o endereço de uma estrutura CMSG_SIGNED_ENCODE_INFO que contém as informações de codificação.
CMSG_ENVELOPED	O parâmetro pvMsgEncodeInfo é o endereço de uma estrutura CMSG_ENVELOPED_ENCODE_INFO que contém as informações de codificação.
CMSG_SIGNED_AND_ENVELOPED	Esse valor não está implementado no momento.
CMSG_HASHED	O parâmetro pvMsgEncodeInfo é o endereço de uma estrutura CMSG_HASHED_ENCODE_INFO que contém as informações de codificação.

[in] pvMsgEncodeInfo

O endereço de uma estrutura que contém as informações de codificação. O tipo de dados depende do valor do parâmetro dwMsgType . Para obter detalhes, consulte dwMsgType.

[in, optional] pszInnerContentObjID

Se CryptMsgCalculateEncodedLength for chamado e os dados de CryptMsgUpdate já tiverem sido codificados por mensagem, o OID ( identificador de objeto ) apropriado será passado em pszInnerContentObjID. Se pszInnerContentObjID for NULL, supõe-se que o tipo de conteúdo interno não tenha sido codificado anteriormente e, portanto, seja codificado como uma cadeia de caracteres de octeto e dado o tipo CMSG_DATA.

Nota Quando o streaming está sendo usado, pszInnerContentObjID deve ser NULL ou szOID_RSA_data.

Os OIDs do algoritmo a seguir são comumente usados. Um usuário pode definir o novo uso de conteúdo interno garantindo que o remetente e o receptor da mensagem concordem com a semântica associada ao 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

Quando o streaming está sendo usado, esse parâmetro é o endereço de uma estrutura CMSG_STREAM_INFO . A função de retorno de chamada especificada pelo membro pfnStreamOutput da estrutura CMSG_STREAM_INFO é chamada quando CryptMsgUpdate é executado. O retorno de chamada é passado pelos bytes codificados resultantes da codificação. Para obter mais informações sobre como usar o retorno de chamada, consulte CMSG_STREAM_INFO.

Nota Quando o streaming está sendo usado, o aplicativo não deve liberar os identificadores de dados que são passados no parâmetro pvMsgEncodeInfo , como o identificador do provedor no membro hCryptProv da estrutura CMSG_SIGNER_ENCODE_INFO , até que o identificador de mensagem retornado por essa função seja fechado usando a função CryptMsgClose .

Quando o streaming não está sendo usado, esse parâmetro é definido como NULL.

O streaming não é usado com o tipo de mensagem CMSG_HASHED . Ao lidar com dados com hash, esse parâmetro deve ser definido como NULL.

Considere o caso de uma mensagem assinada sendo colocada em uma mensagem em envelope. A saída codificada da codificação transmitida dos feeds de mensagens assinadas em outra codificação de streaming da mensagem enveloped. O retorno de chamada para a codificação de streaming chama CryptMsgUpdate para codificar a mensagem enveloped. O retorno de chamada para a mensagem envelopeda recebe os bytes codificados da mensagem assinada aninhada.

Retornar valor

Se a função for bem-sucedida, ela retornará um identificador para a mensagem aberta. Esse identificador deve ser fechado quando não for mais necessário passando-o para a função CryptMsgClose .

Se essa função falhar, NULL será retornado.

Para recuperar informações de erro estendidas, use a função GetLastError .

A tabela a seguir lista os códigos de erro mais comumente retornados pela função GetLastError .

Código de retorno	Descrição
CRYPT_E_INVALID_MSG_TYPE	O tipo de mensagem não é válido.
CRYPT_E_OID_FORMAT	O OID está mal formatado.
CRYPT_E_UNKNOWN_ALGO	O algoritmo criptográfico é desconhecido.
E_INVALIDARG	Um ou mais argumentos não são válidos.
E_OUTOFMEMORY	Não há memória suficiente.

Além disso, se dwMsgType for CMSG_SIGNED, os erros poderão ser propagados de CryptCreateHash.

Se dwMsgType for CMSG_ENVELOPED, os erros poderão ser propagados de CryptGenKey, CryptImportKey e CryptExportKey.

Se dwMsgType for CMSG_HASHED, erros poderão ser propagados de CryptCreateHash.

Comentários

Para funções que executam criptografia, as chaves simétricas criptografadas são invertidas do formato little-endian para o formato big-endian depois que CryptExportKey é chamado internamente. Para funções que executam a descriptografia, as chaves simétricas criptografadas são invertidas do formato big-endian para o formato little-endian antes que CryptImportKey seja chamado.

CRYPT_NO_SALT é especificado quando chaves simétricas são geradas e importadas com CryptGenKey e CryptImportKey.

As mensagens criptografadas com o algoritmo de criptografia RC2 usam KP_EFFECTIVE_KEYLEN com CryptGetKeyParam para determinar o comprimento efetivo da chave RC2 importando ou exportando chaves.

Para mensagens criptografadas com o algoritmo de criptografia RC2, as operações de codificação e decodificação foram atualizadas para lidar com parâmetros ASN RC2 para o membro ContentEncryptionAlgorithm da estrutura CMSG_ENVELOPED_ENCODE_INFO .

Para mensagens criptografadas com os algoritmos de criptografia RC4, DES e 3DES, as operações de codificação e decodificação agora lidam com o parâmetro de cadeia de caracteres de octeto ASN IV para o membro ContentEncryptionAlgorithm da estrutura CMSG_ENVELOPED_ENCODE_INFO .

Exemplos

Para obter exemplos que usam essa função, consulte Exemplo de Programa C: Assinatura, Codificação, Decodificação e Verificação de uma Mensagem, Código Alternativo para Codificar uma Mensagem Enveloped, Exemplo de Programa C: Codificação de um Enveloped, Mensagem Assinada e Exemplo de Programa C: Codificação e Decodificação de uma Mensagem hash.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll