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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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.
[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.
[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 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 |
|---|---|
|
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. |
|
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 |