Função CryptMsgGetParam (wincrypt.h)
A função CryptMsgGetParam adquire um parâmetro de mensagem depois que uma mensagem criptográfica é codificada ou decodificada. Essa função é chamada após a chamada cryptMsgUpdate final.
Sintaxe
BOOL CryptMsgGetParam(
[in] HCRYPTMSG hCryptMsg,
[in] DWORD dwParamType,
[in] DWORD dwIndex,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Parâmetros
[in] hCryptMsg
Identificador de uma mensagem criptográfica.
[in] dwParamType
Indica os tipos de parâmetro de dados a serem recuperados. O tipo de dados a ser recuperado determina o tipo de estrutura a ser usada para pvData.
Para uma mensagem codificada, somente os CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM e CMSG_COMPUTED_HASH_PARAM dwParamTypesão válidos.
| Valor | Significado |
|---|---|
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna a contagem dos certificados de atributo em uma mensagem SIGNED ou ENVELOPED. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Recupera um certificado de atributo. Para obter todos os certificados de atributo, chame CryptMsgGetParamvariando dwIndex definido como 0 o número de atributos menos um. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Recupera o conteúdo codificado de uma mensagem criptográfica codificada, sem a camada externa da estrutura CONTENT_INFO. Ou seja, somente a codificação do campo ContentInfo.content definido por PKCS nº 7 é retornada. |
|
Tipo de dados pvData: ponteiro para DWORD
Retorna o número de certificados em uma mensagem SIGNED ou ENVELOPED recebida. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o certificado de um signatário. Para obter todos os certificados do signatário, chame CryptMsgGetParam, variando dwIndex de 0 para o número de certificados disponíveis menos um. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o hash calculado dos dados na mensagem. Esse tipo é aplicável à codificação e à decodificação. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna toda a mensagem PKCS nº 7 de uma mensagem aberta para codificar. Recupera o conteúdo interno de uma mensagem aberta para decodificar. Se a mensagem estiver envolvida, o tipo interno será data e CryptMsgControl tiver sido chamado para descriptografar a mensagem, o conteúdo descriptografado será retornado. Se o tipo interno não for dados, o BLOB codificado que requer mais decodificação será retornado. Se a mensagem não estiver envolvida e o conteúdo interno for DATA, os dados retornados serão os octetos do conteúdo interno. Esse tipo é aplicável à codificação e à decodificação. Para decodificação, se o tipo for CMSG_DATA, os octetos do conteúdo serão retornados; else, o conteúdo interno codificado é retornado. |
|
Tipo de dados pvData: ponteiro para DWORD
Retorna a contagem de CRLs em uma mensagem recebida, ASSINADA ou ENVELOPED. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna uma CRL. Para obter todas as CRLs, chame CryptMsgGetParam, variando dwIndex de 0 para o número de CRLs disponíveis menos uma. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Altera o conteúdo de uma mensagem já codificada. A mensagem deve primeiro ser decodificada com uma chamada para CryptMsgOpenToDecode. Em seguida, a alteração na mensagem é feita por meio de uma chamada para CryptMsgControl, CryptMsgCountersign ou CryptMsgCountersignEncoded. Em seguida, a mensagem é codificada novamente com uma chamada para CryptMsgGetParam, especificando CMSG_ENCODED_MESSAGE para obter uma nova codificação que reflita as alterações feitas. Isso pode ser usado, por exemplo, para adicionar um atributo de carimbo de data/hora a uma mensagem. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna as informações codificadas CMSG_SIGNER_INFO signatário para um signatário de mensagem. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o hash criptografado de uma assinatura. Normalmente usado para executar carimbo de data/hora. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER.
Retorna o algoritmo de criptografia usado para criptografar a mensagem. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER.
Retorna o algoritmo de criptografia usado para criptografar uma mensagem ENVELOPED. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER.
Retorna o algoritmo de hash usado para hash da mensagem quando ela foi criada. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o valor de hash armazenado na mensagem quando ele foi criado. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma cadeia de caracteres OID (identificador de objeto terminada em nulo).
Retorna o tipo de conteúdo interno de uma mensagem recebida. Esse tipo não é aplicável a mensagens do tipo DATA. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o número de destinatários de transporte de chave de uma mensagem ENVELOPED recebida. |
|
Tipo de dados pvData: ponteiro para DWORD
Retorna a contagem total de todos os destinatários de mensagens, incluindo os destinatários do contrato de chave e da lista de emails. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o índice do destinatário de transporte de chave usado para descriptografar uma mensagem ENVELOPED. Esse valor só estará disponível depois que uma mensagem tiver sido descriptografada. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o índice do transporte de chaves, do contrato de chave ou do destinatário da lista de emails usado para descriptografar uma mensagem ENVELOPED. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o índice da chave criptografada de um destinatário de contrato de chave usado para descriptografar uma mensagem ENVELOPED. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CERT_INFO.
Retorna informações de certificado sobre o destinatário de uma mensagem de transporte de chave. Para obter informações de certificado sobre todos os destinatários da mensagem de transporte de chave, chame repetidamente CryptMsgGetParam, variando dwIndex de 0 para o número de destinatários menos um. Somente os membros Issuer, SerialNumber e PublicKeyAlgorithm da estrutura CERT_INFO retornada estão disponíveis e são válidos. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_CMS_RECIPIENT_INFO.
Retorna informações sobre um transporte de chave, contrato de chave ou destinatário da lista de emails. Ele não se limita aos destinatários de mensagens de transporte de chave. Para obter informações sobre todos os destinatários de uma mensagem, chame repetidamente CryptMsgGetParam, variando dwIndex de 0 para o número de destinatários menos um. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CRYPT_ATTRIBUTES.
Retorna os atributos autenticados de um signatário de mensagem. Para recuperar os atributos autenticados para um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber a estrutura CERT_INFO.
Retorna informações sobre um signatário de mensagem necessário para identificar o certificado do signatário. O Emissor e o SerialNumber de um certificado podem ser usados para identificar exclusivamente um certificado para recuperação. Para recuperar informações para todos os signatários, chame repetidamente CryptMsgGetParamvariando dwIndex de 0 para o número de signatários menos um. Somente os campos Emissor e SerialNumber na estrutura CERT_INFO retornada contêm dados disponíveis e válidos. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CERT_ID.
Retorna informações sobre um signatário de mensagem necessário para identificar a chave pública do signatário. Isso pode ser um Emissor e SerialNumber de um certificado, um KeyID ou um HashId. Para recuperar informações para todos os signatários, chame CryptMsgGetParamvariando dwIndex de 0 para o número de signatários menos um. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o número de signatários de uma mensagem SIGNED recebida. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber a estrutura CRYPT_ALGORITHM_IDENTIFIER.
Retorna o algoritmo de hash usado por um signatário da mensagem. Para obter o algoritmo de hash para um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_SIGNER_INFO.
Retorna informações sobre um signatário de mensagem. Isso inclui o emissor e o número de série do certificado do signatário e atributos autenticados e não autenticados do certificado do signatário. Para recuperar informações do signatário em todos os signatários de uma mensagem, chame CryptMsgGetParam variando dwIndex de 0 para o número de signatários menos um. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura de CMSG_CMS_SIGNER_INFO.
Retorna informações sobre um signatário de mensagem. Isso inclui um signerId e atributos autenticados e não autenticados. Para recuperar informações do signatário em todos os signatários de uma mensagem, chame CryptMsgGetParam variando dwIndex de 0 para o número de signatários menos um. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CRYPT_ATTRIBUTES.
Retorna os atributos não autenticados de um signatário de mensagem. Para recuperar os atributos não autenticados de um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna o tipo de mensagem de uma mensagem decodificada de tipo desconhecido. O tipo de mensagem recuperado pode ser comparado aos tipos com suporte para determinar se o processamento pode continuar. Para tipos de mensagem com suporte, consulte o parâmetro dwMessageType de CryptMsgOpenToDecode. |
|
Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_ATTR.
Retorna os atributos desprotegidos em uma mensagem em envelope. |
|
Tipo de dados pvData: ponteiro para um DWORD
Retorna a versão da mensagem decodificada. Para obter mais informações, consulte a tabela na seção Comentários. |
[in] dwIndex
Índice para o parâmetro que está sendo recuperado, quando aplicável. Quando um parâmetro não está sendo recuperado, esse parâmetro é ignorado e é definido como zero.
[out] pvData
Um ponteiro para um buffer que recebe os dados recuperados. A forma desses dados variará dependendo do valor do parâmetro dwParamType .
Esse parâmetro pode ser NULL para definir o tamanho dessas informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
Ao processar os dados retornados nesse buffer, os aplicativos precisam usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.
[in, out] pcbData
Um ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData . Quando a função retorna, a variável apontada pelo parâmetro pcbData contém o número de bytes armazenados no buffer.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).
Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.
A tabela a seguir lista os códigos de erro mais comumente retornados pela função GetLastError .
| Código de retorno | Descrição |
|---|---|
|
A mensagem não contém os atributos solicitados. |
|
O valor do índice não é válido. |
|
O tipo de mensagem não é válido. |
|
O conteúdo da mensagem ainda não foi descriptografado. |
|
O identificador de objeto está mal formatado. |
|
A mensagem não está codificada conforme o esperado. |
|
Um ou mais argumentos não são válidos. |
|
O buffer especificado não é grande o suficiente para manter os dados retornados. |
Para CMSG_COMPUTED_HASH_PARAM dwParamType , um erro pode ser propagado de CryptGetHashParam.
Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.
Comentários
Os seguintes números de versão são retornados por chamadas para CryptMsgGetParam com dwParamType definido como CMSG_VERSION_PARAM são definidos:
- CMSG_SIGNED_DATA_V1
- CMSG_SIGNED_DATA_V3
- CMSG_SIGNED_DATA_PKCS_1_5_VERSION
- CMSG_SIGNED_DATA_CMS_VERSION
- CMSG_SIGNER_INFO_V1
- CMSG_SIGNER_INFO_V3
- CMSG_SIGNER_INFO_PKCS_1_5_VERSION
- CMSG_SIGNER_INFO_CMS_VERSION
- CMSG_HASHED_DATA_V0
- CMSG_HASHED_DATA_V2
- CMSG_HASHED_DATA_PKCS_1_5_VERSION
- CMSG_HASHED_DATA_CMS_VERSION
- CMSG_ENVELOPED_DATA_V0
- CMSG_ENVELOPED_DATA_V2
- CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
- CMSG_ENVELOPED_DATA_CMS_VERSION
Exemplos
Para obter um exemplo que usa 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 encolhida, exemplo de programa C: codificação de um envelope, mensagem assinada e exemplo de programa C: codificação e decodificação de uma mensagem com hash.
Requisitos
| 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 |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de