Função CertAddSerializedElementToStore (wincrypt.h)

Artigo
03/15/2023

A função CertAddSerializedElementToStore adiciona um certificado serializado, uma CRL ( lista de revogação de certificado ) ou um elemento CTL ( lista de confiança de certificado ) ao repositório. O elemento serializado contém o certificado codificado, CRL ou CTL e suas propriedades estendidas. As propriedades estendidas são associadas a um certificado e não fazem parte de um certificado, conforme emitido por uma autoridade de certificação. As propriedades estendidas não estão disponíveis em um certificado quando ele é usado em uma plataforma não Microsoft.

Sintaxe

BOOL CertAddSerializedElementToStore(
  [in]  HCERTSTORE hCertStore,
  [in]  const BYTE *pbElement,
  [in]  DWORD      cbElement,
  [in]  DWORD      dwAddDisposition,
  [in]  DWORD      dwFlags,
  [in]  DWORD      dwContextTypeFlags,
  [out] DWORD      *pdwContextType,
  [out] const void **ppvContext
);

Parâmetros

[in] hCertStore

O identificador de um repositório de certificados em que o certificado criado será armazenado. Se hCertStore for NULL, a função criará uma cópia de um contexto de certificado, CRL ou CTL com suas propriedades estendidas, mas o certificado, CRL ou CTL não será persistido em nenhum repositório.

[in] pbElement

Um ponteiro para um buffer que contém as informações de certificado, CRL ou CTL a serem serializadas e adicionadas ao repositório de certificados.

[in] cbElement

O tamanho, em bytes, do buffer pbElement .

[in] dwAddDisposition

Especifica a ação a ser tomada se o certificado, a CRL ou a CTL já existirem no repositório. Os valores de disposição definidos atualmente são mostrados na tabela a seguir.

Valor	Significado
CERT_STORE_ADD_NEW	Se o certificado, CRL ou CTL for novo, ele será criado e persistido no repositório. A operação falhará se um certificado idêntico, CRL ou CTL já existir no repositório. O último código de erro é definido como CRYPT_E_EXISTS.
CERT_STORE_ADD_USE_EXISTING	Se o certificado, CRL ou CTL for novo, ele será adicionado ao repositório. Se já existir um certificado idêntico, CRL ou CTL, o elemento existente será usado. Se ppvContext não for NULL, o contexto existente será duplicado. A função só adiciona propriedades que ainda não existem. As propriedades de hash SHA-1 e MD5 não são copiadas.
CERT_STORE_ADD_REPLACE_EXISTING	Se um certificado idêntico, CRL ou CTL já existir no repositório, o contexto existente de certificado, CRL ou CTL será excluído antes de criar e adicionar o novo contexto.
CERT_STORE_ADD_ALWAYS	Nenhuma marcar é feita para determinar se já existe um certificado idêntico, CRL ou CTL. Um novo elemento sempre é criado. Isso pode levar a duplicatas no repositório. Para determinar se o elemento já existe no repositório, chame CertGetCRLFromStore ou CertGetSubjectCertificateFromStore.
CERT_STORE_ADD_NEWER	Se existir uma CRL ou CTL correspondente ou um link para uma CRL ou CTL correspondente, a função comparará os tempos de NotBefore na CRL ou CTL. Se a CRL ou CTL existente tiver um tempo NotBefore menor que o tempo NotBefore no novo elemento, o elemento ou link antigo será substituído exatamente como por CERT_STORE_ADD_REPLACE_EXISTING. Se o elemento existente tiver um tempo NotBefore maior ou igual ao tempo NotBefore no elemento a ser adicionado, a função falhará com GetLastError retornando o código CRYPT_E_EXISTS. Se uma CRL ou CTL correspondente ou um link para uma CRL ou CTL correspondente não for encontrado no repositório, um novo elemento será adicionado ao repositório.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES	A ação é a mesma que para CERT_STORE_ADD_NEWER. No entanto, se uma CRL ou CTL mais antiga for substituída, as propriedades do elemento mais antigo serão incorporadas à substituição.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES	Se houver um certificado correspondente no repositório, o contexto existente será excluído antes de criar e adicionar o novo contexto. O novo contexto adicionado herda as propriedades do certificado existente.

[in] dwFlags

Reservado para uso futuro e deve ser zero.

[in] dwContextTypeFlags

Especifica os contextos que podem ser adicionados. Por exemplo, para adicionar um certificado, CRL ou CTL, defina dwContextTypeFlags como CERT_STORE_CERTIFICATE_CONTEXT_FLAG ou CERT_STORE_CRL_CONTEXT_FLAG.

Os sinalizadores de tipo de contexto definidos no momento são mostrados na tabela a seguir.

Valor	Significado
CERT_STORE_ALL_CONTEXT_FLAG	Adiciona qualquer contexto.
CERT_STORE_CERTIFICATE_CONTEXT_FLAG	Adiciona apenas um contexto de certificado.
CERT_STORE_CRL_CONTEXT_FLAG	Adiciona apenas um contexto de CRL.
CERT_STORE_CTL_CONTEXT_FLAG	Adiciona apenas um contexto CTL.

[out] pdwContextType

Um ponteiro para o tipo de contexto do elemento serializado adicionado. Esse é um parâmetro opcional e pode ser NULL, o que indica que o aplicativo de chamada não requer o tipo de contexto .

Os tipos de contexto definidos atualmente são mostrados na tabela a seguir.

Valor	Significado
CERT_STORE_CERTIFICATE_CONTEXT	Certificados
CERT_STORE_CRL_CONTEXT	CRLs
CERT_STORE_CTL_CONTEXT	CTLs

[out] ppvContext

Um ponteiro para um ponteiro para o contexto de certificado, CRL ou CTL decodificado. Esse é um parâmetro opcional e pode ser NULL, o que indica que o aplicativo de chamada não requer o contexto do certificado adicionado ou existente, CRL ou CTL.

Se ppvContext não for NULL, ele deverá ser o endereço de um ponteiro para um CERT_CONTEXT, CRL_CONTEXT ou CTL_CONTEXT. Quando o aplicativo for concluído com o contexto, o contexto deverá ser liberado usando CertFreeCertificateContext para um certificado, CertFreeCRLContext para uma CRL ou CertFreeCTLContext para uma CTL.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError. Alguns códigos de erro possíveis seguem.

Código de retorno	Descrição
CRYPT_E_EXISTS	Se o parâmetro dwAddDisposition estiver definido como CERT_STORE_ADD_NEW, o certificado, a CRL ou a CTL já existirão no repositório.
E_INVALIDARG	Um valor de disposição que não é válido foi especificado no parâmetro dwAddDisposition .

Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação de ASN.1 (Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Codificação/Decodificação de Valores Retornados do ASN.1.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll

Confira também

CertSerializeCRLStoreElement

CertSerializeCertificateStoreElement

Funções de manutenção do repositório de certificados e certificados

Compartilhar via