Compartilhar via


Função CryptAcquireCertificatePrivateKey (wincrypt.h)

A função CryptAcquireCertificatePrivateKey obtém a chave privada de um certificado. Essa função é usada para obter acesso à chave privada de um usuário quando o certificado do usuário está disponível, mas o identificador do contêiner de chave do usuário não está disponível. Essa função só pode ser usada pelo proprietário de uma chave privada e não por nenhum outro usuário.

Se um identificador CSP e o contêiner de chave que contém a chave privada de um usuário estiverem disponíveis, a função CryptGetUserKey deverá ser usada.

Sintaxe

BOOL CryptAcquireCertificatePrivateKey(
  [in]           PCCERT_CONTEXT                  pCert,
  [in]           DWORD                           dwFlags,
  [in, optional] void                            *pvParameters,
  [out]          HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
  [out]          DWORD                           *pdwKeySpec,
  [out]          BOOL                            *pfCallerFreeProvOrNCryptKey
);

Parâmetros

[in] pCert

O endereço de uma estrutura CERT_CONTEXT que contém o contexto de certificado para o qual uma chave privada será obtida.

[in] dwFlags

Um conjunto de sinalizadores que modificam o comportamento dessa função. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir.

Valor Significado
CRYPT_ACQUIRE_CACHE_FLAG
Se um identificador já estiver adquirido e armazenado em cache, esse mesmo identificador será retornado. Caso contrário, um novo identificador será adquirido e armazenado em cache usando a propriedade CERT_KEY_CONTEXT_PROP_ID do certificado.

Quando esse sinalizador é definido, o parâmetro pfCallerFreeProvOrNCryptKey recebe FALSE e o aplicativo de chamada não deve liberar o identificador. O identificador é liberado quando o contexto do certificado é liberado; no entanto, você deve manter o contexto de certificado referenciado pelo parâmetro pCert enquanto a chave estiver em uso, caso contrário, as operações que dependem da chave falharão.

CRYPT_ACQUIRE_COMPARE_KEY_FLAG
A chave pública no certificado é comparada com a chave pública retornada pelo provedor de serviços criptográficos (CSP). Se as chaves não corresponderem, a operação de aquisição falhará e o último código de erro será definido como NTE_BAD_PUBLIC_KEY. Se um identificador armazenado em cache for retornado, nenhuma comparação será feita.
CRYPT_ACQUIRE_NO_HEALING
Essa função não tentará recriar a propriedade CERT_KEY_PROV_INFO_PROP_ID no contexto do certificado se essa propriedade não puder ser recuperada.
CRYPT_ACQUIRE_SILENT_FLAG
O CSP não deve exibir nenhuma interface do usuário para esse contexto. Se o CSP precisar exibir a interface do usuário para operar, a chamada falhará e o código de erro NTE_SILENT_CONTEXT será definido como o último erro.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG
Usa a propriedade CERT_KEY_PROV_INFO_PROP_ID do certificado para determinar se o cache deve ser realizado. Para obter mais informações sobre a propriedade CERT_KEY_PROV_INFO_PROP_ID , consulte CertSetCertificateContextProperty.

Essa função só usará o cache se, durante uma chamada anterior, o membro dwFlags da estrutura CRYPT_KEY_PROV_INFO contiver CERT_SET_KEY_CONTEXT_PROP.

CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG
Qualquer interface do usuário necessária para o CSP ou KSP será um filho do HWND fornecido no parâmetro pvParameters . Para uma chave CSP, usar esse sinalizador fará com que a função CryptSetProvParam com o sinalizador PP_CLIENT_HWND usando esse HWND seja chamada com NULL para HCRYPTPROV. Para uma chave KSP, usar esse sinalizador fará com que a função NCryptSetProperty com o sinalizador NCRYPT_WINDOW_HANDLE_PROPERTY seja chamada usando o HWND.

Não use esse sinalizador com CRYPT_ACQUIRE_SILENT_FLAG.

 

Os sinalizadores a seguir determinam qual tecnologia é usada para obter a chave. Se nenhum desses sinalizadores estiver presente, essa função tentará apenas obter a chave usando CryptoAPI.

Windows Server 2003 e Windows XP: Não há suporte para esses sinalizadores.

Valor Significado
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG
Essa função tentará obter a chave usando CryptoAPI. Se isso falhar, essa função tentará obter a chave usando a API de Criptografia: Próxima Geração (CNG).

A variável pdwKeySpec receberá o sinalizador CERT_NCRYPT_KEY_SPEC se o CNG for usado para obter a chave.

CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG
Essa função só tentará obter a chave usando CNG e não usará CryptoAPI para obter a chave.

A variável pdwKeySpec receberá o sinalizador CERT_NCRYPT_KEY_SPEC se o CNG for usado para obter a chave.

CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG
Essa função tentará obter a chave usando CNG. Se isso falhar, essa função tentará obter a chave usando CryptoAPI.

A variável pdwKeySpec receberá o sinalizador CERT_NCRYPT_KEY_SPEC se o CNG for usado para obter a chave.

Nota A CryptoAPI não dá suporte aos algoritmos assimétricos CNG Diffie-Hellman ou DSA. A CryptoAPI dá suporte apenas a chaves públicas Diffie-Hellman e DSA por meio dos CSPs herdados. Se esse sinalizador for definido para um certificado que contém uma chave pública Diffie-Hellman ou DSA, essa função alterará implicitamente esse sinalizador para CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG primeiro tentar usar CryptoAPI para obter a chave.
 

[in, optional] pvParameters

Se o CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG estiver definido, esse será o endereço de um HWND. Se o CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG não estiver definido, esse parâmetro deverá ser NULL.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Esse parâmetro foi nomeado pvReserved e reservado para uso futuro e deve ser NULL.

[out] phCryptProvOrNCryptKey

O endereço de uma variável HCRYPTPROV_OR_NCRYPT_KEY_HANDLE que recebe o identificador do provedor CryptoAPI ou da chave CNG. Se a variável pdwKeySpec receber o sinalizador CERT_NCRYPT_KEY_SPEC , esse será um identificador de chave CNG do tipo NCRYPT_KEY_HANDLE; caso contrário, esse é um identificador de provedor CryptoAPI do tipo HCRYPTPROV.

Para obter mais informações sobre quando e como liberar esse identificador, consulte a descrição do parâmetro pfCallerFreeProvOrNCryptKey .

[out] pdwKeySpec

O endereço de uma variável DWORD que recebe informações adicionais sobre a chave. Esse pode ser um dos valores a seguir.

Valor Significado
AT_KEYEXCHANGE
O par de chaves é um par de troca de chaves.
AT_SIGNATURE
O par de chaves é um par de assinaturas.
CERT_NCRYPT_KEY_SPEC
A chave é uma chave CNG.

Windows Server 2003 e Windows XP: Não há suporte para esse valor.

[out] pfCallerFreeProvOrNCryptKey

O endereço de uma variável BOOL que recebe um valor que indica se o chamador deve liberar o identificador retornado na variável phCryptProvOrNCryptKey . Isso receberá FALSE se qualquer um dos seguintes itens for verdadeiro:

  • Falha na aquisição ou comparação de chave pública.
  • O parâmetro dwFlags contém o sinalizador CRYPT_ACQUIRE_CACHE_FLAG .
  • O parâmetro dwFlags contém o sinalizador CRYPT_ACQUIRE_USE_PROV_INFO_FLAG , a propriedade de contexto do certificado é definida como CERT_KEY_PROV_INFO_PROP_ID com a estrutura CRYPT_KEY_PROV_INFO e o membro dwFlags da estrutura CRYPT_KEY_PROV_INFO está definido como CERT_SET_KEY_CONTEXT_PROP_ID.
Se essa variável receber FALSE, o aplicativo de chamada não deverá liberar o identificador retornado na variável phCryptProvOrNCryptKey . O identificador será liberado na última ação gratuita do contexto do certificado.

Se essa variável receber TRUE, o chamador será responsável por liberar o identificador retornado na variável phCryptProvOrNCryptKey . Se a variável pdwKeySpec receber o valor CERT_NCRYPT_KEY_SPEC , o identificador deverá ser liberado passando-o para a função NCryptFreeObject ; caso contrário, o identificador é liberado passando-o para a função CryptReleaseContext .

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError. Um código de erro possível é o seguinte.

Código de retorno Descrição
NTE_BAD_PUBLIC_KEY
A chave pública no certificado não corresponde à chave pública retornada pelo CSP. Esse código de erro será retornado se o CRYPT_ACQUIRE_COMPARE_KEY_FLAG estiver definido e a chave pública no certificado não corresponder à chave pública retornada pelo provedor criptográfico.
NTE_SILENT_CONTEXT
O parâmetro dwFlags continha o sinalizador CRYPT_ACQUIRE_SILENT_FLAG e o CSP não podia continuar uma operação sem exibir uma interface do usuário.

Comentários

Quando CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG está definido, o chamador deve garantir que o HWND seja válido. Se o HWND não for mais válido, para CSP, o chamador deverá chamar CryptSetProvParam usando o sinalizador PP_CLIENT_HWND com NULL para o HWND e NULL para o HCRYPTPROV. Para KSP, o chamador deve definir o NCRYPT_WINDOW_HANDLE_PROPERTY da chave ncrypt como NULL. Quando CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG sinalizador é definido para KSP, o NCRYPT_WINDOW_HANDLE_PROPERTY é definido no provedor de armazenamento e na chave. Se ambas as chamadas falharem, a função falhará. Se apenas um falhar, a função terá êxito. Observe que a configuração de HWND como NULL remove efetivamente o HWND da chave HCRYPTPROV ou ncrypt.

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de Programa C: Enviando e recebendo uma mensagem assinada e criptografada.

Requisitos

   
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

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Funções de Geração de Chaves e Exchange