Operações de hash de criptogragia simétrica e assimétrica. Mais...

Funções
int AAP_API	DEncrypt (HKEYCTX hKey, HHASHCTX hHash, BOOL bFinal, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen, DWORD dwBufLen)

int AAP_API	DDecrypt (HKEYCTX hKey, HHASHCTX hHash, BOOL bFinal, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen)

int AAP_API	DCreateHash (HSESSIONCTX hSession, int nAlgId, HKEYCTX hKey, DWORD dwFlags, HHASHCTX *hHash)

int AAP_API	DHashData (HHASHCTX hHash, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DSetHashParam (HHASHCTX hHash, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetHashParam (HHASHCTX hHash, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DSignHash (HHASHCTX hHash, HKEYCTX hKey, DWORD dwFlags, BYTE pbSignature, DWORD pdwSigLen)

int AAP_API	DDestroyHash (HHASHCTX *phHash)

int AAP_API	DVerifySignature (HHASHCTX hHash, BYTE *pbSignature, DWORD dwSigLen, HKEYCTX hPubKey, DWORD dwFlags)

int AAP_API	DDuplicateHash (HHASHCTX hHash, DWORD dwFlag, HHASHCTX *phHash)

int AAP_API	DGetRandom (HSESSIONCTX hSession, BYTE *pbData, DWORD dwDataLen)

int AAP_API	DGenEcdhKey (HSESSIONCTX hSession, DWORD dwOP, char szPriKey, void pvInData, DWORD dwInDataLen, BYTE pbOutData, DWORD pdwOutDataLen, DWORD dwFlags)

int AAP_API	DCRLCertCheck (HSESSIONCTX hSession, char szCRL, char szCertId, char *szVerifyInfo)

Descrição Detalhada

Operações de hash de criptogragia simétrica e assimétrica.

Funções

int AAP_API DEncrypt	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		BOOL	bFinal,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwBufLen
	)

#include <dinamo.h>

Criptografa de dados. O algoritmo usado depende da chave informada no parâmetro hKey.

Parâmetros

[in] hKey Contexto de chave.

[in] hHash Contexto de hash se os dados forem submetidos à operação de hash antes de serem criptografados. Depois da operação completa, o valor do hash pode ser obtido através da função DGetHashParam().

[in] bFinal Indica o último bloco de uma série que foi cifrada. TRUE para último bloco ou FALSE caso contrário.

[in]

dwFlags

Deve ser passado 0, os valores da tabela abaixo são aceitos para casos específicos.

Valor	Significado
D_NO_RSA_PADDING	Não faz/desfaz o padding para chaves RSA. Usar apenas para chaves RSA. Pode ser utilizada juntamente com a flag D_FORCE_ACTUAL_RSA.
D_FORCE_ACTUAL_RSA	Utiliza a chave RSA de maneira direta. Encriptação com chave privada em DEncrypt e decript com DDecrypt. Pode ser utilizada juntamente com a flag D_NO_RSA_PADDING.

[in,out] pbData Ponteiro para um buffer que contem os dados a serem criptografados. Quando a função retorna, os dados originais são sobrescritos pelo resultado da operação de criptografia.
O tamanho buffer é especificado pelo parâmetro dwBufLen, o número de bytes a serem processados é especificado pelo parâmetro pdwDataLen. O tamanho do buffer deve ser grande o suficiente para conter os dados criptografados mais o padding.

[in,out] pdwDataLen Ponteiro para um DWORD que contem o tamanho dos dados em pbData. Quando parâmetro de entrada, contém o número de bytes que serão processados, quando parâmetro de saída, contém o número de bytes dos dados criptografados.
Se o buffer alocado não for suficiente para receber todo o dado cifrado (faltar, por exemplo, espaço para o padding) a função irá falhar retornando D_MORE_DATA.

[in] dwBufLen Tamanho do buffer passado em pbData. Para operações simétricas que exijam padding o buffer deve ter o tamanho mínimo do comprimento do dado mais o tamanho do bloco de operação do algoritmo a ser utilizado.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: Se uma quantidade grande de dados for cifrada, ela pode ser feita em parte, com chamadas subsequentes de DEncrypt. Na última chamada o parâmetro bFinal deve ser passado com valor verdadeiro.

: Apenas no último bloco o padding é feito (quando se aplicar), assim, os demais blocos devem ter tamanho condizente com o algoritmo usado. O buffer onde os dados são passados deve ter tamanho suficiente para acondicionar também o padding.

: Essa API suporta operações RSA feitas diretamente nesta função. Os dados para serem operados devem ter comprimento igual ou menor que o tamanho da chave menos 11 bytes. Quando utilizada a chave pública para criptografia o padding utilizado é PKCS#1 tipo 2 e no processo de decriptografia, o padding é verificado e retirado. Para operações com a chave privada, utiliza-se o padding PKCS#1 tipo 1. O HSM irá verificar a formatação do padding mesmo quando a operação não tem padding definido como em D_NO_RSA_PADDING.

Veja também: DGenerateKey().

Exemplos:: cryptsym.c.

int AAP_API DDecrypt	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		BOOL	bFinal,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen
	)

#include <dinamo.h>

Decriptografa dados, muitas vezes cifrado pela função DEncrypt. O algoritmo usado depende da chave informada no parâmetro hKey.

Parâmetros

[in] hKey Contexto de chave.

[in] hHash Contexto de hash se os dados forem submetidos à operação de hash depois de serem decriptografados. Depois da operação completa, o valor do hash pode ser obtido através da função DGetHashParam().

[in] bFinal Indica o último bloco de uma série que foi cifrada. TRUE para último bloco ou FALSE caso contrário.

[in]

dwFlags

Deve ser passado 0, os valores da tabela abaixo são aceitos para casos específicos.

Valor	Significado
D_NO_RSA_PADDING	Não faz/desfaz o padding para chaves RSA. Usar apenas para chaves RSA. Pode ser utilizada juntamente com a flag D_FORCE_ACTUAL_RSA.
D_FORCE_ACTUAL_RSA	Utiliza a chave RSA de maneira direta. Encriptação com chave privada em DEncrypt e decript com DDecrypt. Pode ser utilizada juntamente com a flag D_NO_RSA_PADDING.

[in,out] pbData Ponteiro para um buffer que contem os dados a serem decriptografados. Quando a função retorna, os dados originais são sobrescritos pelo resultado da operação de criptografia.
Para operações simétricas de bloco, é necessário que o tamanho dos dados seja sempre múltiplo do bloco usado pelo algoritmo em questão.

[in,out] pdwDataLen Ponteiro para um DWORD que contem o tamanho dos dados em pbData. Quando parâmetro de entrada, contém o número de bytes que serão processados, quando parâmetro de saída, contém o número de bytes dos dados em texto claro.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: Se uma quantidade grande de dados for decifrada, ela pode ser feita em parte, com chamadas subsequentes de DDecrypt. Na última chamada o parâmetro bFinal deve ser passado com valor verdadeiro.

: Apenas no último bloco o padding é desfeito (quando se aplicar), assim, os demais blocos devem ter tamanho condizentes com algoritmo usado, e se o modo de operação de criptografia simétrica CBC estiver sendo usado, o vetor de incialização será zerado.

: Essa API suporta operações RSA feitas diretamente nesta função. Os dados para serem operados devem ter comprimento igual ao tamanho da chave. Quando utilizada a chave pública para criptografia o padding utilizado é PKCS#1 tipo 2 e no processo de decriptografia, o padding é verificado e retirado. Para operações com a chave privada, utiliza-se o padding PKCS#1 tipo 1. O HSM irá verificar a formatação do padding mesmo quando a operação não tem padding definido como em D_NO_RSA_PADDING.

Exemplos:: cryptsym.c.

int AAP_API DCreateHash	(	HSESSIONCTX	hSession,
		int	nAlgId,
		HKEYCTX	hKey,
		DWORD	dwFlags,
		HHASHCTX *	hHash
	)

#include <dinamo.h>

Inicializa um contexto de hash para ser usado com um fluxo de dados. Esse contexto é usado para chamadas subseqüentes DHashData(), DHashSessionKey(), entre outras.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

nAlgId

Define o algoritmo associado ao contexto de hash.

Valor	Significado
ALG_MD5	Algoritmo de hash MD5. hKey deve ser NULL.
ALG_SHA1	Algoritmo de hash SHA1. hKey deve ser NULL.
ALG_SSL_SHA1_MD5	Hash para autenticação de cliente em SSLv3. hKey deve ser NULL.
ALG_SHA2_256	Algoritmo de hash SHA2 - 256. hKey deve ser NULL.
ALG_SHA2_384	Algoritmo de hash SHA2 - 384. hKey deve ser NULL.
ALG_SHA2_512	Algoritmo de hash SHA2 - 512. hKey deve ser NULL.
ALG_HMAC_MD5	Algoritmo HMAC MD5. hKey deve ser o contexto para a chave utilizada no HMAC.
ALG_HMAC_SHA1	Algoritmo HMAC SHA1. hKey deve ser o contexto para a chave utilizada no HMAC.
ALG_HMAC_SHA2_256	Algoritmo HMAC SHA2 - 256. hKey deve ser o contexto para a chave utilizada no HMAC.
ALG_HMAC_SHA2_384	Algoritmo HMAC SHA2 - 384. hKey deve ser o contexto para a chave utilizada no HMAC.
ALG_HMAC_SHA2_512	Algoritmo HMAC SHA2 - 512. hKey deve ser o contexto para a chave utilizada no HMAC.
ALG_CMAC_DES	Algoritmo CMAC 3DES. hKey deve ser o contexto para a chave 3DES utilizada no CMAC.
ALG_CMAC_AES	Algoritmo CMAC AES. hKey deve ser o contexto para a chave AES utilizada no CMAC.

[in] hKey Deve ser passado de acordo com o tipo de algoritmo passado em nAlgId.

[in] dwFlags Reservado para uso futuro (deve ser 0).

[out] hHash Ponteiro para o contexto do hash gerado. Depois do seu uso deverá ser liberado com a função DDestroyHash().

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos:: hashcreate.c e signverify.c.

int AAP_API DHashData	(	HHASHCTX	hHash,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Adiciona dados à um determinado contexto de hash. Essa função pode ser chamada diversas vezes para adicionar dados discontinuos.

Parâmetros

[in]	hHash	Contexto de hash gerado pela função DCreateHash().
[in]	pbData	Buffer contendo os dados que serão adicionados ao contexto de hash.
[in]	dwDataLen	Número de bytes a ser adicionados.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos:: hashcreate.c e signverify.c.

int AAP_API DSetHashParam	(	HHASHCTX	hHash,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Altera um contexto de hash criado por DCreateHash().

Parâmetros

[in] hHash Contexto de hash gerado pela função DCreateHash().

[in]

dwParam

Define o parâmetro do contexto de hash a ser modificado.

Valor	Significado
DHP_HASH_VALUE	Tipo de `pbData:` BYTE * pbData deverá ser um ponteiro para um buffer contendo o valor do hash a ser associado ao contexto. Depois que for atribuído algum valor a este parâmetro, o valor do hash não poderá mais ser alterado e chamadas futuras de DHashData ou DHashSessionKey falharão retornando o código de erro D_INVALID_HASH_STATE.

[in] pbData Ponteiro para os dados ou estruturas especificados em dwParam.

[in] dwDataLen Tamanho dos dados ou estrutura especificados em dwParam.

[in] dwFlags Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

int AAP_API DGetHashParam	(	HHASHCTX	hHash,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Retorna atributos associados à um determinado contexto de hash. O valor do hash pode ser recuperado usando essa função.

Parâmetros

[in] hHash Contexto de hash gerado pela função DCreateHash().

[in]

dwParam

Define o parâmetro do contexto de hash a ser recuperado.

Valor	Significado
DHP_ALGID	Tipo de `pbData:` DWORD Recupera o algoritmo associado a esse contexto quando ele foi criado.
DHP_HASH_SIZE	Tipo de `pbData:` DWORD Recupera o comprimento do valor do hash.
DHP_HASH_VALUE	Tipo de `pbData:` BYTE * `pbData` será um ponteiro para um buffer contendo o valor do hash associado ao contexto. Depois que esse atributo for retornado, o valor do hash não poderá mais ser alterado e chamadas futuras de DHashData ou DHashSessionKey falharão retornando o código de erro D_INVALID_HASH_STATE.

[in] pbData Ponteiro para os dados ou estruturas especificados em dwParam. Esse parâmetro pode ser NULL para que seja especificada a quantidade de memória necessária.

[in,out] pdwDataLen Ponteiro para o tamanho do buffer, em bytes, especificado em pbData. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbData.

[in] dwFlags Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos:: hashcreate.c.

int AAP_API DSignHash	(	HHASHCTX	hHash,
		HKEYCTX	hKey,
		DWORD	dwFlags,
		BYTE *	pbSignature,
		DWORD *	pdwSigLen
	)

#include <dinamo.h>

Assina um dado a partir do seu contexto de hash criado com a função DCreateHash().

Parâmetros

[in] hHash Contexto de hash gerado pela função DCreateHash().

[in] hKey Contexto da chave privada a ser utilizada na assinatura.

[in]

dwFlags

Deve-se passar 0 ou algum modificador definido na lista abaixo.

Valor	Significado
NO_HASH_OID	Quando essa flag é especificada, o identificador do objeto (OID) não é colocado na frente do valor do hash, como previsto no PKCS#7, atributo DigestInfo. Por padrão, esse valor é sempre acrescentado à assinatura.

[out] pbSignature Buffer que receberá a assinatura. Esse parâmetro pode ser NULL para que seja especificada a quantidade de memória necessária.

[in,out] pdwSigLen Ponteiro para o tamanho da assinatura, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbSignature.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: O formato da assinatura gerado pela função DSignHash() está em conformidade com as especificações do PKCS#1 v.1.5, utilizando padding tipo 1 quando for usada uma chave RSA, com o uso de chaves ECC a assinatura estará no padrão DER.

Exemplos:: signverify.c.

int AAP_API DDestroyHash ( HHASHCTX * phHash )

#include <dinamo.h>

Libera o contexto de um hash depois do seu uso. Depois que este contexto foi liberado ele não pode ser mais usado por qualquer função, se tornando inválido.

Parâmetros

[in] phHash Contexto de hash gerado pela função DCreateHash().

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos:: hashcreate.c e signverify.c.

int AAP_API DVerifySignature	(	HHASHCTX	hHash,
		BYTE *	pbSignature,
		DWORD	dwSigLen,
		HKEYCTX	hPubKey,
		DWORD	dwFlags
	)

#include <dinamo.h>

Verifica a assinatura do hash associado à um contexto.

Parâmetros

[in] hHash Contexto de hash gerado pela função DCreateHash().

[in] pbSignature Buffer contendo o a assinatura a ser verificada.

[in] dwSigLen Número de bytes da assinatura.

[in] hPubKey Contexto para a chave pública utilizada na verificação da assinatura.

[in]

dwFlags

Modificadores do comportamento da função.

Valor	Significado
NO_HASH_OID	Quando essa flag é especificada, o identificador do objeto (OID) não é verificado, como previsto no PKCS#7, atributo DigestInfo. Por padrão, esse valor é sempre verificado.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: O formato da assinatura gerado pela função DSignHash() e verificado por DVerifySignature() está em conformidade com as especificações do PKCS#1 v.1.5, utilizando padding tipo 1 para chaves RSA. No caso de chaves ECC o padrão utilizado será DER.

Exemplos:: signverify.c.

int AAP_API DDuplicateHash	(	HHASHCTX	hHash,
		DWORD	dwFlag,
		HHASHCTX *	phHash
	)

#include <dinamo.h>

Duplica o contexto de um hash, incluindo o seu estado interno.

Parâmetros

[in]	hHash	Contexto de hash gerado pela função DCreateHash().
[in]	dwFlag	Reservado para uso futuro (deve ser 0).
[in]	phHash	Ponteiro para o contexto do hash gerado. Depois do seu uso deverá ser liberado com a função DDestroyHash().

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: Os contextos dos hashs são independentes, sendo assim, ao liberar o contexto original, o novo contexto continua a ser válido.

int AAP_API DGetRandom	(	HSESSIONCTX	hSession,
		BYTE *	pbData,
		DWORD	dwDataLen
	)

#include <dinamo.h>

Recupera um número determinado de bytes pseudo-aleatórios para uso criptográfico.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[out]	pbData	Buffer que será preenchido com os bytes pseudo-aleatórios.
[in]	dwDataLen	Tamanho em bytes de `pbData`.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

int AAP_API DGenEcdhKey	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		char *	szPriKey,
		void *	pvInData,
		DWORD	dwInDataLen,
		BYTE *	pbOutData,
		DWORD *	pdwOutDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Gera um segredo compartilhado(shared secret)/chave utilizando o protocolo de acordo de chaves (key-agreement) ECDH (Elliptc Curve Diffie-Hellman).

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwOP

Modificadores do comportamento da função.

Valor	Significado
DN_GEN_KEY_KDF_RAW_SECRET	Retorna em `pbOutData` a chave secreta ECDH sem derivação. Recomendamos derivar uma chave a partir desta, para comunicação com o par. O parâmetro passado em `pvInData` deve ser um ponteiro para um buffer contendo a chave pública do par no formato DER.
DN_GEN_KEY_X9_63_SHA256	Deriva uma chave secreta ECDH no padrão ANSI X9.63 utilizando SHA256. Deve ser passado `pvInData` a estrutura GEN_ECDH_X9_63. Ver documentação de GEN_ECDH_X9_63 para detalhes de preenchimento. Retorna opcionalmente em `pbOutData` a chave secreta gerada, ver GEN_ECDH_X9_63 para mais detalhes.

[in] szPriKey Identificador da chave privada dentro do HSM. Este identificador não deve conter espaços ou caracteres especiais. Caracteres maiúsculos e minúsculos são diferenciados ( case sensitive)

[in] pvInData Ponteiro para os dados de entrada da função. Deve ser preenchido de acordo com o descrito nas opções de dwOP

[in] dwInDataLen Tamanho em bytes de pvInData.

[out] pbOutData Buffer que receberá a chave/segredo de saída. Esse parâmetro pode ser NULL para que seja retornada a quantidade de memória necessária em pdwOutDataLen. Este parâmetro será ignorado quando a operação for de gravar a chave no HSM.

[in,out] pdwOutDataLen Ponteiro para o tamanho do buffer pbOutData, em bytes, que conterá a chave/segredo de saída. Quando a função retorna, esse parâmetro conterá o tamanho dos dados efetivamente armazenados em pbOutData. Este parâmetro será ignorado quando a operação for de gravar a chave no HSM.

[in] dwFlags Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos:: genecdh.c.

int AAP_API DCRLCertCheck	(	HSESSIONCTX	hSession,
		char *	szCRL,
		char *	szCertId,
		char *	szVerifyInfo
	)

#include <dinamo.h>

Valida um certificado X.509 no HSM utilizando uma LCR(Lista de Certificados Revogados) e uma cadeia de certificados.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szCRL	Nome da LCR(Lista de Certificados Revogados).
[in]	szCertId	Nome do certificado que será validado.
[in]	szVerifyInfo	Nome da cadeia de certificados/certificado para validação do certificado especificado em szCertId. Pode ser passado NULL para não fazer a verificação de cadeia de certificados.

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.