Função CertAddCTLLinkToStore (wincrypt.h)

Artigo
08/27/2023

A função CertAddCTLLinkToStore adiciona um link em um repositório a um contexto de CTL (lista de confiança de certificado) em um repositório diferente. Em vez de criar e adicionar uma duplicata de um contexto CTL, essa função adiciona um link ao contexto CTL original.

Sintaxe

BOOL CertAddCTLLinkToStore(
  [in]            HCERTSTORE    hCertStore,
  [in]            PCCTL_CONTEXT pCtlContext,
  [in]            DWORD         dwAddDisposition,
  [out, optional] PCCTL_CONTEXT *ppStoreContext
);

Parâmetros

[in] hCertStore

Identificador do repositório de certificados em que o link deve ser adicionado.

[in] pCtlContext

Um ponteiro para a estrutura CTL_CONTEXT a ser vinculada.

[in] dwAddDisposition

Especifica a ação a ser tomada se uma CTL correspondente ou um link para uma CTL correspondente já existir no repositório. Os valores de disposição definidos no momento e seus usos são os seguintes.

Valor	Significado
CERT_STORE_ADD_ALWAYS	Não faz marcar para uma CTL correspondente existente ou vincula a uma CTL correspondente. Uma nova CTL sempre é adicionada ao repositório. Isso pode levar a duplicatas em um repositório.
CERT_STORE_ADD_NEW	Se existir uma CTL correspondente ou um link para uma CTL correspondente, a operação falhará. GetLastError retorna o código CRYPT_E_EXISTS.
CERT_STORE_ADD_NEWER	Se existir uma CTL correspondente ou um link para uma CTL correspondente, os tempos de ThisUpdate nas CTLs serão comparados. Se a CTL existente tiver um tempo ThisUpdate menor que o tempo ThisUpdate na nova CTL, o ctl ou link antigo será substituído da mesma forma que o CERT_STORE_ADD_REPLACE_EXISTING. Se a CTL existente tiver um tempo ThisUpdate maior ou igual ao tempo ThisUpdate na CTL a ser adicionada, a função falhará com GetLastError retornando o código CRYPT_E_EXISTS. Se uma CTL correspondente ou um link para uma CTL correspondente não for encontrado no repositório, uma nova CTL será adicionada ao repositório.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES	A ação é a mesma que para CERT_STORE_ADD_NEWER, exceto que, se uma CTL mais antiga for substituída, as propriedades da CTL mais antiga serão incorporadas à CTL de substituição.
CERT_STORE_ADD_REPLACE_EXISTING	Se existir uma CTL correspondente ou um link para uma CTL correspondente, o CTL ou link existente será excluído e uma nova CTL será criada e adicionada ao repositório. Se uma CTL correspondente ou um link para uma CTL correspondente não existir, uma será adicionada.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES	Se houver uma CTL correspondente no repositório, esse contexto existente será excluído antes de criar e adicionar o novo contexto. O contexto adicionado herda as propriedades da CTL existente.
CERT_STORE_ADD_USE_EXISTING	Se existir uma CTL correspondente ou um link para uma CTL correspondente, essa CTL existente será usada e as propriedades da nova CTL serão adicionadas. A função não falha, mas nenhuma nova CTL é adicionada. Se ppCertContext não for NULL, o contexto existente será duplicado. Se uma CTL correspondente ou um link para uma CTL correspondente não existir, uma nova CTL será adicionada.

[out, optional] ppStoreContext

Um ponteiro para um ponteiro para uma cópia do link criado. ppStoreContext pode ser NULL para indicar que uma cópia do link não é necessária. Se uma cópia do link for criada, essa cópia deverá ser liberada usando CertFreeCTLContext.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE. 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	Para um dwAddDisposition de CERT_STORE_ADD_NEW, a CTL já existe no repositório.
E_INVALIDARG	A disposição de adição especificada pelo parâmetro dwAddDisposition não é válida.

Comentários

Como o link fornece acesso ao contexto ctl original, definir uma propriedade estendida no contexto ctl vinculado altera essa propriedade estendida no local da CTL original e em qualquer outro links para essa CTL.

Os links não podem ser adicionados a um repositório aberto como uma coleção. As lojas abertas como coleções incluem todas as lojas abertas com CertOpenSystemStore ou CertOpenStore usando CERT_STORE_PROV_SYSTEM ou CERT_STORE_PROV_COLLECTION. Consulte também CertAddStoreToCollection.

Quando links são usados e CertCloseStore é chamado com CERT_CLOSE_STORE_FORCE_FLAG, o repositório que usa links deve ser fechado antes que o repositório que contém os contextos originais seja fechado. Se CERT_CLOSE_STORE_FORCE_FLAG não for usado, os dois repositórios poderão ser fechados em qualquer ordem.

Para remover o link de contexto CTL do repositório de certificados, use a função CertDeleteCTLFromStore .

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