Função BCryptEncrypt (bcrypt.h)
A função BCryptEncrypt criptografa um bloco de dados.
Sintaxe
NTSTATUS BCryptEncrypt(
[in, out] BCRYPT_KEY_HANDLE hKey,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in, optional] VOID *pPaddingInfo,
[in, out, optional] PUCHAR pbIV,
[in] ULONG cbIV,
[out, optional] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);
Parâmetros
[in, out] hKey
O identificador da chave a ser usada para criptografar os dados. Esse identificador é obtido de uma das principais funções de criação, como BCryptGenerateSymmetricKey, BCryptGenerateKeyPair ou BCryptImportKey.
[in] pbInput
O endereço de um buffer que contém o texto não criptografado a ser criptografado. O parâmetro cbInput contém o tamanho do texto não criptografado a ser criptografado. Para obter mais informações, consulte Comentários.
[in] cbInput
O número de bytes no buffer pbInput a ser criptografado.
[in, optional] pPaddingInfo
Um ponteiro para uma estrutura que contém informações de preenchimento. Esse parâmetro só é usado com chaves assimétricas e modos de criptografia autenticados. Se um modo de criptografia autenticado for usado, esse parâmetro deverá apontar para uma estrutura BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO . Se chaves assimétricas forem usadas, o tipo de estrutura para a qual esse parâmetro aponta será determinado pelo valor do parâmetro dwFlags . Caso contrário, o parâmetro deverá ser definido como NULL.
[in, out, optional] pbIV
O endereço de um buffer que contém o IV (vetor de inicialização ) a ser usado durante a criptografia. O parâmetro cbIV contém o tamanho desse buffer. Essa função modificará o conteúdo desse buffer. Se você precisar reutilizar o IV mais tarde, certifique-se de fazer uma cópia desse buffer antes de chamar essa função.
Esse parâmetro é opcional e pode ser NULL se nenhum IV for usado.
O tamanho necessário do IV pode ser obtido chamando a função BCryptGetProperty para obter a propriedade BCRYPT_BLOCK_LENGTH . Isso fornecerá o tamanho de um bloco para o algoritmo, que também é o tamanho do IV.
[in] cbIV
O tamanho, em bytes, do buffer pbIV .
[out, optional] pbOutput
O endereço do buffer que recebe o texto cifrado produzido por essa função. O parâmetro cbOutput contém o tamanho desse buffer. Para obter mais informações, consulte Comentários.
Se esse parâmetro for NULL, a função BCryptEncrypt calculará o tamanho necessário para o texto cifrado dos dados passados no parâmetro pbInput . Nesse caso, o local apontado pelo parâmetro pcbResult contém esse tamanho e a função retorna STATUS_SUCCESS. O parâmetro pPaddingInfo não foi modificado.
Se os valores dos parâmetros pbOutput e pbInput forem NULL, um erro será retornado, a menos que um algoritmo de criptografia autenticado esteja em uso. No último caso, a chamada é tratada como uma chamada de criptografia autenticada com dados de comprimento zero e a marca de autenticação é retornada no parâmetro pPaddingInfo .
[in] cbOutput
O tamanho, em bytes, do buffer pbOutput . Esse parâmetro será ignorado se o parâmetro pbOutput for NULL.
[out] pcbResult
Um ponteiro para uma variável ULONG que recebe o número de bytes copiados para o buffer pbOutput . Se pbOutput for NULL, isso receberá o tamanho, em bytes, necessário para o texto cifrado.
[in] dwFlags
Um conjunto de sinalizadores que modificam o comportamento dessa função. O conjunto permitido de sinalizadores depende do tipo de chave especificado pelo parâmetro hKey .
Se a chave for uma chave simétrica, ela poderá ser zero ou o valor a seguir.
| Valor | Significado |
|---|---|
|
Permite que o algoritmo de criptografia adicione os dados ao próximo tamanho do bloco. Se esse sinalizador não for especificado, o tamanho do texto não criptografado especificado no parâmetro cbInput deverá ser um múltiplo do tamanho do bloco do algoritmo.
O tamanho do bloco pode ser obtido chamando a função BCryptGetProperty para obter a propriedade BCRYPT_BLOCK_LENGTH da chave. Isso fornecerá o tamanho de um bloco para o algoritmo. Esse sinalizador não deve ser usado com os modos de criptografia autenticados (AES-CCM e AES-GCM). |
Se a chave for uma chave assimétrica, esse poderá ser um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Não use nenhum preenchimento. O parâmetro pPaddingInfo não é usado. O tamanho do texto não criptografado especificado no parâmetro cbInput deve ser um múltiplo do tamanho do bloco do algoritmo. |
|
Use o esquema OAEP (Preenchimento de Criptografia Assimétrica Ideal). O parâmetro pPaddingInfo é um ponteiro para uma estrutura BCRYPT_OAEP_PADDING_INFO . |
|
Os dados serão preenchidos com um número aleatório para arredondar o tamanho do bloco. O parâmetro pPaddingInfo não é usado. |
Retornar valor
Retorna um código status que indica o êxito ou a falha da função.
Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.
| Código de retorno | Descrição |
|---|---|
|
A função foi bem-sucedida. |
|
O tamanho especificado pelo parâmetro cbOutput não é grande o suficiente para conter o texto cifrado. |
|
O parâmetro cbInput não é um múltiplo do tamanho do bloco do algoritmo e o BCRYPT_BLOCK_PADDING ou o sinalizador BCRYPT_PAD_NONE não foi especificado no parâmetro dwFlags . |
|
O identificador de chave no parâmetro hKey não é válido. |
|
Um ou mais dos parâmetros não são válidos. |
|
O algoritmo não dá suporte à criptografia. |
Comentários
Os parâmetros pbInput e pbOutput podem ser iguais. Nesse caso, essa função executará a criptografia em vigor. É possível que o tamanho dos dados criptografados seja maior do que o tamanho dos dados não criptografados, portanto, o buffer deve ser grande o suficiente para conter os dados criptografados. Se pbInput e pbOutput não forem iguais, os dois buffers poderão não se sobrepor.
Dependendo de quais modos de processador um provedor dá suporte, BCryptEncrypt pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem ser executados em PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Se o nível IRQL atual for DISPATCH_LEVEL, o identificador fornecido no parâmetro hKey deverá ser derivado de um identificador de algoritmo retornado por um provedor que foi aberto com o sinalizador BCRYPT_PROV_DISPATCH e quaisquer ponteiros passados para a função BCryptEncrypt deverão se referir à memória não paga (ou bloqueada).
Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | bcrypt.h |
| Biblioteca | Bcrypt.lib |
| DLL | Bcrypt.dll |