Funzione CryptMsgOpenToDecode (wincrypt.h)

Articolo
08/27/2023

La funzione CryptMsgOpenToDecode apre un messaggio di crittografia per la decodifica e restituisce un handle del messaggio aperto. Il messaggio rimane aperto fino a quando non viene chiamata la funzione CryptMsgClose .

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 informazioni dettagliate, vedere la sezione Osservazioni di CryptMsgOpenToEncode.

Sintassi

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Parametri

[in] dwMsgEncodingType

Specifica il tipo di codifica utilizzato. È sempre accettabile specificare sia il certificato che i tipi di codifica dei messaggi combinandoli con un'operazione OR bit per bit, come illustrato nell'esempio seguente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

I tipi di codifica attualmente definiti sono:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Questo parametro può essere uno dei flag seguenti.

Valore	Significato
CMSG_DETACHED_FLAG	Indica che il messaggio da decodificare è scollegato. Se questo flag non è impostato, il messaggio non viene scollegato.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Se impostato, l'hCryptProv passato a questa funzione viene rilasciato nella versione finale di CryptMsgUpdate. L'handle non viene rilasciato se la funzione ha esito negativo.

[in] dwMsgType

Specifica il tipo di messaggio da decodificare. Nella maggior parte dei casi, il tipo di messaggio viene determinato dall'intestazione del messaggio e zero viene passato per questo parametro. In alcuni casi, in particolare con Internet Explorer 3.0, i messaggi non hanno intestazioni e il tipo di messaggio da decodificare deve essere fornito in questa chiamata di funzione. Se l'intestazione è mancante e zero viene passato per questo parametro, la funzione ha esito negativo.

Questo parametro può essere uno dei tipi di messaggio predefiniti seguenti.

Valore	Significato
CMSG_DATA	Il messaggio è costituito da dati codificati.
CMSG_ENVELOPED	Il messaggio è un messaggio in busto.
CMSG_HASHED	Il messaggio è un messaggio con hash.
CMSG_SIGNED	Il messaggio è un messaggio firmato.
CMSG_SIGNED_AND_ENVELOPED	Il messaggio è un messaggio firmato e in busta.

[in] hCryptProv

Questo parametro non viene usato e deve essere impostato su NULL.

Windows Server 2003 e Windows XP: Specifica un handle per il provider di crittografia da usare per l'hashing del messaggio. Per i messaggi firmati, hCryptProv viene usato per la verifica della firma. Il tipo di dati di questo parametro è HCRYPTPROV.

A meno che non vi sia un motivo sicuro per passare un provider di crittografia specifico in hCryptProv, impostare questo parametro su NULL. Il passaggio di NULL causa l'acquisizione del provider RSA o DSS predefinito prima di eseguire operazioni hash, verifica della firma o crittografia del destinatario.

[in] pRecipientInfo

Questo parametro è riservato per uso futuro e deve essere NULL.

[in, optional] pStreamInfo

Quando lo streaming non viene usato, questo parametro deve essere impostato su NULL.

Nota Lo streaming non viene usato con i messaggi CMSG_HASHED. Quando si gestiscono dati con hash, questo parametro deve essere impostato su NULL.

Quando si usa lo streaming, il parametro pStreamInfo è un puntatore a una struttura CMSG_STREAM_INFO che contiene un puntatore a un callback da chiamare quando viene eseguito CryptMsgUpdate o quando viene eseguito CryptMsgControl durante la decodifica di un messaggio in busto trasmesso.

Per un messaggio firmato, al callback viene passato un blocco dei byte decodificati dal contenuto interno del messaggio.

Per un messaggio in busta, dopo ogni chiamata a CryptMsgUpdate, è necessario verificare se la proprietà CMSG_ENVELOPE_ALGORITHM_PARAM è disponibile chiamando la funzione CryptMsgGetParam . CryptMsgGetParam avrà esito negativo e GetLastError restituirà CRYPT_E_STREAM_MSG_NOT_READY finché CryptMsgUpdate non ha elaborato abbastanza del messaggio per rendere disponibile la proprietà CMSG_ENVELOPE_ALGORITHM_PARAM. Quando la proprietà CMSG_ENVELOPE_ALGORITHM_PARAM è disponibile, è possibile scorrere i destinatari recuperando una struttura CERT_INFO per ogni destinatario usando la funzione CryptMsgGetParam per recuperare la proprietà CMSG_RECIPIENT_INFO_PARAM. Per impedire un attacco Denial of Service da un messaggio in busto con un blocco di intestazione artificialmente grande, è necessario tenere traccia della quantità di memoria passata alla funzione CryptMsgUpdate durante questo processo. Se la quantità di dati supera un limite definito dall'applicazione prima che la proprietà CMSG_ENVELOPE_ALGORITHM_PARAM sia disponibile, è necessario interrompere l'elaborazione del messaggio e chiamare la funzione CryptMsgClose per fare in modo che il sistema operativo rilasci qualsiasi memoria allocata per il messaggio. Un limite suggerito è la dimensione massima consentita di un messaggio. Ad esempio, se la dimensione massima del messaggio è 10 MB, il limite per questo test deve essere 10 MB.

La struttura CERT_INFO viene usata per trovare un certificato corrispondente in un archivio certificati aperto in precedenza usando la funzione CertGetSubjectCertificateFromStore . Quando viene trovato il certificato corretto, viene chiamata la funzione CertGetCertificateContextProperty con un parametro CERT_KEY_PROV_INFO_PROP_ID per recuperare una struttura CRYPT_KEY_PROV_INFO . La struttura contiene le informazioni necessarie per acquisire la chiave privata del destinatario chiamando CryptAcquireContext, usando i membri pwszContainerName, pwszProvName, dwProvType e dwFlags della struttura CRYPT_KEY_PROV_INFO . HCryptProv acquisito e il membro dwKeySpec della struttura CRYPT_KEY_PROV_INFO vengono passati alla struttura CryptMsgControl come membro della struttura CMSG_CTRL_DECRYPT_PARA per consentire l'inizio della decrittografia del contenuto interno. Il codice di streaming eseguirà quindi la decrittografia perché i dati sono input. I blocchi risultanti di testo non crittografato vengono passati alla funzione di callback specificata dal membro pfnStreamOutput della struttura CMSG_STREAM_INFO per gestire l'output del messaggio decrittografato.

Nota Decodifica in streaming di un messaggio in busta accoda il testo crittografato in memoria fino a quando non viene chiamato CryptMsgControl per avviare la decrittografia. L'applicazione deve avviare la decrittografia in modo tempestivo in modo che i dati possano essere salvati su disco o indirizzati altrove prima che il testo crittografato accumulato diventi troppo grande e il sistema esaurisce la memoria.

Nel caso di un messaggio firmato racchiuso in un messaggio in busta, l'output di testo non crittografato dalla decodifica in streaming del messaggio in busta può essere inserito in un altro codice di streaming per elaborare il messaggio firmato.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce l'handle del messaggio aperto.

Se la funzione ha esito negativo, restituisce NULL. Per informazioni sugli errori estesi, chiamare GetLastError.

Nella tabella seguente sono elencati i codici di errore restituiti più di frequente dalla funzione GetLastError .

Valore	Descrizione
E_INVALIDARG	Uno o più argomenti non sono validi.
E_OUTOFMEMORY	Si è verificato un errore di allocazione della memoria.

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 messaggio di basso livello

Funzioni di messaggio semplificate

Condividi tramite