Método ICertConfig::GetConfig (certcli.h)

Artículo
03/14/2023

El método GetConfig recupera la cadena de configuración de un servidor de Servicios de certificados. Este método se definió por primera vez en la interfaz ICertConfig .

La cadena de configuración es el nombre del servidor y el nombre de la entidad de certificación separados por una barra diagonal inversa (\); por ejemplo: NombreDeServidor CaName\. Esta cadena de configuración se puede usar para hacer referencia de forma inequívoca a un servidor de Servicios de certificados específico. Para obtener más información, vea la sección Comentarios.

Sintaxis

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

Parámetros

[in] Flags

Valor que especifica la entidad de certificación que se va a usar. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
CC_DEFAULTCONFIG 0x00000000	Recupera la entidad de certificación predeterminada.
CC_FIRSTCONFIG 0x00000002	Devuelve la primera entidad de certificación.
CC_LOCALACTIVECONFIG 0x00000004	Recupera la entidad de certificación local si se está ejecutando.
CC_LOCALCONFIG 0x00000003	Recupera la entidad de certificación local.
CC_UIPICKCONFIG 0x00000001	Muestra una interfaz de usuario que permite al usuario seleccionar una entidad de certificación.
CC_UIPICKCONFIGSKIPLOCALCA 0x00000005	Muestra una interfaz de usuario que permite al usuario seleccionar una entidad de certificación. La interfaz de usuario excluye cualquier entidad de certificación local. Esta exclusión es útil durante la renovación de certificados de entidad de certificación subordinada cuando la solicitud de certificado de entidad de certificación subordinada se envía a una entidad de certificación distinta de la entidad de certificación actual.

[out] pstrOut

Puntero a un BSTR que contiene la configuración. Cuando haya terminado de usar la configuración, llame a la función SysFreeString para liberar pbstrOut.

Valor devuelto

C++

Si el método se realiza correctamente, el método devuelve S_OK.

Si se produce un error en el método, devuelve un valor HRESULT que indica el error. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

VB

El valor devuelto es una cadena que contiene la configuración.

Comentarios

La parte del nombre de la entidad de certificación (CA) de la cadena de configuración que devuelve esta función es el texto exacto especificado durante el proceso de instalación de Servicios de certificados. Tenga en cuenta que este texto puede ser diferente de la forma del nombre de entidad de certificación que se encuentra en los nombres de archivo (por ejemplo, para la lista de revocación de certificados) o en las claves del Registro. Esto se debe a que los nombres de archivo y las claves del Registro usan una versión saneada del nombre de la entidad de certificación.

El proceso de saneamiento del nombre de la entidad de certificación es necesario para quitar caracteres que no son válidos para los nombres de archivo, los nombres de clave del Registro o los valores de nombre distintivos, o no son válidos por motivos específicos de Servicios de certificados. En el proceso de saneamiento, cualquier carácter ilegal del nombre común se convierte en una representación de cinco caracteres en el formato !xxxx, donde ! se usa como carácter de escape y xxxx representa cuatro dígitos hexadecimales que identifican de forma única el carácter que se va a convertir.

Por ejemplo, el signo de número (#) no se permite en nombres distintivos en Active Directory. Si el nombre de ca especificado durante la instalación es #YourName, el nombre de la ENTIDAD de certificación saneada será !0023YourName.

Los caracteres siguientes, si se escriben para el nombre común de la ENTIDAD de certificación durante la instalación, se convierten en !formato xxxx durante el proceso de saneamiento. Esta lista está sujeta a cambios.

Nombre	Carácter	Valor en formato !xxxx
Y comercial	&	!0026
Apóstrofo	'	!0027
Asterisk	*	!002a
Barra diagonal inversa	\	!005c
Llave izquierda	{	!007b
Llave derecha	}	!007d
Corchete de apertura	[	!005b
Corchete de cierre	]	!005d
Símbolo de intercalación	^	!005e
Dos puntos	:	!003a
Coma	,	!002c
Signo igual	=	!003d
Signo de exclamación	!	!0021
Énfasis grave	`	!0060
Signo mayor que	>	!003e
Signo menor que	<	!003c
Signo de número	#	!0023
Paréntesis de apertura	(	!0028
Paréntesis de cierre	)	!0029
Percent	%	!0025
Pipe	\|	!007c
Signo más	+	!002b
Signo de interrogación	?	!003f
Comillas	"	!0022
Punto y coma	;	!003b
Barra diagonal	/	!002f

Cualquier carácter que no sea de impresión y todos los caracteres Unicode que no sean siete bits también se convierten en !formato xxxx .

Se genera un nombre corto saneado cuando el nombre saneado es demasiado largo para un nombre distintivo relativo de 64 caracteres (RDN). El nombre corto saneado consta del nombre saneado truncado y anexado con un hash del nombre completo saneado. El nombre corto saneado reserva algunos de los 64 caracteres para contener sufijos de lista de revocación de certificados (CRL), como (123).

La parte del nombre de la entidad de certificación de la cadena de configuración devuelta por este método es el texto original especificado durante la instalación. Tenga en cuenta que los métodos de Servicios de certificados que requieren un nombre de entidad de certificación como parámetro aceptan el nombre de entidad de certificación especificado originalmente. Por ejemplo, para el nombre # de la entidad de certificación YourName,
El método ICertView2::OpenConnection acepta #YourName como parte de la entidad de certificación del parámetro.

Ejemplos

En el ejemplo siguiente se muestra cómo usar este método para recuperar la cadena de configuración predeterminada de la entidad de certificación.


    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();

Requisitos

Requisito	Value
Cliente mínimo compatible	No se admite ninguno
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	certcli.h (incluya Certsrv.h)
Library	Certidl.lib
Archivo DLL	Certcli.dll