Compartilhar via


Função CryptSetProvParam (wincrypt.h)

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração de Criptografia. A Microsoft pode remover essa API em versões futuras.
 
A função CryptSetProvParam personaliza as operações de um CSP ( provedor de serviços criptográficos ). Essa função geralmente é usada para definir um descritor de segurança no contêiner de chaves associado a um CSP para controlar o acesso às chaves privadas nesse contêiner de chave.

Sintaxe

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parâmetros

[in] hProv

O identificador de um CSP para o qual definir valores. Esse identificador já deve ter sido criado usando a função CryptAcquireContext .

[in] dwParam

Especifica o parâmetro a ser definido. Esse pode ser um dos valores a seguir.

Valor Significado
PP_CLIENT_HWND
1 (0x1)
Defina o identificador de janela que o provedor usa como o pai de todas as caixas de diálogo que ele cria. pbData contém um ponteiro para um HWND que contém o identificador de janela pai.

Esse parâmetro deve ser definido antes de chamar CryptAcquireContext porque muitos CSPs exibirão uma interface do usuário quando CryptAcquireContext for chamado. Você pode passar NULL para o parâmetro hProv para definir esse identificador de janela para todos os contextos criptográficos adquiridos posteriormente nesse processo.

PP_DELETEKEY
24 (0x18)
Exclua a chave efêmera associada a um contexto de hash, criptografia ou verificação. Isso liberará memória e limpará as configurações do Registro associadas à chave.
PP_KEYEXCHANGE_ALG
Essa constante não é usada.
PP_KEYEXCHANGE_PIN
32 (0x20)
Especifica que o PIN de troca de chaves está contido em pbData. O PIN é representado como uma cadeia de caracteres ASCII terminada em nulo.
PP_KEYEXCHANGE_KEYSIZE
Essa constante não é usada.
PP_KEYSET_SEC_DESCR
8 (0x8)
Define o descritor de segurança no contêiner de armazenamento de chaves. O parâmetro pbData é o endereço de uma estrutura SECURITY_DESCRIPTOR que contém o novo descritor de segurança para o contêiner de armazenamento de chaves.
PP_PIN_PROMPT_STRING
44 (0x2C)
Define uma cadeia de caracteres de prompt alternativa a ser exibida para o usuário quando o PIN do usuário é solicitado. O parâmetro pbData é um ponteiro para uma cadeia de caracteres Unicode terminada em nulo.
PP_ROOT_CERTSTORE
46 (0x2E)
Define o repositório de certificados raiz para o cartão inteligente. O provedor copiará os certificados raiz desse repositório para o cartão inteligente.

O parâmetro pbData é uma variável HCERTSTORE que contém o identificador do novo repositório de certificados. O provedor copiará os certificados do repositório durante essa chamada, portanto, é seguro fechar esse repositório depois que essa função for chamada.

Windows XP e Windows Server 2003: Não há suporte para esse parâmetro.

PP_SIGNATURE_ALG
Essa constante não é usada.
PP_SIGNATURE_PIN
33 (0x21)
Especifica o PIN de assinatura. O parâmetro pbData é uma cadeia de caracteres ASCII terminada em nulo que representa o PIN.
PP_SIGNATURE_KEYSIZE
Essa constante não é usada.
PP_UI_PROMPT
21 (0x15)
Para um provedor de cartão inteligente, define a cadeia de caracteres de pesquisa exibida para o usuário como um prompt para inserir o cartão inteligente. Essa cadeia de caracteres é passada como o membro lpstrSearchDesc da estrutura OPENCARDNAME_EX que é passada para a função SCardUIDlgSelectCard . Essa cadeia de caracteres é usada durante o tempo de vida do processo de chamada.

O parâmetro pbData é um ponteiro para uma cadeia de caracteres Unicode terminada em nulo.

PP_USE_HARDWARE_RNG
38 (0x26)
Especifica que o CSP deve usar exclusivamente o RNG (gerador de número aleatório) de hardware. Quando PP_USE_HARDWARE_RNG é definido, os valores aleatórios são obtidos exclusivamente do RNG de hardware e nenhuma outra fonte é usada. Se um RNG de hardware tiver suporte do CSP e puder ser usado exclusivamente, a função terá êxito e retornará TRUE; caso contrário, a função falhará e retornará FALSE. O parâmetro pbData deve ser NULL e dwFlags deve ser zero ao usar esse valor.

Nenhum dos CSPs da Microsoft atualmente dá suporte ao uso de um RNG de hardware.

PP_USER_CERTSTORE
42 (0x2A)
Especifica o repositório de certificados do usuário para o cartão inteligente. Esse repositório de certificados contém todos os certificados de usuário armazenados no cartão inteligente. Os certificados nesse repositório são codificados usando PKCS_7_ASN_ENCODING ou codificação X509_ASN_ENCODING e devem conter a propriedade CERT_KEY_PROV_INFO_PROP_ID .

O parâmetro pbData é uma variável HCERTSTORE que recebe o identificador de um repositório de certificados na memória. Quando esse identificador não é mais necessário, o chamador deve fechá-lo usando a função CertCloseStore .

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_SECURE_KEYEXCHANGE_PIN
47 (0x2F)
Especifica que um PIN de troca de chaves criptografada está contido em pbData. O parâmetro pbData contém um DATA_BLOB.
PP_SECURE_SIGNATURE_PIN
48 (0x30)
Especifica que um PIN de assinatura criptografado está contido em pbData. O parâmetro pbData contém um DATA_BLOB.
PP_SMARTCARD_READER
43 (0x2B)
Especifica o nome do leitor de cartão inteligente. O parâmetro pbData é o endereço de uma matriz de caracteres ANSI que contém uma cadeia de caracteres ANSI terminada em nulo que contém o nome do leitor de cartão inteligente.

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_SMARTCARD_GUID
45 (0x2D)
Especifica o identificador do cartão inteligente. O parâmetro pbData é o endereço de uma estrutura GUID que contém o identificador do cartão inteligente.

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

[in] pbData

Um ponteiro para um buffer de dados que contém o valor a ser definido como um parâmetro de provedor. A forma desses dados varia dependendo do valor dwParam . Se dwParam contiver PP_USE_HARDWARE_RNG, esse parâmetro deverá ser NULL.

[in] dwFlags

Se dwParam contiver PP_KEYSET_SEC_DESCR, dwFlags conterá os SECURITY_INFORMATION sinalizadores de bits aplicáveis, conforme definido no SDK da Plataforma. A segurança do contêiner de chaves é tratada usando SetFileSecurity e GetFileSecurity.

Esses sinalizadores de bits podem ser combinados usando uma operação OR bit a bit. Para obter mais informações, consulte CryptGetProvParam.

Se dwParam for PP_USE_HARDWARE_RNG ou PP_DELETEKEY, dwFlags deverá ser definido como zero.

Retornar valor

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.

Os códigos de erro precedidos por "NTE" são gerados pelo CSP específico que está sendo usado. Os códigos de erro incluem o seguinte.

Código de retorno Descrição
ERROR_BUSY
O contexto do CSP está sendo usado por outro processo.
ERROR_INVALID_HANDLE
Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido.
NTE_BAD_FLAGS
O parâmetro dwFlags é diferente de zero ou o buffer pbData contém um valor que não é válido.
NTE_BAD_TYPE
O parâmetro dwParam especifica um parâmetro desconhecido.
NTE_BAD_UID
O contexto CSP especificado quando a chave hKey foi criada não pode ser encontrado.
NTE_FAIL
A função falhou de alguma forma inesperada.

Requisitos

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

Confira também

Cryptacquirecontext

Cryptgetprovparam

Cryptsetkeyparam

Funções do provedor de serviços