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 |
|---|---|
|
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 |
|---|---|
|
BLOB che contiene i byte codificati del certificato dell'attributo. |
|
Struttura CRYPT_INTEGER_BLOB che contiene i byte codificati del certificato da aggiungere al messaggio. |
|
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. |
|
BLOB che contiene i byte codificati del CRL da aggiungere al messaggio. |
|
Struttura CMSG_SIGNER_ENCODE_INFO contenente le informazioni sul firmatario da aggiungere al messaggio. |
|
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. |
|
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. |
|
Indice del certificato dell'attributo da rimuovere. |
|
Indice del certificato da eliminare dal messaggio. |
|
Indice del CRL da eliminare dal messaggio. |
|
Indice del firmatario da eliminare. |
|
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. |
|
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:
|
|
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. |
|
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. |
|
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. |
|
Questo valore non viene utilizzato. |
|
Struttura CERT_INFO che identifica il firmatario del messaggio la cui firma deve essere verificata. |
|
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 |
|---|---|
|
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 .
|
|
L'hash calcolato dal contenuto del messaggio viene confrontato con l'hash contenuto nel messaggio. |
|
pvCtrlPara punta a una struttura CMSG_SIGNER_ENCODE_INFO che contiene le informazioni sul segno da aggiungere al messaggio. |
|
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 . |
|
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 . |
|
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 . |
|
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:
- CryptCreateHash
- CryptDecrypt
- CryptGetHashParam
- CryptGetUserKey
- CryptHashData
- CryptImportKey
- CryptSignHash
- CryptVerifySignature
I codici di errore seguenti vengono restituiti più comunemente.
| Codice restituito | Descrizione |
|---|---|
|
Il contenuto del messaggio è già stato decrittografato. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_DECRYPT. |
|
Il messaggio non contiene un attributo autenticato previsto. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE. |
|
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. |
|
Il tipo di controllo non è valido. |
|
Il valore hash non è corretto. |
|
Il valore dell'indice non è valido. |
|
Tipo di messaggio non valido. |
|
L'identificatore dell'oggetto non è formattato correttamente. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_ADD_SIGNER. |
|
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. |
|
Il firmatario specificato per il messaggio non è stato trovato. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE. |
|
L'algoritmo crittografico è sconosciuto. |
|
Il messaggio non viene codificato come previsto. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_VERIFY_SIGNATURE. |
|
Uno o più argomenti non sono validi. Questo errore può essere restituito se il parametro dwCtrlType è impostato su CMSG_CTRL_DECRYPT. |
|
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 |