Funzione CryptMsgOpenToDecode (wincrypt.h)

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.

[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.

[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.

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.

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 .

Requisiti

Vedi anche

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToEncode

CryptMsgUpdate

Funzioni messaggio di basso livello

Funzioni di messaggio semplificate