Metodo IX509CertificateRequestPkcs7::InitializeFromCertificate (certenroll.h)

  • Articolo

Il metodo InitializeFromCertificate inizializza la richiesta di certificato usando un certificato esistente. Il certificato è contenuto in una matrice di byte codificata usando Distinguished Encoding Rules (DER) come definito dallo standard ASN.1 (Abstract Syntax Notation One). La matrice di byte con codifica DER è rappresentata da una stringa che è una sequenza binaria pura o è codificata Unicode.

Sintassi

HRESULT InitializeFromCertificate(
  [in] X509CertificateEnrollmentContext Context,
  [in] VARIANT_BOOL                     RenewalRequest,
  [in] BSTR                             strCertificate,
  [in] EncodingType                     Encoding,
  [in] X509RequestInheritOptions        InheritOptions
);

Parametri

[in] Context

Valore di enumerazione X509CertificateEnrollmentContext che specifica se il certificato richiesto è destinato a un utente finale, un computer o un amministratore che agisce per conto del computer.

[in] RenewalRequest

VARIANT_BOOL che indica se l'entità finale richiede che il certificato identificato dal parametro strCertificate venga rinnovato.

[in] strCertificate

Variabile BSTR contenente il certificato con codifica DER.

A partire da Windows 7 e Windows Server 2008 R2, è possibile specificare una stampa personale del certificato o un numero di serie anziché un certificato codificato. In questo modo, la funzione cerca gli archivi locali appropriati per il certificato corrispondente. Tenere presente quanto segue:

  • BSTR deve essere un numero pari di cifre esadecimali.
  • Lo spazio vuoto tra coppie esadecimali viene ignorato.
  • Il parametro Codifica deve essere impostato su XCN_CRYPT_STRING_HEXRAW.
  • Il parametro Context determina se gli archivi locali o computer o entrambi vengono cercati.
  • Se è necessaria una chiave privata, vengono cercati solo gli archivi personali e delle richieste.
  • Se non è necessaria una chiave privata, vengono inoltre cercati gli archivi ca radice e intermedi.

[in] Encoding

Valore di enumerazione EncodingType che specifica il tipo di codifica applicato al certificato con codifica DER. Il valore predefinito è XCN_CRYPT_STRING_BASE64.

[in] InheritOptions

Valore di enumerazione X509RequestInheritOptions che specifica come creare l'oggetto richiesta certificato dal certificato esistente. È possibile specificare come ereditare una chiave scegliendo uno dei valori seguenti. Il valore predefinito è InheritDefault.

Valore Significato
EreditaDefault
 L'ereditarietà del provider e della chiave non è specificata.
ErediNewDefaultKey
 Crea una nuova chiave ma eredita il provider di crittografia predefinito.
ErediNewSimilarKey
 Crea una nuova chiave, ma eredita il provider di crittografia usato per creare il certificato esistente.
ErediPrivateKey
 Eredita le chiavi private e pubbliche.
EreditaPublicKey
 Eredita solo la chiave pubblica.
 

È anche possibile usare un'operazione bit per bit-AND per combinare il valore di ereditarietà della chiave con qualsiasi combinazione dei valori seguenti.

Valore Significato
InheritRenewalCertificateFlag
 Eredita il certificato di rinnovo. Specificando questo flag viene impostato un valore ICertPropertyRenewal .
EreditaTemplateFlag
 Eredita il modello di certificato.
EreditaSubjectFlag
 Eredita il nome distinto dell'oggetto.
EreditaExtensionsFlag
 Eredita le estensioni pertinenti dal certificato.
EreditaSubjectAltNameFlag
 Eredita l'estensione SubjectAlternativeName .
Eredita validitàPeriodFlag
 Eredita il periodo di validità.
 

È anche possibile specificare InheritNone per impedire l'implementazione predefinita di uno dei flag nella tabella precedente (flag non correlati all'ereditarietà delle chiavi). Se si specifica ErediNone ma si specifica anche un flag non correlato all'ereditarietà delle chiavi, il metodo restituisce E_INVALIDARG.

Se si imposta il parametro InheritOptions su zero (0) o si specifica ErediDefault e non si specifica un valore di ereditarietà della chiave, ErediNewSimilarKey viene usato per impostazione predefinita.

Se si imposta il parametro InheritOptions su zero (0) o si specifica ErediDefault e non si specifica uno dei valori non correlati all'ereditarietà delle chiavi, i flag seguenti vengono impostati per impostazione predefinita:

  • EreditaSubjectFlag
  • EreditaExtensionsFlag
  • Eredita validitàPeriodFlag
  • EreditaTemplateFlag (se il certificato contiene un'estensione del modello)
  • InheritRenewalCertificateFlag (se il client sta rinnovando un certificato)

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
ERROR_ALREADY_INITIALIZED
 L'oggetto richiesta certificato è già stato inizializzato.

Commenti

Il metodo InitializeFromCertificate convalida le opzioni specificate nel parametro InheritOptions e inizializza un nuovo oggetto richiesta PKCS #7 eseguendo le azioni seguenti:

  • Crea un oggetto richiesta PKCS #10 dal certificato, dal contesto di registrazione e eredita le opzioni specificate nell'input. L'oggetto PKCS #10 eredita:
    • Modello se presente nel certificato originale e si imposta il valore InheritTemplateFlag .
    • Nome distinto dell'oggetto se si specifica InheritSubjectFlag.
    • Nome alternativo dell'oggetto se si specifica ErediSubjectAltNameFlag.
    • Le estensioni se si specifica ErediExtensionsFlag.
  • Copia il certificato originale, se deve essere rinnovato, nella proprietà RenewalCertificate nella nuova richiesta PKCS #10.
  • Crea un oggetto ISignerCertificate dal certificato originale, se deve essere rinnovato e lo imposta sulla proprietà SignerCertificate .
  • Imposta la richiesta PKCS #10 come oggetto richiesta interna.

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

IX509CertificateRequestPkcs7