Condividi tramite


Funzione CryptMsgOpenToEncode (wincrypt.h)

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

Vedi anche

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToDecode

CryptMsgUpdate

Funzioni di messaggio di basso livello

Funzioni di messaggio semplificate