Funzione CryptMsgOpenToEncode (wincrypt.h)

Articolo
08/27/2023

La funzione CryptMsgOpenToEncode apre un messaggio di crittografia per la codifica e restituisce un handle del messaggio aperto. Il messaggio rimane aperto finché non viene chiamato CryptMsgClose .

Sintassi

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

Parametri

[in] dwMsgEncodingType

Specifica il tipo di codifica usato. È sempre accettabile specificare sia i tipi di codifica del certificato che dei messaggi combinandoli con un'operazione bit per bit or , 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

I dwFlag attualmente definiti sono visualizzati nella tabella seguente.

Valore	Significato
CMSG_BARE_CONTENT_FLAG	L'output in flusso non avrà un wrapper ContentInfo esterno (come definito da PKCS #7). In questo modo è adatto per essere trasmesso in un messaggio racchiuso.
CMSG_DETACHED_FLAG	I dati scollegati vengono forniti per le chiamate successive a CryptMsgUpdate.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Gli attributi autenticati devono essere inclusi in SignerInfo (come definito da PKCS #7) nei casi in cui non sarebbero altrimenti necessari.
CMSG_CONTENTS_OCTETS_FLAG	Usato per calcolare le dimensioni di un messaggio codificato usando Distinguished Encoding Rules (DER) e annidato all'interno di un messaggio busto. Ciò è particolarmente utile quando si esegue lo streaming.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Se impostato, il contenuto interno del tipo di dati non viene incapsulato all'interno di una STRINGA OCTET. Applicabile sia ai messaggi firmati che in busta.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Se impostato, hCryptProv passato a questa funzione viene rilasciato nel CryptMsgUpdate finale. L'handle non viene rilasciato se la funzione ha esito negativo. Nota I destinatari della busta hCryptProvnon vengono rilasciati.

[in] dwMsgType

Indica il tipo di messaggio. Questo deve essere uno dei valori seguenti.

Valore	Significato
CMSG_DATA	Questo valore non viene utilizzato.
CMSG_SIGNED	Il parametro pvMsgEncodeInfo è l'indirizzo di una struttura CMSG_SIGNED_ENCODE_INFO contenente le informazioni di codifica.
CMSG_ENVELOPED	Il parametro pvMsgEncodeInfo è l'indirizzo di una struttura CMSG_ENVELOPED_ENCODE_INFO contenente le informazioni di codifica.
CMSG_SIGNED_AND_ENVELOPED	Questo valore non è attualmente implementato.
CMSG_HASHED	Il parametro pvMsgEncodeInfo è l'indirizzo di una struttura CMSG_HASHED_ENCODE_INFO contenente le informazioni di codifica.

[in] pvMsgEncodeInfo

Indirizzo di una struttura che contiene le informazioni di codifica. Il tipo di dati dipende dal valore del parametro dwMsgType . Per informazioni dettagliate, vedere dwMsgType.

[in, optional] pszInnerContentObjID

Se viene chiamato CryptMsgCalculateEncodedLength e i dati per CryptMsgUpdate sono già stati codificati, l'identificatore dell'oggetto appropriato (OID) viene passato in pszInnerContentObjID. Se pszInnerContentObjID è NULL, si presuppone che il tipo di contenuto interno non sia stato codificato in precedenza ed è quindi codificato come stringa ottet e dato il tipo CMSG_DATA.

Nota Quando viene usato lo streaming, pszInnerContentObjID deve essere NULL o szOID_RSA_data.

Gli OID dell'algoritmo seguenti vengono comunemente usati. Un utente può definire un nuovo utilizzo del contenuto interno assicurandosi che il mittente e il destinatario del messaggio accettino la semantica associata all'OID.

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

Quando viene usato lo streaming, questo parametro è l'indirizzo di una struttura CMSG_STREAM_INFO . La funzione di callback specificata dal membro pfnStreamOutput della struttura CMSG_STREAM_INFO viene chiamata quando viene eseguito CryptMsgUpdate . Il callback viene passato ai byte codificati risultanti dalla codifica. Per altre informazioni su come usare il callback, vedere CMSG_STREAM_INFO.

Nota Quando viene usato lo streaming, l'applicazione non deve rilasciare alcun handle di dati passato nel parametro pvMsgEncodeInfo , ad esempio l'handle del provider nel membro hCryptProv della struttura CMSG_SIGNER_ENCODE_INFO , fino a quando l'handle del messaggio restituito da questa funzione viene chiuso usando la funzione CryptMsgClose .

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

Lo streaming non viene usato con il tipo di messaggio CMSG_HASHED . Quando si tratta di dati hash, questo parametro deve essere impostato su NULL.

Si consideri il caso di un messaggio firmato racchiuso in un messaggio busto. Output codificato dalla codifica in streaming dei feed di messaggi firmati in un'altra codifica di streaming del messaggio in busta. Il callback per la codifica di streaming chiama CryptMsgUpdate per codificare il messaggio busto. Il callback per il messaggio busto riceve i byte codificati del messaggio firmato annidato.

Valore restituito

Se la funzione ha esito positivo, restituisce un handle al messaggio aperto. Questo handle deve essere chiuso quando non è più necessario passandolo alla funzione CryptMsgClose .

Se questa funzione ha esito negativo, viene restituito NULL .

Per recuperare informazioni sull'errore estese, usare la funzione GetLastError .

La tabella seguente elenca i codici di errore più comunemente restituiti dalla funzione GetLastError .

Codice restituito	Descrizione
CRYPT_E_INVALID_MSG_TYPE	Tipo di messaggio non valido.
CRYPT_E_OID_FORMAT	L'OID non è formattato correttamente.
CRYPT_E_UNKNOWN_ALGO	L'algoritmo crittografico è sconosciuto.
E_INVALIDARG	Uno o più argomenti non sono validi.
E_OUTOFMEMORY	Memoria insufficiente.

Inoltre, se dwMsgType è CMSG_SIGNED, gli errori possono essere propagati da CryptCreateHash.

Se dwMsgType è CMSG_ENVELOPED, gli errori possono essere propagati da CryptGenKey, CryptImportKey e CryptExportKey.

Se dwMsgType è CMSG_HASHED, gli errori possono essere propagati da CryptCreateHash.

Commenti

Per le funzioni che eseguono la crittografia, le chiavi simmetriche crittografate vengono invertite dal formato little-endian al formato big-endian dopo che CryptExportKey viene chiamato internamente. Per le funzioni che eseguono la decrittografia, le chiavi simmetriche crittografate vengono invertite dal formato big-endian al formato little-endian prima della chiamata di CryptImportKey .

CRYPT_NO_SALT viene specificato quando vengono generate chiavi simmetriche e importate con CryptGenKey e CryptImportKey.

I messaggi crittografati con l'algoritmo di crittografia RC2 usano KP_EFFECTIVE_KEYLEN con CryptGetKeyParam per determinare la lunghezza effettiva della chiave RC2 che importa o esporta le chiavi.

Per i messaggi crittografati con l'algoritmo di crittografia RC2, le operazioni di codifica e decodifica sono state aggiornate per gestire i parametri ASN RC2 per il membro ContentEncryptionAlgorithm della struttura CMSG_ENVELOPED_ENCODE_INFO .

Per i messaggi crittografati con gli algoritmi di crittografia RC4, DES e 3DES, codificare e decodificare le operazioni ora gestiscono il parametro stringa ottetto ASN IV per il membro ContentEncryptionAlgorithm della struttura CMSG_ENVELOPED_ENCODE_INFO .

Esempio

Per esempi che usano questa funzione, vedere Esempio di programma C: firma, codifica, decodifica e verifica di un messaggio, codice alternativo per la codifica di un messaggio busto, esempio di programma C: codifica di un messaggio busto, firmato e programma C di esempio: codifica e decodifica di un messaggio hash.

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