Condividi tramite


Funzione CryptMsgControl (wincrypt.h)

La funzione CryptMsgControl esegue un'operazione di controllo dopo che un messaggio è stato decodificato da una chiamata finale alla funzione CryptMsgUpdate . Le operazioni di controllo fornite da questa funzione vengono usate per la decrittografia, la firma e la verifica hash e l'aggiunta e l'eliminazione di certificati, elenchi di revoche di certificati (CRL), firmatari e attributi non autenticati.

Modifiche importanti che influiscono sulla gestione dei messaggi in busta sono state apportate a CryptoAPI per supportare l'interoperabilità della posta elettronica S/MIME ( Secure/Multipurpose Internet Mail Extensions ). Per altre informazioni, vedere la sezione Osservazioni per la funzione CryptMsgOpenToEncode .

Sintassi

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Parametri

[in] hCryptMsg

Handle di un messaggio di crittografia per il quale deve essere applicato un controllo.

[in] dwFlags

Il valore seguente viene definito quando il parametro dwCtrlType è uno dei seguenti:

  • CMSG_CTRL_DECRYPT
  • CMSG_CTRL_KEY_TRANS_DECRYPT
  • CMSG_CTRL_KEY_AGREE_DECRYPT
  • CMSG_CTRL_MAIL_LIST_DECRYPT
Valore Significato
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
L'handle per il provider di crittografia viene rilasciato nella chiamata finale alla funzione CryptMsgClose . Questo handle non viene rilasciato se la funzione CryptMsgControl ha esito negativo.
 

Se il parametro dwCtrlType non specifica un'operazione di decrittografia, impostare questo valore su zero.

[in] dwCtrlType

Tipo di operazione da eseguire. I tipi di controllo messaggi attualmente definiti e il tipo di struttura che devono essere passati al parametro pvCtrlPara sono illustrati nella tabella seguente.

Valore Significato
CMSG_CTRL_ADD_ATTR_CERT
14 (0xE)
BLOB che contiene i byte codificati del certificato dell'attributo.
CMSG_CTRL_ADD_CERT
10 (0xA)
Struttura CRYPT_INTEGER_BLOB che contiene i byte codificati del certificato da aggiungere al messaggio.
CMSG_CTRL_ADD_CMS_SIGNER_INFO
20 (0x14)
Struttura CMSG_CMS_SIGNER_INFO che contiene informazioni sul firmatario. Questa operazione è diversa da CMSG_CTRL_ADD_SIGNER perché le informazioni sul firmatario contengono la firma.
CMSG_CTRL_ADD_CRL
12 (0xC)
BLOB che contiene i byte codificati del CRL da aggiungere al messaggio.
CMSG_CTRL_ADD_SIGNER
6 (0x6)
Struttura CMSG_SIGNER_ENCODE_INFO contenente le informazioni sul firmatario da aggiungere al messaggio.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR
8 (0x8)
Struttura CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA che contiene l'indice del firmatario e un BLOB che contiene le informazioni sull'attributo non autenticato da aggiungere al messaggio.
CMSG_CTRL_DECRYPT
2 (0x2)
Struttura CMSG_CTRL_DECRYPT_PARA utilizzata per decrittografare il messaggio per il destinatario del trasporto di chiavi specificato. Questo valore è applicabile ai destinatari RSA. Questa operazione specifica che la funzione CryptMsgControl esegue la ricerca nell'indice del destinatario per ottenere le informazioni sul destinatario del trasporto della chiave. Se la funzione ha esito negativo, GetLastError restituirà CRYPT_E_INVALID_INDEX se non viene trovato alcun destinatario di trasporto della chiave.
CMSG_CTRL_DEL_ATTR_CERT
15 (0xF)
Indice del certificato dell'attributo da rimuovere.
CMSG_CTRL_DEL_CERT
11 (0xB)
Indice del certificato da eliminare dal messaggio.
CMSG_CTRL_DEL_CRL
13 (0xD)
Indice del CRL da eliminare dal messaggio.
CMSG_CTRL_DEL_SIGNER
7 (0x7)
Indice del firmatario da eliminare.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
9 (0x9)
Struttura CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA che contiene un indice che specifica il firmatario e l'indice che specifica l'attributo non autenticato del firmatario da eliminare.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE
21 (0x15)
Struttura CERT_STRONG_SIGN_PARA utilizzata per eseguire il controllo delle firme complesse.

Per verificare la presenza di una firma complessa, specificare questo tipo di controllo prima di chiamare CryptMsgGetAndVerifySigner o prima di chiamare CryptMsgControl con i tipi di controllo seguenti impostati:

  • CMSG_CTRL_VERIFY_SIGNATURE
  • CMSG_CTRL_VERIFY_SIGNATURE_EX
Dopo la verifica della firma, questa funzione verifica la presenza di una firma complessa. Se la firma non è complessa, l'operazione avrà esito negativo e il valore GetLastError verrà impostato su NTE_BAD_ALGID.
CMSG_CTRL_KEY_AGREE_DECRYPT
17 (0x11)
Struttura CMSG_CTRL_KEY_AGREE_DECRYPT_PARA utilizzata per decrittografare il messaggio per la chiave di sessione del contratto di chiave specificata. Il contratto di chiave viene usato con Diffie-Hellman crittografia/decrittografia.
CMSG_CTRL_KEY_TRANS_DECRYPT
16 (0x10)
Struttura CMSG_CTRL_KEY_TRANS_DECRYPT_PARA utilizzata per decrittografare il messaggio per il destinatario del trasporto di chiavi specificato. Il trasporto delle chiavi viene usato con crittografia/decrittografia RSA.
CMSG_CTRL_MAIL_LIST_DECRYPT
18 (0x12)
Struttura CMSG_CTRL_MAIL_LIST_DECRYPT_PARA utilizzata per decrittografare il messaggio per il destinatario specificato usando una chiave di crittografia della chiave distribuita in precedenza.
CMSG_CTRL_VERIFY_HASH
5 (0x5)
Questo valore non viene utilizzato.
CMSG_CTRL_VERIFY_SIGNATURE
1 (0x1)
Struttura CERT_INFO che identifica il firmatario del messaggio la cui firma deve essere verificata.
CMSG_CTRL_VERIFY_SIGNATURE_EX
19 (0x13)
Struttura CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA che specifica l'indice del firmatario e la chiave pubblica per verificare la firma del messaggio. La chiave pubblica del firmatario può essere una struttura CERT_PUBLIC_KEY_INFO , un contesto del certificato o un contesto della catena di certificati.

[in] pvCtrlPara

Puntatore a una struttura determinata dal valore di dwCtrlType.

valore dwCtrlType Significato
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT o CMSG_CTRL_MAIL_LIST_DECRYPT e il messaggio in busto trasmesso viene decodificato
La decodifica verrà eseguita come se il contenuto trasmesso fosse decrittografato. Se un contenuto crittografato con flusso è stato accumulato prima di questa chiamata, alcuni o tutti i testo non crittografati risultanti dalla decrittografia del testo di crittografia vengono passati all'applicazione tramite la funzione di callback specificata nella chiamata alla funzione CryptMsgOpenToDecode .
Nota Quando si esegue lo streaming di un messaggio in busta, la funzione CryptMsgControl non viene chiamata finché il polling non viene eseguito il polling per la disponibilità del CMSG_ENVELOPE_ALGORITHM_PARAM ha esito positivo. Se il polling non riesce, viene restituito un errore. Per una descrizione del polling, vedere la funzione CryptMsgOpenToDecode .
 
CMSG_CTRL_VERIFY_HASH
L'hash calcolato dal contenuto del messaggio viene confrontato con l'hash contenuto nel messaggio.
CMSG_CTRL_ADD_SIGNER
pvCtrlPara punta a una struttura CMSG_SIGNER_ENCODE_INFO che contiene le informazioni sul segno da aggiungere al messaggio.
CMSG_CTRL_DEL_SIGNER
Dopo aver eseguito un'eliminazione, tutti gli altri indici di firma in uso per questo messaggio non sono più validi e devono essere riacquisiti chiamando la funzione CryptMsgGetParam .
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
Dopo aver eseguito un'eliminazione, tutti gli altri indici di attributi non autenticati in uso per questo signer non sono più validi e devono essere riacquisiti chiamando la funzione CryptMsgGetParam .
CMSG_CTRL_DEL_CERT
Dopo aver eseguito un'eliminazione, tutti gli altri indici di certificato in uso per questo messaggio non sono più validi e devono essere riacquisiti chiamando la funzione CryptMsgGetParam .
CMSG_CTRL_DEL_CRL
Dopo aver eseguito un'eliminazione, qualsiasi altro indice CRL in uso per questo messaggio non è più valido e dovrà essere riacquisto chiamando la funzione CryptMsgGetParam .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero e la funzione GetLastError restituisce un errore di codifica astratta notazione 1 (ASN.1). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.

Quando viene decodificato un messaggio in streaming, gli errori rilevati nella funzione di callback definita dall'applicazione specificata dal parametro pStreamInfo dell'oggetto
La funzione CryptMsgOpenToDecode potrebbe essere propagata alla funzione CryptMsgControl . In questo caso, la funzione SetLastError non viene chiamata dalla funzione CryptMsgControl dopo che la funzione di callback restituisce. In questo modo vengono mantenuti eventuali errori rilevati sotto il controllo dell'applicazione. È responsabilità della funzione di callback (o di una delle API che chiama) chiamare la funzione SetLastError se si verifica un errore durante l'elaborazione dei dati trasmessi dall'applicazione.

Gli errori propagati potrebbero essere rilevati dalle funzioni seguenti:

I codici di errore seguenti vengono restituiti più comunemente.

Codice restituito Descrizione
CRYPT_E_ALREADY_DECRYPTED
Il contenuto del messaggio è già stato decrittografato. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_DECRYPT.
CRYPT_E_AUTH_ATTR_MISSING
Il messaggio non contiene un attributo autenticato previsto. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_BAD_ENCODE
Si è verificato un errore durante la codifica o la decodifica. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_CONTROL_TYPE
Il tipo di controllo non è valido.
CRYPT_E_HASH_VALUE
Il valore hash non è corretto.
CRYPT_E_INVALID_INDEX
Il valore dell'indice non è valido.
CRYPT_E_INVALID_MSG_TYPE
Tipo di messaggio non valido.
CRYPT_E_OID_FORMAT
L'identificatore dell'oggetto non è formattato correttamente. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_ADD_SIGNER.
CRYPT_E_RECIPIENT_NOT_FOUND
Il messaggio di dati in busta non contiene il destinatario specificato. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_DECRYPT.
CRYPT_E_SIGNER_NOT_FOUND
Il firmatario specificato per il messaggio non è stato trovato. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_UNKNOWN_ALGO
L'algoritmo crittografico è sconosciuto.
CRYPT_E_UNEXPECTED_ENCODING
Il messaggio non viene codificato come previsto. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE.
E_INVALIDARG
Uno o più argomenti non sono validi. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_DECRYPT.
E_OUTOFMEMORY
Memoria insufficiente disponibile per completare l'operazione.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione wincrypt.h
Libreria Crypt32.lib
DLL Crypt32.dll

Vedi anche

Funzioni di messaggio di basso livello

Funzioni di messaggio semplificate