Gerência do ciclo de vida de chaves criptográficas no HSM. Mais...

Definições e Macros
#define	D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1)

#define	D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0)

Funções
int AAP_API	DGenerateKey (HSESSIONCTX hSession, char szKeyId, int nAlgId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DGenerateKeyMaterial (HSESSIONCTX hSession, int nAlgId, BYTE pbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DGetUserKey (HSESSIONCTX hSession, char szKeyId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DImportKey (HSESSIONCTX hSession, char szKeyId, HKEYCTX hKEKey, DWORD dwBlobType, int nAlgId, DWORD dwFlags, BYTE pbData, DWORD dwDataLen, HKEYCTX *phKey)

int AAP_API	DExportKey (HKEYCTX hKey, HKEYCTX hKEKey, DWORD dwBlobType, DWORD dwFlags, BYTE pbData, DWORD pdwDataLen)

int AAP_API	DPKCS8ImportKey (HSESSIONCTX hSession, char szKeyId, char szSecret, DWORD dwKeyAlg, DWORD dwAttrib, BYTE *pbKeyEnvelope, DWORD dwKeyEnvelopeLen)

int AAP_API	DPKCS8ExportKey (HSESSIONCTX hSession, char szKeyId, char szSecret, BYTE *ppbKeyEnvelope, DWORD pdwKeyEnvelopeLen)

int AAP_API	DSetKeyParam (HKEYCTX hKey, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetKeyParam (HKEYCTX hKey, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DDeriveKey (HHASHCTX hHash, char szKeyId, int nAlgId, DWORD dwFlags, HKEYCTX phKey)

int AAP_API	DDuplicateKey (HKEYCTX hKey, DWORD dwFlags, HKEYCTX *phKey)

int AAP_API	DHashSessionKey (HKEYCTX hKey, HHASHCTX hHash, DWORD dwFlags)

int AAP_API	DDestroyKey (HKEYCTX *phKey, DWORD dwFlags)

int AAP_API	DAssociatePKCS11Key (HSESSIONCTX hSession, char szPriKey, char szPubKey, char szCert, void pvReserved, DWORD dwReserved)

int AAP_API	DExportPKCS12 (const HSESSIONCTX hSession, const char szPkcs12Pwd, const char szKeyId, const char szCertId, const char szReserved, BYTE *ppbPkcs12, DWORD pdwPkcs12Len, DWORD dwReserved)

Descrição Detalhada

Gerência do ciclo de vida de chaves criptográficas no HSM.

Definições e macros

#define D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1)

#include <dinamo.h>

#define D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0)

#include <dinamo.h>

Funções

int AAP_API DGenerateKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int	nAlgId,
		DWORD	dwFlags,
		HKEYCTX *	phKey
	)

#include <dinamo.h>

Cria e armazena uma chave criptográfica associada a um algoritmo de acordo com os parâmetros informados, dentro do HSM.

Parâmetros

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

[in] szKeyId Identificador da chave 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). Um identificador de objeto no HSM pode ter tamanho máximo, em caracteres, de MAX_OBJ_ID (já incluído o caracter terminador). Quando está criando chaves na partição de outro usuário (é necessária permissão) o nome deve ser qualificado por inteiro com um FQN (Full Qualified Name: partition_id/obj_id), o tamanho máximo para um FQN é MAX_OBJ_ID_FQN_LEN (já incluído o caracter terminador).

[in]

nAlgId

Define o algoritmo associado à chave criptográfica a ser gerada.

Chaves Simétricas

Valor	Significado
ALG_DES	DES de 56 bits e com paridade impar.
ALG_3DES_112	3DES-EDE (Encrypt-Decrypt-Encrypt) de 112 bits e com paridade impar.
ALG_3DES_168	3DES-EDE (Encrypt-Decrypt-Encrypt) de 168 bits e com paridade impar.
ALG_DESX	DESX de 192 bits. O tamanho efetivo é de 118 bits.
ALG_ARC4	ARC4 com 128 bits.
ALG_AES_128	AES com 128 bits.
ALG_AES_192	AES com 192 bits.
ALG_AES_256	AES com 256 bits.

Chaves Assimétricas RSA

Valor	Significado
ALG_RSA_512	RSA com módulo de 512 bits.
ALG_RSA_1024	RSA com módulo de 1024 bits.
ALG_RSA_2048	RSA com módulo de 2048 bits.
ALG_RSA_4096	RSA com módulo de 4096 bits.
ALG_RSA_8192	RSA com módulo de 8192 bits.

Chaves Assimétricas ECC

Valor	Significado
ALG_ECC_SECP112R1	curva SECG/WTLS sobre um corpo finito primo de 112 bits (verifiably random elliptic curve domain parameters).
ALG_ECC_SECP112R2	curva SECG sobre um corpo finito primo de 112 bits (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP128R1	curva SECG sobre um corpo finito primo de 128 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP128R2	curva SECG sobre um corpo finito primo de 128 bits (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP160K1	curva SECG sobre um corpo finito primo de 160 bits (koblitz domain parameters ).
ALG_ECC_SECP160R1	curva SECG sobre um corpo finito primo de 160 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP160R2	curva SECG/WTLS sobre um corpo finito primo de 160 bits (verifiably random elliptic curve domain parameters 2).
ALG_ECC_SECP192K1	curva SECG sobre um corpo finito primo de 192 bits (koblitz domain parameters ).
ALG_ECC_SECP192R1	curva SECG/X9.62/NIST sobre um corpo finito primo de 192 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP224K1	curva SECG sobre um corpo finito primo de 224 bits (koblitz domain parameters ).
ALG_ECC_SECP224R1	curva SECG/NIST sobre um corpo finito primo de 224 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP256K1	curva SECG sobre um corpo finito primo de 256 bits (koblitz domain parameters ).
ALG_ECC_SECP256R1	curva SECG/X9.62 sobre um corpo finito primo de 256 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP384R1	curva SECG/NIST sobre um corpo finito primo de 384 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_SECP521R1	curva SECG/NIST sobre um corpo finito primo de 521 bits (verifiably random elliptic curve domain parameters 1).
ALG_ECC_X9_62_PRIME192V1	curva X9.62 sobre um corpo finito primo de 192 bits (version 1 domain parameters).
ALG_ECC_X9_62_PRIME192V2	curva X9.62 sobre um corpo finito primo de 192 bits (version 2 domain parameters).
ALG_ECC_X9_62_PRIME192V3	curva X9.62 sobre um corpo finito primo de 192 bits (version 3 domain parameters).
ALG_ECC_X9_62_PRIME239V1	curva X9.62 sobre um corpo finito primo de 239 bits (version 1 domain parameters).
ALG_ECC_X9_62_PRIME239V2	curva X9.62 sobre um corpo finito primo de 239 bits (version 2 domain parameters).
ALG_ECC_X9_62_PRIME239V3	curva X9.62 sobre um corpo finito primo de 239 bits (version 3 domain parameters).
ALG_ECC_X9_62_PRIME256V1	curva X9.62 sobre um corpo finito primo de 256 bits (version 1 domain parameters).
ALG_ECC_BRAINPOOL_P160R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 160 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P160T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 160 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P192R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 192 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P192T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 192 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P224R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 224 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P224T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 224 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P256R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 256 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P256T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 256 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P320R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 320 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P320T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 320 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P384R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 384 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P384T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 384 bits (twisted domain parameters 1)
ALG_ECC_BRAINPOOL_P512R1	curva Brainpool RFC 5639 sobre um corpo finito primo de 512 bits (verifiably random domain parameters 1)
ALG_ECC_BRAINPOOL_P512T1	curva Brainpool RFC 5639 sobre um corpo finito primo de 512 bits (twisted domain parameters 1)

Chaves HMAC

Valor	Significado
ALG_HMAC_MD5	Chave HMAC MD5 com tamanho de 16 bytes.
ALG_HMAC_SHA1	Chave HMAC SHA1 com tamanho de 20 bytes.
ALG_HMAC_SHA2_256	Chave HMAC SHA2 256 com tamanho de 32 bytes.
ALG_HMAC_SHA2_384	Chave HMAC SHA2 384 com tamanho de 48 bytes.
ALG_HMAC_SHA2_512	Chave HMAC SHA2 512 com tamanho de 64 bytes.

[in]

dwFlags

Parâmetros adicionais da chave.

Valor	Significado
EXPORTABLE_KEY	A chave poderá ser exportada do HSM.
TEMPORARY_KEY	A chave somente existirá enquanto a sessão estiver ativa. Ela será destruída após o encerramento da sessão. O parâmetro szKeyId, identificador da chave, deve ser NULL.

[in] phKey Ponteiro para o contexto da chave gerada. Depois do seu uso deverá ser liberado com a função DDestroyKey().

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

Atenção: No Dinamo todas as chaves são armazenadas cifradas, independe do modo de operação (FIPS ou non-FIPS).

Anotações

Aos contextos das chaves simétricas são atribuídos os seguintes valores padrões, quando se aplicarem:

Parâmetro	Valor
Vetor de Inicialização	Será um vetor com todos os bytes igual a zero e com o mesmo tamanho do bloco de operação do algoritmo da chave.
Modo de Operação de Criptografia Simétrica	Será usado o modo CBC (Cipher Block Chain)
Padding	Será usado o formato definido no padrão PKCS#5 como padding.

O tamanho do bloco de operação dos algoritmos segue a tabela abaixo:

Valor	Tamanho do bloco
ALG_DES	8 bytes
ALG_3DES_112	8 bytes
ALG_3DES_168	8 bytes
ALG_AES_128	16 bytes
ALG_AES_192	16 bytes
ALG_AES_256	16 bytes

As chaves RSA no HSM são criadas preferencialmente com expoente público de valor fixo e definido (três bytes na sequência 01 00 01, valor decimal de 216 + 1 = 65537). Opcionalmente pode ser usado um expoente de valor 3 por questão de compatibilidade com sistemas antigos, mas não é recomendado.

As chaves ECC são definidas conforme os padrões:

Standards for Efficient Cryptography Group (SECG)
Wireless Transport Layer Security (WTLS)
ANSI X9.62:2005 - Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA)
NIST FIPS PUB 186-4 - Digital Signature Standard (DSS)
RFC 5639 - Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation

Exemplos:: cryptsym.c, genecdh.c, keyaddremove.c e signverify.c.

int AAP_API DGenerateKeyMaterial	(	HSESSIONCTX	hSession,
		int	nAlgId,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved
	)

#include <dinamo.h>

Gera uma chave criptográfica e retorna o seu material. Esta operação gera uma chave utilizando o HSM e retorna o conteúdo da chave sem persistir a chave no HSM.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	nAlgId	Define o algoritmo da chave criptográfica a ser gerada. Esta operação suporta apenas algoritmos de chaves simétricas. Veja lista de algoritmos em DGenerateKey().
[in]	pbData	Buffer que conterá a chave gerada. Pode ser passado NULL para receber o tamanho esperado de pbData em pdwDataLen.
[in,out]	pdwDataLen	Ponteiro contendo o tamanho do buffer pbData. Esta variável conterá o tamanho exato dos dados copiados em pbData. Caso pbData seja NULL ou o tamanho informado não seja suficiente para completar a operação, pdwDataLen conterá o tamanho esperado de pbData.
[in]	dwReserved	Reservado para uso futuro.

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

int AAP_API DGetUserKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		DWORD	dwFlags,
		HKEYCTX *	phKey
	)

#include <dinamo.h>

Recupera o contexto de uma chave, desde que o usuário corrente tenha acesso, armazenada dentro do HSM. Essa função não cria uma nova chave.

Parâmetros

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

[in] szKeyId Identificador da chave 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). Veja szKeyId em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.

[in]

dwFlags

Passar zero. Caso contrário a seguinte tabela é aceita.

Valor

Significado

D_GET_USR_KEY_OFFLINE

Gerará um handle de chave baseado em parâmetros específicos e não irá ao HSM para verificar os parâmetros informados. Para usar esta flag uma estrutura GET_USR_KEY_OFFLINE devidamente preenchida deverá ser passada em szKeyId. Notar que não são feitas verificações de correlação dos dados informados. Passar dados inválidos gerará um handle inválido, mesmo se esta função retornar sucesso.

[out] phKey Ponteiro para o contexto da chave gerada. Depois do seu uso deverá ser liberado com a função DDestroyKey().

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

Veja também: DGenerateKey().

Exemplos:: keyattribute.c.

int AAP_API DImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		HKEYCTX	hKEKey,
		DWORD	dwBlobType,
		int	nAlgId,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD	dwDataLen,
		HKEYCTX *	phKey
	)

#include <dinamo.h>

Importa uma chave criptográfica para dentro do HSM. As chaves podem ser permanentes ou temporárias. As chaves exportadas com a função DExportKey() podem ser importadas sem alteração de formato.

Parâmetros

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

[in] szKeyId Identificador da chave 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). Veja szKeyId em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.

[in] hKEKey Contexto da chave com a qual o blob da chave a ser importada está cifrada - KEK (key encryption key)

[in]

dwBlobType

Formato do buffer da chave no parâmetro pbData.

Valor	Significado
PRIVATEKEY_BLOB	Será importado um par de chaves RSA no formato PRIVATEKEY_BLOB. hKEKey deve ser o contexto de uma chave de simétrica, uma chave pública ou ainda NULL. O formato do blob da chave pode ser uma concatenação dos formatos de chave pública e chave privada definidos no PKCS#1 v1.5, nas seções 7.1 e 7.2, ou pode ser também apenas o formato definido para a chave privada (que contém as informações de módulo e expoente público), definido na PKCS#1 v1.5 seção 7.2.
PRIVATEKEY_BLOB_P8	Será importado um par de chaves RSA no formato PRIVATEKEY_BLOB_P8. hKEKey deve ser o contexto de uma chave de simétrica. O formato do blob da chave é o PrivateKeyInfo definido no PKCS#8.
PUBLICKEY_BLOB	Será importada uma chave pública de um par de chaves RSA no formato PUBLICKEY_BLOB.hKEKey deve ser igual a NULL. O contexto retornado pela importação de chave pública deve ser utilizado apenas nas operações de envelope digital, pois o HSM não cria de forma persistente objetos RSA com apenas a parte pública da chave.Para importação de chave pública ECC o formato utilizado será DER.
SIMPLE_BLOB	Será importada uma chave simétrica no formato SIMPLE_BLOB.hKEKey deve ser o contexto de uma chave privada associada à chave pública usada para criptografar o blob a ser importado.O tipo do padding usado para criptografia da chave deve ser 2, como definido no PKCS#1 v1.5 seção 8.1.
PLAINTEXTKEY_BLOB	Será importada uma chave simétrica ou HMAC em claro.Essa flag ainda não é suportada para chaves RSA.
SIMPLE_BLOB_OAEP	Define a importação através de envelope digital usando o padrão PKCS#1 versão 2.1, com esquema de cifragem RSAES-OAEP. A KEK deverá ser uma chave privada no HSM, cuja chave pública correspondente foi utilizada na criação do envelope. O contexto para esta KEK pode ser obtido via uma chamada à DGetUserKey, onde será informado o id da chave RSA do HSM usada para abrir o envelope.Este método de importação pode ser utilizado no modo de operação FIPS.
SYM_WRAPPED_KEY_BLOB	Define uma chave simétrica encriptada por uma KEK (Key Encryption Key) também simétrica.O parâmetro hKEKey deverá conter o contexto de uma chave simétrica com os devidos parâmetros de utilização já definidos, como modo e padding.A chave será decriptada e importada para a base do HSM diretamente, sem formatação específica.
HOTP_BLOB	Define a importação de um objeto tipo HTOP para a partição do usuário.
PUBLICKEY_BLOB_HSM	Será importada uma chave pública de um par de chaves RSA/ECC no formato DER para dentro do HSM. hKEKey deve ser igual a NULL.
PUBLICKEY_RSA_PARTS_HSM	Será importada uma chave pública, a partir do módulo e do expoente público, para dentro do HSM. hKEKey deve ser igual a NULL. Deve ser passado em pbData a estrutura RSA_PUB_KEY_PARTS devidamente preenchida.

[in] nAlgId Indica o algoritmo associado à chave criptográfica que será gerada. Veja lista de algoritmos em DGenerateKey(). Utilizar D_IMPORT_ALG_PRIV_KEY_RSA quando a chave privada importada for RSA e encriptada por KEK, o algoritmo específico será detectado automáticamente pelo HSM após abertura do BLOB encriptado.

[in] dwFlags Parâmetros adicionais da chave. Veja as opções na função DGenerateKey().

[in] pbData Buffer contendo a chave a ser importada.

[in] dwDataLen Tamanho do bloco de dados com a chave a ser importada.

[out] phKey Ponteiro para o contexto da chave gerada. Depois do seu uso deverá ser liberado com a função DDestroyKey.

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

Anotações: Para chaves de sessão e chaves públicas é recomendável que a flag TEMPORARY_KEY seja usada, evitando que chaves de uso temporário ocupem espaço desnecessário no HSM.

Formato do SIMPLE_BLOB:

EB = 00 || BT || PS || 00 || D

Estruturas DER de PRIVATEKEY_BLOB:

 RSAPublicKey ::= SEQUENCE {
     modulus INTEGER, -- n
     publicExponent INTEGER -- e
 }
                 +
 RSAPrivateKey ::= SEQUENCE {
     version Version,
     modulus INTEGER, -- n
     publicExponent INTEGER, -- e
     privateExponent INTEGER, -- d
     prime1 INTEGER, -- p
     prime2 INTEGER, -- q
     exponent1 INTEGER, -- d mod (p-1)
     exponent2 INTEGER, -- d mod (q-1)
     coefficient INTEGER -- (inverse of q) mod p
 }

ou

 RSAPrivateKey ::= SEQUENCE {
     version Version,
     modulus INTEGER, -- n
     publicExponent INTEGER, -- e
     privateExponent INTEGER, -- d
     prime1 INTEGER, -- p
     prime2 INTEGER, -- q
     exponent1 INTEGER, -- d mod (p-1)
     exponent2 INTEGER, -- d mod (q-1)
     coefficient INTEGER -- (inverse of q) mod p
 }

Estrutura DER de PRIVATEKEY_BLOB:

 RSAPublicKey ::= SEQUENCE {
     modulus INTEGER, -- n
     publicExponent INTEGER -- e
 }

Veja também: Observações de DGenerateKey().

Exemplos:: eftvalidatecvv.c.

int AAP_API DExportKey	(	HKEYCTX	hKey,
		HKEYCTX	hKEKey,
		DWORD	dwBlobType,
		DWORD	dwFlags,
		BYTE *	pbData,
		DWORD *	pdwDataLen
	)

#include <dinamo.h>

Exporta uma chave armazenada no HSM para que possa ser transportada. A chave poderá ser novamente importada para o Dinamo com a função DImportKey().

Parâmetros

[in]	hKey	Contexto da chave a ser exportada.
[in]	hKEKey	Contexto da chave com a qual o bloco da chave será cifrado - KEK (key encryption key).
[in]	dwBlobType	Formato do buffer da chave no parâmetro `pbData`. Veja parâmetro `dwBlobType` em DImportKey() para lista de tipos.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).
[in]	pbData	Buffer contendo os dados da chave conforme o parâmetro dwBlobType. 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`.

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

Anotações: Apenas chaves criadas como exportáveis podem ser extraídas com esta função, caso contrário o código de erro D_INVALID_KEY_STATE será retornado.

Exemplos:: genecdh.c.

int AAP_API DPKCS8ImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szSecret,
		DWORD	dwKeyAlg,
		DWORD	dwAttrib,
		BYTE *	pbKeyEnvelope,
		DWORD	dwKeyEnvelopeLen
	)

#include <dinamo.h>

Importa para o HSM uma chave assimétrica privada RSA envelopada segundo o padrão PKCS#8. A chave privada RSA pode ser importada em texto claro ou protegida por envelope digital. Para detalhes sobre os padrões, consulte os documentos Public-Key Cryptography Standards (PKCS) da RSA Labs. No modo de operação FIPS as chaves RSA só podem ser importadas via o padrão PKCS#8 com uso de envelope digital, derivando uma chave AES 256 a partir de uma senha de no mínimo 01 caracter e no máximo 16, sendo a derivação feita conforme o padrão PKCS#5 versão 2.0.
O envelope utilizado poderá ser proveniente de qualquer sistema aderente aos padrões descritos.

Parâmetros

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

[in] szKeyId Indentificador para a chave RSA que será criada na base do HSM. Veja szKeyId em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.

[in] szSecret Senha utilizada para derivar a chave AES 256. Pode ser passado NULL para não utilizar senha (importação em texto claro) ou uma senha de no máximo 16 caracteres.

[in]

dwKeyAlg

Indica o algoritmo associado à chave criptográfica a ser gerada.

Valor	Significado
ALG_RSA_512	Par de chaves RSA com módulo de 512 bits.
ALG_RSA_1024	Par de chaves RSA com módulo de 1024 bits.
ALG_RSA_1152	Par de chaves RSA com módulo de 1152 bits.
ALG_RSA_1408	Par de chaves RSA com módulo de 1408 bits.
ALG_RSA_1984	Par de chaves RSA com módulo de 1984 bits.
ALG_RSA_2048	Par de chaves RSA com módulo de 2048 bits.
ALG_RSA_4096	Par de chaves RSA com módulo de 4096 bits.

[in]

dwAttrib

Parâmetros adicionais da chave.

Valor	Significado
EXPORTABLE_KEY	A chave poderá ser exportada em claro do HSM.

[in] pbKeyEnvelope Buffer que contém o envelope PKCS#8 de entrada.

[in] dwKeyEnvelopeLen Tamanho em bytes do envelope PKCS#8 de entrada.

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

int AAP_API DPKCS8ExportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szSecret,
		BYTE **	ppbKeyEnvelope,
		DWORD *	pdwKeyEnvelopeLen
	)

#include <dinamo.h>

Exporta uma chave assimétrica privada RSA armazenada no HSM segundo o padrão PKCS#8. A chave privada RSA pode ser exportada em texto claro ou protegida por envelope digital. Para detalhes sobre os padrões, consulte os documentos Public-Key Cryptography Standards (PKCS) da RSA Labs. No modo de operação FIPS as chaves RSA exportáveis só podem ser exportadas via o padrão PKCS#8 com uso de envelope digital, derivando uma chave AES 256 a partir de uma senha com tamanho entre ND_MIN_P8_PWD_LEN e ND_MAX_P8_PWD_LEN caracteres, sendo a derivação feita conforme o padrão PKCS#5 versão 2.0. O envelope de saída poderá ser importado em qualquer sistema aderente aos padrões descritos.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Indentificador da chave RSA a ser exportada. Veja `szKeyId` em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.
[in]	szSecret	Senha com tamanho entre ND_MIN_P8_PWD_LEN e ND_MAX_P8_PWD_LEN, utilizada para derivar a chave AES 256. Pode ser passado NULL para exportar em texto claro, sem senha.
[out]	ppbKeyEnvelope	Ponteiro de ponteiro que irá conter o envelope PKCS#8 de saída. A alocação de memória é feita internamente pela biblioteca. A aplicação chamadora é responsável por liberar a memória alocada. Deve ser utilizada a função DFree() para liberar este buffer.
[out]	pdwKeyEnvelopeLen	Ponteiro para DWORD que conterá o tamanho em bytes do envelope PKCS#8 de saída.

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

int AAP_API DSetKeyParam	(	HKEYCTX	hKey,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Altera parâmetros dos contextos de chaves que, em geral, vão influenciar na sua manipulação.

Parâmetros

[in] hKey Contexto da chave a ser exportada.

[in]

dwParam

Define a operação que será executada e por conseqüência a estrutura ou dados passados no parâmetro pbData.

Valor	significado
DKP_IV	Tipo de `pbData:` BYTE * Vetor de inicialização usado com algoritmos de bloco de acordo com o seu modo de operação de criptografia simétrica. O tamanho do vetor de inicialização depende do algoritmo simétrico utilizado, já que tem o mesmo comprimento do bloco de operação. Mais detalhes na sessão Observações. Válido apenas para chaves simétricas.
DKP_PADDING	Tipo de `pbData:` DWORD A biblioteca pode trabalhar com 3 formas de padding: D_NO_PADDING: Não é feito padding, os dados passados para criptografia já deve ter comprimento múltiplo do tamanho do bloco de operação. D_PKCS5_PADDING: O padding é feito seguindo o padrão definido no PKCS#5. D_ZERO_PADDING: Caso o comprimento dos dados não seja múltiplo do tamanho do bloco de operação, ele é completado com zeros a direita até que tenha um tamanho suportado pelo algoritmo. Este tipo de padding não deve ser usado com dados onde pode haver bytes com valor zero, pois pode gerar ambigüidade na operação de decriptografia. Caso os dados contenham apenas texto ASCII, por exemplo, não há problema. Válido apenas para chaves simétricas.
DKP_MODE	Tipo de `pbData:` DWORD Indica o modo de operação de criptografia do algoritmo de bloco. MODE_ECB: Eletronic Codebook (ECB) MODE_CBC: Cipher Block Chain (CBC) MODE_CFB: Cipher-Feedback. Ainda não suportada. MODE_OFB: Output-Feedback. Ainda não suportada. Válido apenas para chaves simétricas e algoritmos de bloco.
DKP_OWNER	Tipo de `pbData:` char * Atribui a um usuário o privilégio de dono da chave. `pbData` é um ponteiro para uma string com o identificador de um usuário do HSM. Ainda não suportada.
DKP_USER	Tipo de `pbData:` char * Atribui a um usuário o privilégio de usuário da chave. `pbData` é um ponteiro para uma string com o identificador de um usuário do HSM. Ainda não suportada.
DKP_READ_LOCK	Tipo de `pbData:` NULL Marca a chave como não exportável. Ainda não suportada.

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

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

[in] dwFlags REMOVE_ATTRIBUTE pode ser usado para remover privilégio de um usuário sobre uma chave. Essa flag só deve ser usada em conjunto com DKP_OWNER ou DKP_USER.

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

int AAP_API DGetKeyParam	(	HKEYCTX	hKey,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags
	)

#include <dinamo.h>

Recupera parâmetros dos contextos de chave.

Parâmetros

[in] hKey Contexto da chave a ser exportada

[in]

dwParam

Define a operação que será executada e por conseqüência a estrutura ou dados passados no parâmetro pbData. Todos os valores descritos em DSetKeyParam() e mais:

Valor	significado
DKP_ALGID	Tipo de `pbData:` DWORD Recupera o algoritmo criptográfico associado à chave. A lista de valores possíveis é a mesma definida para o parâmetro nAlgId na função DGenerateKey (ver pág. 36). Caso o objeto não seja uma chave criptográfica o valor retornado é ALG_OBJ.
DKP_KEYLEN	Tipo de `pbData:` DWORD Recupera o tamanho da chave em bytes.
DKP_ENCRYPTED	Tipo de `pbData:` BOOL Retorna o estado da chave dentro do HSM. Se verdadeiro a chave estará armazenada cifrada dentro do HSM, se falso a chave estará gravada em claro.
DKP_KEY_INFO	Tipo de `pbData:` GET_USR_KEY_OFFLINE Retorna as informações básicas da chave.

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

[in] pdwDataLen 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.

Veja também: DGenerateKey().

Exemplos:: keyattribute.c.

int AAP_API DDeriveKey	(	HHASHCTX	hHash,
		char *	szKeyId,
		int	nAlgId,
		DWORD	dwFlags,
		HKEYCTX *	phKey
	)

#include <dinamo.h>

Deriva uma chave a partir do hash informado. Se o hash ainda não estiver completo, ele será finalizado e seu valor utilizado como uma chave simétrica.

Parâmetros

[in]	hHash	Contexto de hash criado com DCreateHash.
[in]	szKeyId	Identificador da chave 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). Veja `szKeyId` em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.
[in]	nAlgId	Indica o algoritmo associado à chave criptográfica que será gerada. Veja lista de algoritmos em DGenerateKey().
[in]	dwFlags	Parâmetros adicionais da chave. Veja lista de parâmetros adicionais da chave em DGenerateKey().
[in]	phKey	Ponteiro para o contexto da chave gerada. Depois do seu uso deverá ser liberado com a função DDestroyKey().

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

int AAP_API DDuplicateKey	(	HKEYCTX	hKey,
		DWORD	dwFlags,
		HKEYCTX *	phKey
	)

#include <dinamo.h>

Duplica o contexto de uma chave, incluindo o seu estado interno.

Parâmetros

[in]	hKey	Contexto de chave.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).
[out]	phKey	Ponteiro para o contexto da chave gerada. Depois do seu uso deverá ser liberado com a função DDestroyKey().

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 das chaves são independentes, sendo assim, ao liberar o contexto original, o novo contexto continua a ser válido.

int AAP_API DHashSessionKey	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		DWORD	dwFlags
	)

#include <dinamo.h>

Usa o valor de uma chave simétrica como dados de entrada para a execução de um hash. O contexto de hash deve ter um contexto limpo para que possa ser usado nessa função, ou seja, não pode ter sido usado com a função DHashData().

Parâmetros

[in]	hKey	Contexto de chave.
[in]	hHash	Contexto de hash criado com DCreateHash().
[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.

Anotações: A chave tem que estar marcada como exportável para que essa operação possa ser realizada.

int AAP_API DDestroyKey	(	HKEYCTX *	phKey,
		DWORD	dwFlags
	)

#include <dinamo.h>

Libera o contexto de uma chave 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] phKey Ponteiro para um contexto de chave que será liberado.

[in]

dwFlags

Modificadores da operação.

Valor	Significado
REMOVE_FROM_HSM	Além de liberar o contexto apontado por `phKey`, remove a chave fisicamente da base do HSM. Esse parâmetro deve ser usado apenas quando se tem certeza que a chave não será mais necessária.

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

Exemplos:: cryptsym.c, eftvalidatecvv.c, genecdh.c, keyaddremove.c, keyattribute.c e signverify.c.

int AAP_API DAssociatePKCS11Key	(	HSESSIONCTX	hSession,
		char *	szPriKey,
		char *	szPubKey,
		char *	szCert,
		void *	pvReserved,
		DWORD	dwReserved
	)

#include <dinamo.h>

Associa uma chave privada a um certificado e opcionalmente uma chave pública seguindo dentro das especificações PKCS#11 Base v2.40 seção 4.6.3 e o utilizado pelo Firefox.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession()..
[in]	szPriKey	Nome da chave privada que será associada.
[in]	szPubKey	Nome da chave pública que será associada. Pode passar NULL para não gerar a chave pública associada. Deve ser relacionado a chave privada.
[in]	szCert	Nome do certificado que será exportado. Deve ser relacionado a chave privada.
[in]	pvReserved	Reservado para uso futuro. Deve ser NULL.
[in]	dwReserved	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.

Anotações

A associação padrão é baseada na utilizada pelo Firefox que altera os metadados dos objetos de acordo com a tabela abaixo.

Atributo	Valor
CKA_ID	SHA1 do módulo da chave pública. Definido para Chave privada, chave pública e certificado.
CKA_LABEL	Id do certificado. Definido para chave privada e certificado.
CKA_SUBJECT	Subject recuperado do certificado. Definido para chave privada e certificado.

Veja também: DImportPKCS12().

int AAP_API DExportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szReserved,
		BYTE **	ppbPkcs12,
		DWORD *	pdwPkcs12Len,
		DWORD	dwReserved
	)

#include <dinamo.h>

Exporta uma chave privada e um certificado RSA no formato PKCS#12.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession()..
[in]	szPkcs12Pwd	Senha do arquivo PKCS#12. Passar NULL para gerar PKCS#12 sem senha.
[in]	szKeyId	Nome da chave privada que será exportada. Veja `szKeyId` em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.
[in]	szCertId	Nome do certificado que será exportado. Deve ser relacionado a chave privada.
[in]	szReserved	Reservado para uso futuro. Deve ser NULL.
[out]	ppbPkcs12	Ponteiro para um ponteiro que conterá o PKCS#12 gerado. Esta área de dados será alocada internamente e deve ser liberada utilizando DFree().
[out]	pdwPkcs12Len	Ponteiro para o tamanho dos dados escritos em `ppbPkcs12`.
[in]	dwReserved	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.

Anotações: A exportação PKCS#12 utiliza RC2 para criptografia do certificado, TripleDES(CBC) para criptografia de chave e SHA1 como hash padrão.

Veja também: DImportPKCS12().

Definições e Macros

Funções

Descrição Detalhada

Definições e macros

Funções