Funzione CryptMsgGetParam (wincrypt.h)

Articolo
08/27/2023

La funzione CryptMsgGetParam acquisisce un parametro di messaggio dopo che un messaggio di crittografia è stato codificato o decodificato. Questa funzione viene chiamata dopo la chiamata finale a CryptMsgUpdate .

Sintassi

BOOL CryptMsgGetParam(
  [in]      HCRYPTMSG hCryptMsg,
  [in]      DWORD     dwParamType,
  [in]      DWORD     dwIndex,
  [out]     void      *pvData,
  [in, out] DWORD     *pcbData
);

Parametri

[in] hCryptMsg

Handle di un messaggio di crittografia.

[in] dwParamType

Indica i tipi di parametri di dati da recuperare. Il tipo di dati da recuperare determina il tipo di struttura da utilizzare per pvData.

Per un messaggio codificato, sono validi solo i CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM e CMSG_COMPUTED_HASH_PARAM dwParamTypes.

Valore	Significato
CMSG_ATTR_CERT_COUNT_PARAM	Tipo di dati pvData: puntatore a un DWORD Restituisce il conteggio dei certificati degli attributi in un messaggio SIGNED o ENVELOPED.
CMSG_ATTR_CERT_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Recupera un certificato di attributo. Per ottenere tutti i certificati degli attributi, chiamare CryptMsgGetParam varying dwIndex impostato su 0 il numero di attributi meno uno.
CMSG_BARE_CONTENT_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Recupera il contenuto codificato di un messaggio di crittografia codificato, senza il livello esterno della struttura CONTENT_INFO. Vale a dire, viene restituita solo la codifica del campo ContentInfo.content definito PKCS #7.
CMSG_CERT_COUNT_PARAM	Tipo di dati pvData: puntatore a DWORD Restituisce il numero di certificati in un messaggio SIGNED o ENVELOPED ricevuto.
CMSG_CERT_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce il certificato di un firmatario. Per ottenere tutti i certificati del firmatario, chiamare CryptMsgGetParam, variabile dwIndex da 0 al numero di certificati disponibili meno uno.
CMSG_COMPUTED_HASH_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce l'hash calcolato dei dati nel messaggio. Questo tipo è applicabile sia alla codifica che alla decodifica.
CMSG_CONTENT_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce l'intero messaggio PKCS #7 da un messaggio aperto per la codifica. Recupera il contenuto interno di un messaggio aperto per decodificare. Se il messaggio è in busta, il tipo interno è dati e CryptMsgControl è stato chiamato per decrittografare il messaggio, viene restituito il contenuto decrittografato. Se il tipo interno non è dati, viene restituito il BLOB codificato che richiede ulteriore decodifica. Se il messaggio non è in busta e il contenuto interno è DATA, i dati restituiti sono gli ottetti del contenuto interno. Questo tipo è applicabile sia alla codifica che alla decodifica. Per la decodifica, se il tipo è CMSG_DATA, vengono restituiti gli ottetti del contenuto; in caso contrario, viene restituito il contenuto interno codificato.
CMSG_CRL_COUNT_PARAM	Tipo di dati pvData: puntatore a DWORD Restituisce il numero di CRL in un messaggio ricevuto, SIGNED o ENVELOPED.
CMSG_CRL_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce un CRL. Per ottenere tutti i CRL, chiamare CryptMsgGetParam, variando dwIndex da 0 al numero di CRL disponibili meno uno.
CMSG_ENCODED_MESSAGE	Tipo di dati pvData: puntatore a una matrice BYTE Modifica il contenuto di un messaggio già codificato. Il messaggio deve essere prima decodificato con una chiamata a CryptMsgOpenToDecode. La modifica al messaggio viene quindi eseguita tramite una chiamata a CryptMsgControl, CryptMsgCountersign o CryptMsgCountersignEncoded. Il messaggio viene quindi codificato nuovamente con una chiamata a CryptMsgGetParam, specificando CMSG_ENCODED_MESSAGE per ottenere una nuova codifica che rifletta le modifiche apportate. Può essere usato, ad esempio, per aggiungere un attributo timestamp a un messaggio.
CMSG_ENCODED_SIGNER	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce le informazioni del firmatario CMSG_SIGNER_INFO codificato per un firmatario del messaggio.
CMSG_ENCRYPTED_DIGEST	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce l'hash crittografato di una firma. Usato in genere per l'esecuzione del timestamp.
CMSG_ENCRYPT_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per una struttura CRYPT_ALGORITHM_IDENTIFIER. Restituisce l'algoritmo di crittografia utilizzato per crittografare il messaggio.
CMSG_ENVELOPE_ALGORITHM_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per una struttura CRYPT_ALGORITHM_IDENTIFIER. Restituisce l'algoritmo di crittografia utilizzato per crittografare un messaggio ENVELOPED.
CMSG_HASH_ALGORITHM_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per una struttura CRYPT_ALGORITHM_IDENTIFIER. Restituisce l'algoritmo hash utilizzato per eseguire l'hashing del messaggio al momento della creazione.
CMSG_HASH_DATA_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE Restituisce il valore hash archiviato nel messaggio al momento della creazione.
CMSG_INNER_CONTENT_TYPE_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE per ricevere una stringa OID (Null-TerminateObject Identifier). Restituisce il tipo di contenuto interno di un messaggio ricevuto. Questo tipo non è applicabile ai messaggi di tipo DATA.
CMSG_RECIPIENT_COUNT_PARAM	Tipo di dati pvData: puntatore a un DWORD Restituisce il numero di destinatari del trasporto delle chiavi di un messaggio ricevuto ENVELOPED.
CMSG_CMS_RECIPIENT_COUNT_PARAM	Tipo di dati pvData: puntatore a DWORD Restituisce il conteggio totale di tutti i destinatari dei messaggi, inclusi il contratto di chiave e i destinatari dell'elenco di posta elettronica.
CMSG_RECIPIENT_INDEX_PARAM	Tipo di dati pvData: puntatore a un DWORD Restituisce l'indice del destinatario del trasporto delle chiavi utilizzato per decrittografare un messaggio ENVELOPED. Questo valore è disponibile solo dopo la decrittografia di un messaggio.
CMSG_CMS_RECIPIENT_INDEX_PARAM	Tipo di dati pvData: puntatore a un DWORD Restituisce l'indice del trasporto chiave, del contratto di chiave o del destinatario dell'elenco di posta elettronica utilizzato per decrittografare un messaggio ENVELOPED.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	Tipo di dati pvData: puntatore a un DWORD Restituisce l'indice della chiave crittografata di un destinatario del contratto di chiave utilizzato per decrittografare un messaggio ENVELOPED.
CMSG_RECIPIENT_INFO_PARAM	Tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CERT_INFO. Restituisce informazioni sul certificato sul destinatario del messaggio di trasporto delle chiavi. Per ottenere informazioni sul certificato su tutti i destinatari del messaggio di trasporto delle chiavi, chiamare in modo ripetitivo CryptMsgGetParam, variando dwIndex da 0 al numero di destinatari meno uno. Sono disponibili e validi solo i membri Autorità di certificazione, SerialNumber e PublicKeyAlgorithm della struttura CERT_INFO restituiti.
CMSG_CMS_RECIPIENT_INFO_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CMSG_CMS_RECIPIENT_INFO. Restituisce informazioni su un trasporto chiave, un contratto chiave o un destinatario dell'elenco di posta elettronica. Non è limitato ai destinatari dei messaggi di trasporto chiave. Per ottenere informazioni su tutti i destinatari di un messaggio, chiamare in modo ripetitivo CryptMsgGetParam, variando dwIndex da 0 al numero di destinatari meno uno.
CMSG_SIGNER_AUTH_ATTR_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CRYPT_ATTRIBUTES. Restituisce gli attributi autenticati di un firmatario del messaggio. Per recuperare gli attributi autenticati per un firmatario specificato, chiamare CryptMsgGetParam con dwIndex uguale all'indice del firmatario.
CMSG_SIGNER_CERT_INFO_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere la struttura CERT_INFO. Restituisce informazioni su un firmatario del messaggio necessario per identificare il certificato del firmatario. Un certificato emittente e SerialNumber può essere usato per identificare in modo univoco un certificato per il recupero. Per recuperare informazioni per tutti i firmatari, chiamare in modo ripetitivo CryptMsgGetParamvariando dwIndex da 0 al numero di firmatari meno uno. Solo i campi Emittente e SerialNumber nella struttura CERT_INFO restituiti contengono dati disponibili e validi.
CMSG_SIGNER_CERT_ID_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CERT_ID. Restituisce informazioni su un firmatario del messaggio necessario per identificare la chiave pubblica del firmatario. Questo potrebbe essere l'autorità di certificazione e serialNumber di un certificato, un KeyID o un HashId. Per recuperare informazioni per tutti i firmatari, chiamare CryptMsgGetParam variabile dwIndex da 0 al numero di firmatari meno uno.
CMSG_SIGNER_COUNT_PARAM	tipo di dati pvData: puntatore a un DWORD Restituisce il numero di firmatari di un messaggio FIRMATO ricevuto.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere la struttura CRYPT_ALGORITHM_IDENTIFIER. Restituisce l'algoritmo hash usato da un firmatario del messaggio. Per ottenere l'algoritmo hash per un firmatario specificato, chiamare CryptMsgGetParam con dwIndex uguale all'indice del firmatario.
CMSG_SIGNER_INFO_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CMSG_SIGNER_INFO. Restituisce informazioni su un firmatario del messaggio. Ciò include l'autorità emittente e il numero di serie del certificato del firmatario e autenticati e gli attributi non autenticati del certificato del firmatario. Per recuperare le informazioni sull'accesso su tutti i firmatari di un messaggio, chiamare CryptMsgGetParam variabile dwIndex da 0 al numero di firmatari meno uno.
CMSG_CMS_SIGNER_INFO_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CMSG_CMS_SIGNER_INFO. Restituisce informazioni su un firmatario del messaggio. Include un signerId e attributi autenticati e non autenticati. Per recuperare le informazioni sull'accesso su tutti i firmatari di un messaggio, chiamare CryptMsgGetParam variabile dwIndex da 0 al numero di firmatari meno uno.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CRYPT_ATTRIBUTES. Restituisce gli attributi non autenticati del firmatario del messaggio. Per recuperare gli attributi non autenticati per un firmatario specificato, chiamare CryptMsgGetParam con dwIndex uguale all'indice del firmatario.
CMSG_TYPE_PARAM	tipo di dati pvData: puntatore a un DWORD Restituisce il tipo di messaggio di un messaggio decodificato di tipo sconosciuto. Il tipo di messaggio recuperato può essere confrontato con i tipi supportati per determinare se l'elaborazione può continuare. Per i tipi di messaggi supportati, vedere il parametro dwMessageType di CryptMsgOpenToDecode.
CMSG_UNPROTECTED_ATTR_PARAM	tipo di dati pvData: puntatore a una matrice BYTE per ricevere una struttura CMSG_ATTR. Restituisce gli attributi non protetti in un messaggio busto.
CMSG_VERSION_PARAM	tipo di dati pvData: puntatore a un DWORD Restituisce la versione del messaggio decodificato. Per altre informazioni, vedere la tabella nella sezione Osservazioni.

[in] dwIndex

Indice per il parametro recuperato, se applicabile. Quando un parametro non viene recuperato, questo parametro viene ignorato e viene impostato su zero.

[out] pvData

Puntatore a un buffer che riceve i dati recuperati. La forma di questi dati varia a seconda del valore del parametro dwParamType .

Questo parametro può essere NULL per impostare le dimensioni di queste informazioni per scopi di allocazione della memoria. Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.

Quando si elaborano i dati restituiti in questo buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori rispetto alle dimensioni del buffer specificato nell'input. In base all'input, le dimensioni del buffer vengono in genere specificate abbastanza grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata per riflettere le dimensioni effettive dei dati copiati nel buffer.

[in, out] pcbData

Puntatore a una variabile che specifica le dimensioni, in byte, del buffer a cui punta il parametro pvData . Quando la funzione restituisce, la variabile puntata dal parametro pcbData contiene il numero di byte archiviati nel buffer.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni sull'errore estese, chiamare GetLastError.

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

Codice restituito	Descrizione
CRYPT_E_ATTRIBUTES_MISSING	Il messaggio non contiene gli attributi richiesti.
CRYPT_E_INVALID_INDEX	Il valore dell'indice non è valido.
CRYPT_E_INVALID_MSG_TYPE	Tipo di messaggio non valido.
CRYPT_E_NOT_DECRYPTED	Il contenuto del messaggio non è ancora stato decrittografato.
CRYPT_E_OID_FORMAT	L'identificatore dell'oggetto non è formattato correttamente.
CRYPT_E_UNEXPECTED_ENCODING	Il messaggio non viene codificato come previsto.
E_INVALIDARG	Uno o più argomenti non sono validi.
ERROR_MORE_DATA	Il buffer specificato non è abbastanza grande per contenere i dati restituiti.

Per CMSG_COMPUTED_HASH_PARAM dwParamType , è possibile propagare un errore da CryptGetHashParam.

Se la funzione ha esito negativo, GetLastError potrebbe restituire un errore di codifica astratta Notation One (ASN.1). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.

Commenti

I numeri di versione seguenti vengono restituiti dalle chiamate a CryptMsgGetParam con dwParamType impostata su CMSG_VERSION_PARAM sono definiti:

CMSG_SIGNED_DATA_V1
CMSG_SIGNED_DATA_V3
CMSG_SIGNED_DATA_PKCS_1_5_VERSION
CMSG_SIGNED_DATA_CMS_VERSION
CMSG_SIGNER_INFO_V1
CMSG_SIGNER_INFO_V3
CMSG_SIGNER_INFO_PKCS_1_5_VERSION
CMSG_SIGNER_INFO_CMS_VERSION
CMSG_HASHED_DATA_V0
CMSG_HASHED_DATA_V2
CMSG_HASHED_DATA_PKCS_1_5_VERSION
CMSG_HASHED_DATA_CMS_VERSION
CMSG_ENVELOPED_DATA_V0
CMSG_ENVELOPED_DATA_V2
CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
CMSG_ENVELOPED_DATA_CMS_VERSION

Esempio

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

Requisiti


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