Metodo IX509CertificateRequestPkcs10::GetCspStatuses (certenroll.h)

Articolo
08/22/2023

Il metodo GetCspStatuses recupera un insieme ICspStatuses che contiene tutte le coppie provider/algoritmo coerenti con l'uso previsto della chiave privata, come specificato dal chiamante.

Sintassi

HRESULT GetCspStatuses(
  [in]  X509KeySpec  KeySpec,
  [out] ICspStatuses **ppCspStatuses
);

Parametri

[in] KeySpec

Valore di enumerazione X509KeySpec che specifica l'uso previsto della chiave. Questo può essere uno dei valori seguenti.

Valore	Significato
XCN_AT_NONE	Vengono selezionati solo l'API di crittografia: i provider CNG (Next Generation).
XCN_AT_KEYEXCHANGE	Vengono selezionati solo i provider di servizi crittografici CryptoAPI con algoritmi di crittografia (incluso lo scambio di chiavi).
XCN_AT_SIGNATURE	Vengono selezionati solo i provider di servizi di crittografia con algoritmi di firma.

[out] ppCspStatuses

Indirizzo di una variabile che riceve un puntatore a un'interfaccia ICspStatuses che rappresenta la raccolta.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce S_OK.

Se la funzione ha esito negativo, restituisce un valore HRESULT che indica l'errore. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.

Codice restituito	Descrizione
CERTSRV_E_PROPERTY_EMPTY	Impossibile trovare la chiave privata.
OLE_E_BLANK	L'oggetto non viene inizializzato.

Commenti

Questo metodo recupera una raccolta di oggetti ICspStatus . Ogni oggetto rappresenta una singola coppia provider/algoritmo. Se si specifica un modello quando si inizializza l'oggetto richiesta IX509CertificateRequestPkcs10, gli attributi del modello, ad esempio pKIDefaultCSPs e pKIDefaultKeySpec influiscono inizialmente sulle coppie abilitate inizialmente. È possibile chiamare le proprietà seguenti in ogni oggetto ICspStatus per recuperare informazioni su una coppia:

La proprietà CspInformation recupera le informazioni sul provider.
La proprietà CspAlgorithm recupera le informazioni sull'algoritmo.
La proprietà EnrollmentStatus recupera un oggetto IX509EnrollmentStatus . Chiamare la proprietà Selected nell'oggetto stato per determinare se la coppia provider/algoritmo è abilitata per questa richiesta.
La proprietà Ordinal recupera la posizione nell'insieme di coppie provider/algoritmo.

L'insieme recuperato da questo metodo viene salvato internamente nell'oggetto request. È possibile creare e salvare fino a tre raccolte, una per ogni valore KeySpec . Questa operazione consente di mantenere lo stato di selezione delle coppie provider/algoritmo in modo che le pagine delle proprietà pertinenti possano essere visualizzate in modo accurato e rapido più volte e in modo che il metodo Encode possa identificare i provider e gli algoritmi selezionati se deve essere creata una chiave privata. Se lo stato di selezione di una coppia provider/algoritmo viene modificato, le modifiche vengono salvate nella raccolta appropriata. Le modifiche apportate ai membri di una raccolta non influiscono sui membri di qualsiasi altra raccolta. Le raccolte esistono finché l'oggetto PKCS #10 continua a esistere.

Si supponga, ad esempio, che questo metodo venga chiamato con il parametro KeySpec impostato su XCN_AT_SIGNATURE e che un modello venga usato per inizializzare la richiesta. Le istruzioni seguenti saranno vere:

Viene creata e salvata una raccolta di oggetti ICspStatus nell'oggetto IX509CertificateRequestPkcs10 . La raccolta contiene tutte le coppie provider/algoritmo valide installate nel computer.
Poiché il parametro KeySpec non è impostato su XCN_AT_NONE, la proprietà Selected è impostata su SelectedNo per ogni API di crittografia: provider/algoritmo CNG (Next Generation) nella raccolta.
Poiché il parametro KeySpec non è impostato su XCN_AT_KEYEXCHANGE, la proprietà Selected è impostata su SelectedNo per ogni coppia di CSP/algoritmo CryptoAPI nella raccolta in cui l'algoritmo può essere usato per crittografare i dati o archiviare una chiave.
Per ogni provider a cui fa riferimento il modello o la chiave privata ma non è supportata nel computer, viene creato un oggetto ICspStatus segnaposto e aggiunto all'insieme e la proprietà Selected è impostata su SelectedNo .
La proprietà Selected è impostata su SelectedYes per ogni coppia CSP/algoritmo CryptoAPI in cui l'algoritmo può essere usato solo per firmare i dati.
La proprietà Ordinal è impostata per riflettere l'ordine CSP, se presente, identificato dall'attributo modello pKIDefaultCSPs . I provider di servizi di configurazione elencati prima dall'attributo vengono ordinati prima nella raccolta. Questa proprietà viene usata durante la registrazione se deve essere creata una chiave privata. La prima coppia CSP/algoritmo selezionata viene usata per creare la chiave, ma se l'operazione ha esito negativo, viene tentata la coppia selezionata successiva.
La chiamata di nuovo a questo metodo con lo stesso parametro KeySpec recupera un puntatore alla raccolta esistente creata in precedenza per tale valore di parametro.
La chiamata di nuovo a questo metodo con un parametro KeySpec diverso non influisce sulla raccolta creata per il valore keySpec XCN_AT_SIGNATURE. Inoltre, la modifica della proprietà Selected in qualsiasi membro della nuova raccolta non influisce su alcun membro della raccolta precedente.

Il metodo GetCspStatuses differisce dalla proprietà CspStatuses usando il parametro KeySpec . Il metodo consente agli utenti di specificare questo valore, ma la proprietà usa il valore impostato sulla chiave privata associata all'oggetto request.

È necessario inizializzare l'oggetto IX509CertificateRequestPkcs10 prima di chiamare questo metodo. Per altre informazioni, vedere uno dei metodi seguenti:

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	certenroll.h
DLL	CertEnroll.dll

Vedi anche

IX509CertificateRequestPkcs10