Metodo ICertConfig::GetConfig (certcli.h)

Articolo
03/14/2023

Il metodo GetConfig recupera la stringa di configurazione per un server Di Servizi certificati . Questo metodo è stato definito per la prima volta nell'interfaccia ICertConfig .

La stringa di configurazione è il nome del server e il nome dell'autorità di certificazione separati da una barra rovesciata (\); ad esempio: ServerName CAName\. Questa stringa di configurazione può essere usata per fare riferimento senza ambiguità a un server di Servizi certificati specifico. Per altre informazioni, vedere la sezione Osservazioni.

Sintassi

HRESULT GetConfig(
  [in]  LONG Flags,
  [out] BSTR *pstrOut
);

Parametri

[in] Flags

Valore che specifica l'autorità di certificazione da usare. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
CC_DEFAULTCONFIG 0x00000000	Recupera l'autorità di certificazione predefinita.
CC_FIRSTCONFIG 0x00000002	Restituisce la prima autorità di certificazione.
CC_LOCALACTIVECONFIG 0x00000004	Recupera l'autorità di certificazione locale se è in esecuzione.
CC_LOCALCONFIG 0x00000003	Recupera l'autorità di certificazione locale.
CC_UIPICKCONFIG 0x00000001	Visualizza un'interfaccia utente che consente all'utente di selezionare un'autorità di certificazione.
CC_UIPICKCONFIGSKIPLOCALCA 0x00000005	Visualizza un'interfaccia utente che consente all'utente di selezionare un'autorità di certificazione. L'interfaccia utente esclude qualsiasi autorità di certificazione locale. Questa esclusione è utile durante il rinnovo del certificato dell'autorità di certificazione subordinata quando la richiesta di certificato dell'autorità di certificazione subordinata viene inviata a un'autorità di certificazione diversa dall'autorità di certificazione corrente.

[out] pstrOut

Puntatore a un BSTR contenente la configurazione. Al termine dell'uso della configurazione, chiamare la funzione SysFreeString per liberare pbstrOut.

Valore restituito

C++

Se il metodo ha esito positivo, il metodo restituisce S_OK.

Se il metodo ha esito negativo, restituisce un valore HRESULT che indica l'errore. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.

VB

Il valore restituito è una stringa che contiene la configurazione.

Commenti

La parte del nome dell'autorità di certificazione (CA) della stringa di configurazione restituita è il testo esatto immesso durante il processo di installazione di Servizi certificati. Si noti che questo testo può essere diverso dal formato del nome della CA trovato nei nomi di file (ad esempio per l'elenco di revoche di certificati) o nelle chiavi del Registro di sistema. Ciò avviee perché i nomi dei file e le chiavi del Registro di sistema usano una versione sanificata del nome della CA.

Il processo di sanificazione del nome della CA è necessario per rimuovere i caratteri non validi per i nomi dei file, i nomi delle chiavi del Registro di sistema o i valori dei nomi distinti o per motivi specifici dei servizi certificati. Nel processo di pulizia, qualsiasi carattere illegale nel nome comune viene convertito in una rappresentazione di cinque caratteri nel formato !xxxx, dove ! viene usato come carattere di escape e xxxx rappresenta quattro cifre esadecimali che identificano in modo univoco il carattere da convertire.

Ad esempio, il segno numero (#) non è consentito nei nomi distinti in Active Directory. Se il nome della CA immesso durante l'installazione è #YourName, il nome della CA sanificato sarà !0023YourName.

I caratteri seguenti, se immessi per il nome comune della CA durante l'installazione, vengono convertiti in !formato xxxx durante il processo di sanificazione. L'elenco è soggetto a variazioni.

Nome	Carattere	Valore in formato !xxxx
E commerciale	&	!0026
Apostrofo	'	!0027
Asterisco	*	!002a
Barra rovesciata	\	!005c
Parentesi graffe sinistra	{	!007b
Parentesi graffe destra	}	!007d
Parentesi quadra aperta	[	!005b
Parentesi quadra chiusa	]	!005d
Cursore	^	!005e
Due punti	:	!003a
Virgola	,	!002c
Segno di uguale	=	!003d
Punto esclamativo	!	!0021
Accento grave	`	!0060
Segno maggiore di	>	!003e
Minore di segno	<	!003c
Segno numero	#	!0023
Parentesi di apertura	(	!0028
Parentesi di chiusura	)	!0029
Percentuale	%	!0025
Pipe	\|	!007c
Segno più	+	!002b
Punto interrogativo	?	!003f
Virgoletta	"	!0022
Semicolon	;	!003b
Barra	/	!002f

Tutti i caratteri non stampabili e tutti i caratteri Unicode che non sono sette bit vengono convertiti anche in !formato xxxx .

Un nome breve sanificato viene generato quando il nome crittografato è troppo lungo per un nome distinto di 64 caratteri per i servizi directory di 64 caratteri. Il nome breve sanificato è costituito dal nome sanificato troncato e accodato con un hash del nome completamente sanificato. Il nome breve crittografato riserva alcuni dei 64 caratteri per contenere suffissi di elenco di revoche di certificati (CRL), ad esempio (123).

La parte del nome dell'autorità di certificazione della stringa di configurazione restituita da questo metodo è il testo originale immesso durante l'installazione. Si noti che i metodi di Servizi certificati che richiedono un nome di autorità di certificazione come parametro accettano il nome dell'autorità di certificazione immesso in origine. Ad esempio, per il nome # dell'autorità di certificazione YourName,
Il metodo ICertView2::OpenConnection accetta #YourName come parte dell'autorità di certificazione del parametro.

Esempio

Nell'esempio seguente viene illustrato come usare questo metodo per recuperare la stringa di configurazione dell'autorità di certificazione predefinita.


    ICertConfig2 * pConfig = NULL;
    BSTR  bstrConfig = NULL; //Contains CA configuration name
    HRESULT    hr;

    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx - [%x]\n", hr);
        goto error;
    }

    // Create an instance of the CertConfig object.
    hr = CoCreateInstance( CLSID_CCertConfig,
                           NULL,
                           CLSCTX_INPROC_SERVER,
                           IID_ICertConfig2,
                           (void **)&pConfig);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance - pConfig [%x]\n", hr);
        goto error;
    }

    // Retrieve the default CA configuration string.
    hr = pConfig->GetConfig(CC_DEFAULTCONFIG, &bstrConfig);
    if (FAILED(hr))
    {
        printf("Failed GetConfig - [%x]\n", hr);
        goto error;
    }
    else
        printf("GetConfig returned: %ws\n", bstrConfig );

error:

    // Done processing.
    if (pConfig)
        pConfig->Release();

    if (bstrConfig)
        SysFreeString(bstrConfig);

    CoUninitialize();

Requisiti

Requisito	Valore
Client minimo supportato	Nessuno supportato
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	certcli.h (include Certsrv.h)
Libreria	Certidl.lib
DLL	Certcli.dll