Función CertAddCertificateContextToStore (wincrypt.h)

  • Artículo

La función CertAddCertificateContextToStore agrega un contexto de certificado al almacén de certificados.

Sintaxis

BOOL CertAddCertificateContextToStore(
  [in]            HCERTSTORE     hCertStore,
  [in]            PCCERT_CONTEXT pCertContext,
  [in]            DWORD          dwAddDisposition,
  [out, optional] PCCERT_CONTEXT *ppStoreContext
);

Parámetros

[in] hCertStore

Identificador de un almacén de certificados.

[in] pCertContext

Puntero a la estructura CERT_CONTEXT que se va a agregar al almacén.

[in] dwAddDisposition

Especifica la acción que se debe realizar si ya existe un certificado coincidente o un vínculo a un certificado coincidente en el almacén. Los valores de disposición definidos actualmente y sus usos son los siguientes.

Valor Significado
CERT_STORE_ADD_ALWAYS
 La función no comprueba si hay un certificado coincidente existente o un vínculo a un certificado coincidente. Siempre se agrega un nuevo certificado al almacén. Esto puede provocar duplicados en un almacén.
CERT_STORE_ADD_NEW
 Si existe un certificado coincidente o un vínculo a un certificado coincidente, se produce un error en la operación. GetLastError devuelve el código CRYPT_E_EXISTS.
CERT_STORE_ADD_NEWER
 Si existe un certificado coincidente o un vínculo a un certificado coincidente y la hora NotBefore del contexto existente es igual o mayor que la hora NotBefore del nuevo contexto que se va a agregar, se produce un error en la operación y GetLastError devuelve el código de CRYPT_E_EXISTS.

Si la hora NotBefore del contexto existente es menor que la hora de NotBefore del nuevo contexto que se va a agregar, se elimina el certificado o vínculo existente y se crea un nuevo certificado y se agrega al almacén. Si no existe un certificado coincidente o un vínculo a un certificado coincidente, se agrega un nuevo vínculo.

Si se comparan listas de revocación de certificados (CRL) o lista de confianza de certificados (CTL), se usa la hora ThisUpdate.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES
 Si existe un certificado coincidente o un vínculo a un certificado coincidente y la hora NotBefore del contexto existente es igual o mayor que la hora NotBefore del nuevo contexto que se va a agregar, se produce un error en la operación y GetLastError devuelve el código de CRYPT_E_EXISTS.

Si la hora NotBefore del contexto existente es menor que la hora NotBefore del nuevo contexto que se va a agregar, el contexto existente se elimina antes de crear y agregar el nuevo contexto. El nuevo contexto agregado hereda las propiedades del certificado existente.

Si se comparan crLs o CTL, se usa la hora ThisUpdate.
CERT_STORE_ADD_REPLACE_EXISTING
 Si existe un vínculo a un certificado coincidente, se elimina ese certificado o vínculo existente y se crea y se agrega un nuevo certificado al almacén. Si no existe un certificado coincidente o un vínculo a un certificado coincidente, se agrega un nuevo vínculo.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES
 Si existe un certificado coincidente en el almacén, no se reemplaza el contexto existente. El contexto existente hereda las propiedades del nuevo certificado.
CERT_STORE_ADD_USE_EXISTING
 Si existe un certificado coincidente o un vínculo a un certificado coincidente, se usa ese certificado o vínculo existente y se agregan las propiedades del nuevo certificado. No se produce un error en la función, pero no agrega un nuevo contexto. Si pCertContext no es NULL, se duplica el contexto existente.

Si no existe un certificado coincidente o un vínculo a un certificado coincidente, se agrega un nuevo certificado.

[out, optional] ppStoreContext

Puntero a un puntero a la copia que se va a realizar del certificado que se agregó al almacén.

El parámetro ppStoreContext puede ser NULL, lo que indica que la aplicación que realiza la llamada no requiere una copia del certificado agregado. Si se realiza una copia, debe liberarse mediante CertFreeCertificateContext.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es TRUE.

Si se produce un error en la función, el valor devuelto es FALSE. Para obtener información de error extendida, llame a GetLastError. Siguen algunos códigos de error posibles.

Código devuelto Descripción
CRYPT_E_EXISTS
 Este valor se devuelve si se establece CERT_STORE_ADD_NEW y el certificado ya existe en el almacén, o si se establece CERT_STORE_ADD_NEWER y existe un certificado en el almacén con una fecha NotBefore mayor o igual que la fecha NotBefore en el certificado que se va a agregar.
E_INVALIDARG
 Se especificó un valor de disposición que no es válido en el parámetro dwAddDisposition .
 

Los errores de las funciones llamadas, CertAddEncodedCertificateToStore y CertSetCertificateContextProperty, se pueden propagar a esta función.

Comentarios

El contexto del certificado no se duplica mediante CertDuplicateCertificateContext. En su lugar, la función crea una nueva copia del contexto y la agrega al almacén.

Además del certificado codificado, CertDuplicateCertificateContext también copia las propiedades del contexto, a excepción de las propiedades CERT_KEY_PROV_HANDLE_PROP_ID y CERT_KEY_CONTEXT_PROP_ID.

Para quitar el contexto de certificado del almacén de certificados, use la función CertDeleteCertificateFromStore .

Nota Es posible que el orden del contexto del certificado no se conserve dentro del almacén. Para acceder a un certificado específico, debe recorrer en iteración los certificados del almacén.
 

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Crypt32.lib
Archivo DLL Crypt32.dll

Consulte también

CertAddEncodedCertificateToStore

CertSetCertificateContextProperty

Funciones de certificado