Descrição detalhada

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

Estruturas de Dados
struct	DN_EXPORT_BYOK_AZURE

Definições e Macros
#define	D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Importa uma chave privada RSA. */

#define	D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Importa uma chave privada ECC(Curvas Elípticas com exceção de ECX). */

#define	D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFFFDF) /* Importa uma chave no formato P8 */

#define	D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFFFDE) /* Import uma chave privada ECX */

#define	DN_FORM_DER (1)

#define	DN_BYOK_TYPE_AZURE (1)

#define	DN_BYOK_TYPE_AWS (2)

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	DGeneratePKCS10CSR (HSESSIONCTX hSession, char szPrivateKeyName, BYTE bVersion, char szDN, DWORD dwOutType, DWORD pdwCSRLen, BYTE *ppbCSR, DWORD dwParam)

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 dwFlags)

int AAP_API	DImportPKCS12Buffer (const HSESSIONCTX hSession, BYTE pbPkcs12, DWORD dwPkcs12Len, const char szPkcs12Pwd, const char szKeyId, DWORD dwKeyAttr, const char szCertId, const char *szPubKeyId, DWORD dwFlags)

int AAP_API	DImportPKCS12 (const HSESSIONCTX hSession, const char szPkcs12File, const char szPkcs12Pwd, const char szKeyId, const DWORD dwKeyAttr, const char szCertId)

int AAP_API	DRSAPublicKey2Info (BYTE pbKey, DWORD dwKeyLen, DWORD dwInForm, void pvPubKeyInfo, DWORD dwReserved)

int AAP_API	DRSAPrivateKey2Info (const BYTE pbRsa, DWORD dwRsaLen, DWORD dwInForm, DN_RSA_PRIVATE_KEY_INFO stRsaInfo, DWORD dwReserved)

int AAP_API	DByokExport (HSESSIONCTX hSession, const char cszKeyId, const char cszKekId, DWORD dwType, const void pvData, BYTE ppbOutData, DWORD pdwOutDataLen, DWORD dwReserved)

Definições e macros

◆ D_IMPORT_ALG_PRIV_KEY_RSA

#define D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Importa uma chave privada RSA. */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECC

#define D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Importa uma chave privada ECC(Curvas Elípticas com exceção de ECX). */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_P8

#define D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFFFDF) /* Importa uma chave no formato P8 */

#include <dinamo.h>

◆ D_IMPORT_ALG_PRIV_KEY_ECX

#define D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFFFDE) /* Import uma chave privada ECX */

#include <dinamo.h>

◆ DN_FORM_DER

#define DN_FORM_DER (1)

#include <dinamo.h>

Formato DER.

◆ DN_BYOK_TYPE_AZURE

#define DN_BYOK_TYPE_AZURE (1)

#include <dinamo.h>

Exporta chave BYOK para Azure.

◆ DN_BYOK_TYPE_AWS

#define DN_BYOK_TYPE_AWS (2)

#include <dinamo.h>

Exporta chave BYOK para AWS.

Funções

◆ DGenerateKey()

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_ARC5	ARC5 com 128 bits, bloco de 8 bytes e utilizando 16 rounds.
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	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_2048	Par de chaves RSA com módulo de 2048 bits.
ALG_RSA_4096	Par de chaves RSA com módulo de 4096 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_1536	Par de chaves RSA com módulo de 1536 bits.
ALG_RSA_1976	Par de chaves RSA com módulo de 1976 bits.
ALG_RSA_1984	Par de chaves RSA com módulo de 1984 bits.
ALG_RSA_8192	Par de chaves RSA com módulo de 8192 bits.
ALG_RSA_2304	Par de chaves RSA com módulo de 2304 bits.
ALG_RSA_2560	Par de chaves RSA com módulo de 2560 bits.
ALG_RSA_2816	Par de chaves RSA com módulo de 2816 bits.
ALG_RSA_3072	Par de chaves RSA com módulo de 3072 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 Assimétricas ECX

Valor	Significado
ALG_ECX_ED25519	curva RFC 8032(apenas assinatura) sobre um corpo finito primo de ~256 bits.
ALG_ECX_ED448	curva RFC 8032(apenas assinatura) sobre um corpo finito primo de ~448 bits.
ALG_ECX_X25519	curva RFC 7748(apenas key-agreement) sobre um corpo finito primo de ~256 bits.
ALG_ECX_X448	curva RFC 7748(apenas key-agreement) sobre um corpo finito primo de ~448 bits.

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.

Além dos valores da tabela anterior é possível adicionar uma definição de perfil de uso de chave.
É possível definir o perfil de uso da chave (Attribute Usage-profile), utilizando apenas um dos valores abaixo. Se nenhum dos valores abaixo for especificado o perfil da chave é definido como livre para qualquer uso. É obrigatório a definição do perfil de uso quando o HSM estiver em modo RM3.

Valor	Significado
AUP_DIG_SIG	assinatura geração/verificação
AUP_DATA_CRYPTO	encriptação/decriptação de dados
AUP_KeK	wrapping/unwrapping de chaves
AUP_MAC	geração/verificação MAC
AUP_KDF	função de derivação de chave
AUP_CRYPTOGRAM	geração/verificação de criptograma
AUP_KEY_TRANSLATE	tradução de chave
AUP_EFT_CVK	geração/verificação de CVV
AUP_EFT_VISA_PVK	geração de PVV
AUP_EFT_IBM_3624	geração/validação de PIN
AUP_EFT_PEK	encriptação/decriptação de PIN
AUP_EFT_BDK	DUKPT
AUP_EFT_IPEK	DUKPT IPEK
AUP_EMV_IMK	derivação de ICC MK, IDN
AUP_EMV_IMKDAC	derivação de ICC DAC
AUP_EMV_IMKENC	encriptação de dados ICC - PinBlock
AUP_EMV_IMKMAC	criptograma de dados ICC - EmvMac
AUP_EMV_KeK	wrapping de ICC MK
AUP_EMV_IMKKDF	derivação de chave EMV
AUP_EMV_IMKACRYPTO	cálculo ARPC
AUP_EFT_KeK	wrapping/unwrapping de chave EFT
AUP_EMV_DIG_SIG	assinatura EMV geração/verificação
AUP_EFT_TR31_KBPK	chave de proteção de key-block TR31
AUP_EFT_TR34_PK	assinatura/envelope TR34
AUP_SPB_PK	SPB assinatura geração/verificação e wrapping de chave

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

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, independente do modo de operação (NRM, RM1 ou RM2).

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
ALG_ARC5	8 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: crypt_sym.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, key_add_remove.c, key_attribute.c, pin_block_translate.c, sign_verify.c, sign_verify_eddsa.c e tokenization.c.

◆ DGenerateKeyMaterial()

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.

◆ DGetUserKey()

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.

D_GET_USR_KEY_NO_PUB Caso recupere uma chave pública, não tentará exportar o seu conteúdo para recuperar mais detalhes. As informações da chave serão parciais. Esta opção é utilizada apenas em casos específicos de uso de M de N de partição no estado de associado, autorizado, onde não é permitido a exportação da chave pública.

[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: key_attribute.c.

◆ DImportKey()

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_STRICT	Será importado um par de chaves RSA ou EC no formato PRIVATEKEY_BLOB. hKEKey deve ser o contexto de uma chave simétrica, uma chave pública(interna ao HSM ver PUBLICKEY_BLOB_HSM) ou ainda NULL. Os seguintes formatos são aceitos. Para RSA: 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. Para chaves ECC devem ter o formato ECPrivateKey descrito na RFC 5915. Para chaves ECX(EdDSA e XECDH) o formato é o descrito na RFC 8410.
PRIVATEKEY_BLOB	Mesmo comportamento de PRIVATEKEY_BLOB_STRICT mas em versões antigas de HSM pode retornar chaves RSA como uma concatenação de chave privada e chave pública nos formatos definidos no PKCS#1 v1.5, nas seções 7.1 e 7.2. Esta opção é mantida por compatibilidade. Utilizar PRIVATEKEY_BLOB_STRICT.
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 ou EC 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 seguindo o padrão PKCS#1 v2.2 formato DER.Para chaves públicas EC (ECC e ECX) o padrão é o SubjectPublicKeyInfo formato 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 com hash SHA-1. 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 nos modos de operação restritos.
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.
WRAPPED_KEY_BLOB	Importa uma chave encriptada por uma KEK (Key Encryption Key).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(de acordo com o algoritmo) e padding. A chave será decriptada e importada para a base do HSM diretamente, sem formatação específica.
WRAPPED_KEY_BLOB_P8	Importa uma chave encriptada por uma KEK (Key Encryption Key).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(de acordo com o algoritmo) e padding. A chave será decriptada e importada para a base do HSM diretamente, sem formatação específica. Na operação de exportação de chave o formato da chave privada será PKCS#8.

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

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
}

  ECPrivateKey ::= SEQUENCE {
  version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
  privateKey     OCTET STRING,
  parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
  publicKey  [1] BIT STRING OPTIONAL
}

Estrutura DER de PUBLICKEY_BLOB:

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

Estrutura DER de PUBLICKEY_BLOB_X509:

SubjectPublicKeyInfo ::= SEQUENCE {
                     algorithm AlgorithmIdentifier,
                     publicKey BIT STRING }

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

Exemplos: eft_validate_cvv.c, import_export.c, pin_block_translate.c e verify_pin_block.c.

◆ DExportKey()

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: gen_ecdh.c, gen_xecdh.c e import_export.c.

◆ DPKCS8ImportKey()

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. Nos modos de operação restritos (RM1 e RM2) 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 ND_MAX_P8_PWD_LEN caracteres mais terminador nulo.

[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_2048	Par de chaves RSA com módulo de 2048 bits.
ALG_RSA_4096	Par de chaves RSA com módulo de 4096 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_1536	Par de chaves RSA com módulo de 1536 bits.
ALG_RSA_1976	Par de chaves RSA com módulo de 1976 bits.
ALG_RSA_1984	Par de chaves RSA com módulo de 1984 bits.
ALG_RSA_8192	Par de chaves RSA com módulo de 8192 bits.
ALG_RSA_2304	Par de chaves RSA com módulo de 2304 bits.
ALG_RSA_2560	Par de chaves RSA com módulo de 2560 bits.
ALG_RSA_2816	Par de chaves RSA com módulo de 2816 bits.
ALG_RSA_3072	Par de chaves RSA com módulo de 3072 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.

◆ DPKCS8ExportKey()

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. Nos modos de operação restritos (RM1 e RM2) 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 mais terminaor nulo, 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.

◆ DSetKeyParam()

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 os seguintes paddings simétricos: D_NO_PADDING: Não é feito padding, os dados passados para criptografia já devem 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. É o padding padrão, caso nenhum seja definido. 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. A biblioteca pode trabalhar com os seguintes paddings assimétricos: D_PKCS1_PADDING: O padding é feito seguindo o padrão definido no PKCS#1 v1.5. É o padding padrão para chaves RSA, caso nenhum seja definido. D_PSS_PADDING: O padding é feito seguindo o padrão PSS definido no PKCS#1 EMSA-PSS-ENCODE com o hash igual ao usado no hash da mensagem, usando o salt com o tamanho máximo disponível no bloco. Opção não disponível para assinaturas legadas. D_PSS_SALT_LEN_MD_PADDING: O padding é feito seguindo o padrão PSS definido no PKCS#1 EMSA-PSS-ENCODE com o hash igual ao usado no hash da mensagem, usando o salt com o mesmo tamanho da saída do hash utilizado na operação. Opção não disponível para assinaturas legadas. D_OAEP_SHA1_PADDING: O padding é feito seguindo o padrão PKCS#1 versão 2.1, com esquema de cifragem RSAES-OAEP com hash SHA-1. Opção não disponível para assinaturas legadas. D_OAEP_SHA2_256_PADDING: O padding é feito seguindo o padrão PKCS#1 versão 2.1, com esquema de cifragem RSAES-OAEP com hash SHA2-256. Opção não disponível para assinaturas legadas. D_X931_PADDING: O padding é feito seguindo o padrão ANSI X9.31. Opção não disponível para assinaturas legadas. D_NO_PADDING: Não é feito padding, os dados passados para criptografia já devem ter comprimento do tamanho do bloco de operação para chaves RSA. Para RSA disponível apenas em operações legadas. Para chaves de curvas elípticas não é feito padding e é disponível em operações não legadas. Opção padrão para chaves de curvas elípticas.
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_GCM: Galois/Counter Mode. A tag de autenticação está localizada logo após os dados encriptados/decriptados com o tamanho de (tamanho retornado - tamanho da mensagem em texto claro). MODE_KW: AESWRAP de acordo com o padrão RFC-3394. Utilizado nas operações de encriptação e decriptação de outras chaves. O padding utilizado é o definido como no padrão, qualquer outro valor será ignorado. Utilizar o IV padrão com valor 0xA6A6A6A6A6A6A6A60000000000000000. MODE_KWP: AESWRAP com padding de acordo com o padrão RFC-5649. Utilizado nas operações de encriptação e decriptação de outras chaves. O padding utilizado é o definido como no padrão, qualquer outro valor será ignorado. Utilizar o IV padrão com valor 0xA65959A6000000000000000000000000. 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.

◆ DGetKeyParam()

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.
DKP_BLOCK_SIZE	Tipo de `pbData:` DWORD Recupera o tamanho do bloco da chave em bytes.
DKP_OBJ_ATTRIBUTES	Tipo de `pbData:` DWORD Recupera os atributos da chave.
DKP_OBJ_STATS	Tipo de `pbData:` DN_OBJ_STATS Recupera as informações de estatística do objeto.

[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: key_attribute.c.

◆ DDeriveKey()

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.

◆ DDuplicateKey()

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.

◆ DHashSessionKey()

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.

◆ DDestroyKey()

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: crypt_sym.c, eft_validate_cvv.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, import_export.c, key_add_remove.c, key_attribute.c, pin_block_translate.c, sign_verify.c, sign_verify_eddsa.c e verify_pin_block.c.

◆ DGeneratePKCS10CSR()

int AAP_API DGeneratePKCS10CSR	(	HSESSIONCTX	hSession,
		char *	szPrivateKeyName,
		BYTE	bVersion,
		char *	szDN,
		DWORD	dwOutType,
		DWORD *	pdwCSRLen,
		BYTE **	ppbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Gera um CSR (Certificate Signing Request / Requisição de Assinatura de Certificado). É uma função especializada da API de geração de CSR PKCS#10 do HSM.

Parâmetros

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

[in] szPrivateKeyName Identificador da chave privada.

[in]

bVersion

Versão do CSR PKCS#10. A seguinte tabela é suportada.

Valor	Significado
CORE_P10_CSR_VERSION1	PKCS#10 CSR versão 1.

[in] szDN DN (Dinstinguished Name), para a geração do CSR, com tamanho máximo CORE_P10_CSR_DN_MAX_LEN. Os campos de DN deverão ser separados por '/'.

[in]

dwOutType

Tipo de saída do CSR. A seguinte tabela é suportada.

Valor	Significado
P10_CSR_DER	Exporta o CSR no formato DER.
P10_CSR_PEM	Exporta o CSR no formato PEM.

[out] pdwCSRLen Ponteiro para o tamanho do buffer alocado em ppbCSR.

[out] ppbCSR Ponteiro de ponteiro que irá receber o CSR.
O tamanho do buffer alocado estará disponível através de pdwCSRLen.
A alocação de memória é feita internamente.
A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree().

[in]

dwParam

Parâmetros adicionais. A seguinte tabela é suportada.

Valor	Significado
0	Utiliza o hash padrão do HSM na assinatura do CSR.
CORE_P10_HASH_SHA1	Utiliza o SHA-1 na assinatura do CSR.
CORE_P10_HASH_SHA224	Utiliza o SHA-224 na assinatura do CSR.
CORE_P10_HASH_SHA256	Utiliza o SHA-256 na assinatura do CSR.
CORE_P10_HASH_SHA384	Utiliza o SHA-384 na assinatura do CSR.
CORE_P10_HASH_SHA512	Utiliza o SHA-512 na assinatura do CSR.

Anotações: Exemplos de campo DN.
/CN=teste

/CN=www.teste.com/O=teste/OU=engenharia

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

Exemplos: gen_csr.c.

◆ DAssociatePKCS11Key()

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.

No caso de chaves EC o CKA_ID será o hash SHA1 do valor de CKA_PUBLIC_KEY_INFO.

Veja também: DImportPKCS12().

◆ DExportPKCS12()

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

#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]

dwFlags

Passar 0 ou uma das opções da tabela abaixo.

Atributo	Valor
DN_EXPORT_P12_LEGACY	Exporta a chave e certificado e gera o arquivo PKCS#12 em software.

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 com a flag DN_EXPORT_P12_LEGACY utiliza RC2 para criptografia do certificado, TripleDES(CBC) para criptografia de chave e SHA1 como hash padrão.

Veja também: DImportPKCS12Buffer() DImportPKCS12().

◆ DImportPKCS12Buffer()

int AAP_API DImportPKCS12Buffer	(	const HSESSIONCTX	hSession,
		BYTE *	pbPkcs12,
		DWORD	dwPkcs12Len,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		DWORD	dwKeyAttr,
		const char *	szCertId,
		const char *	szPubKeyId,
		DWORD	dwFlags )

#include <dinamo.h>

Importa uma chave privada/pública e um certificado a partir de um buffer no formato PKCS#12.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession(). .
[in]	pbPkcs12	PKCS#12 que será importado.
[in]	dwPkcs12Len	Tamanho do buffer que contém o PKCS#12 em `pbPkcs12`.
[in]	szPkcs12Pwd	Senha do PKCS#12. Passar NULL para o caso de não haver senha.
[in]	szKeyId	Nome da chave privada que será importada. Veja `szKeyId` em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.
[in]	dwKeyAttr	Atributos da chave privada que será importada Veja `dwFlags` em DGenerateKey() para detalhes sobre os atributos de chave.
[in]	szCertId	Nome do certificado que será importado. Deve ser relacionado a chave privada.
[in]	szPubKeyId	Nome da chave pública que poderá ser importada. Pode ser NULL caso não queira que a chave pública seja importada.
[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: DExportPKCS12(), DImportPKCS12().

Exemplos: pkcs7_sign.c, sign_check_pix_jws.c, sign_verify_dict.c, sign_verify_pix.c e sign_verify_xml.c.

◆ DImportPKCS12()

int AAP_API DImportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12File,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const DWORD	dwKeyAttr,
		const char *	szCertId )

#include <dinamo.h>

Importa uma chave privada/pública e um certificado a partir de um arquivo no formato PKCS#12.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession(). .
[in]	szPkcs12File	Nome do arquivo PKCS#12 que será importado.
[in]	szPkcs12Pwd	Senha do PKCS#12. Passar NULL para o caso de não haver senha.
[in]	szKeyId	Nome da chave privada que será importada. Veja `szKeyId` em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.
[in]	dwKeyAttr	Atributos da chave privada que será importada Veja `dwFlags` em DGenerateKey() para detalhes sobre os atributos de chave.
[in]	szCertId	Nome do certificado que será importado. Deve ser relacionado a chave privada.

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

Veja também: DExportPKCS12(), DImportPKCS12Buffer().

◆ DRSAPublicKey2Info()

int AAP_API DRSAPublicKey2Info	(	BYTE *	pbKey,
		DWORD	dwKeyLen,
		DWORD	dwInForm,
		void *	pvPubKeyInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Decodifica as informações de uma chave pública RSA. Aceita chaves públicas no formato PKCS#1 RSAPublicKey ou X.509 SubjectPublicKeyInfo.

Parâmetros

[in] pbKey Chave pública.

[in] dwKeyLen Tamanho do buffer pbKey.

[in]

dwInForm

Formato de entrada da chave em pbKey. A tabela abaixo é aceita.

Atributo	Valor
DN_FORM_DER	Chave em formato DER.

[out] pvPubKeyInfo Ponteiro para uma estrutura DN_RSA_PUB_KEY_INFO.

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

◆ DRSAPrivateKey2Info()

int AAP_API DRSAPrivateKey2Info	(	const BYTE *	pbRsa,
		DWORD	dwRsaLen,
		DWORD	dwInForm,
		DN_RSA_PRIVATE_KEY_INFO *	stRsaInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Decodifica as informações de uma chave privada RSA. Aceita chaves privadas no formato PKCS#1 RSAPrivateKey ou PKCS#8 PrivateKeyInfo sem encriptação.

Parâmetros

[in] pbRsa Chave privada.

[in] dwRsaLen Tamanho do buffer pbRsa.

[in]

dwInForm

Formato de entrada da chave em pbRsa. A tabela abaixo é aceita.

Atributo	Valor
DN_FORM_DER	Chave em formato DER.

[out] stRsaInfo Ponteiro para uma estrutura DN_RSA_PRIVATE_KEY_INFO.

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

◆ DByokExport()

int AAP_API DByokExport	(	HSESSIONCTX	hSession,
		const char *	cszKeyId,
		const char *	cszKekId,
		DWORD	dwType,
		const void *	pvData,
		BYTE **	ppbOutData,
		DWORD *	pdwOutDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Exporta uma chave no formato BYOK (Bring Your Own Key) para um provedor de nuvem.

Parâmetros

[in] hSession Contexto de sessão.

[in] cszKeyId Identificador da chave que será exportada. Veja szKeyId em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.

[in] cszKekId Identificador da chave KEK que será utilizada para encriptar a chave que será exportada.

[in]

dwType

Tipo de exportação. A tabela abaixo é aceita.

Atributo	Valor
DN_BYOK_TYPE_AZURE	Exporta chave BYOK para Azure. Passar a estrutura DN_EXPORT_BYOK_AZURE em `pvData`.
DN_BYOK_TYPE_AWS	Exporta chave BYOK para AWS. Passar D_OAEP_SHA1_PADDING ou D_OAEP_SHA2_256_PADDING. Tipo DWORD em `pvData`.

[in] pvData Ponteiro para uma estrutura de dados específica para cada tipo de exportação. Ver dwType para detalhes.

[out] ppbOutData Ponteiro para um ponteiro que conterá os dados de saída. Esta área de dados será alocada internamente e deve ser liberada utilizando DFree().

[out] pdwOutDataLen Ponteiro para o tamanho dos dados escritos em ppbOutData.

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

Descrição detalhada

Estruturas de Dados

Definições e Macros

Funções

Definições e macros

◆ D_IMPORT_ALG_PRIV_KEY_RSA

◆ D_IMPORT_ALG_PRIV_KEY_ECC

◆ D_IMPORT_ALG_PRIV_KEY_P8

◆ D_IMPORT_ALG_PRIV_KEY_ECX

◆ DN_FORM_DER

◆ DN_BYOK_TYPE_AZURE

◆ DN_BYOK_TYPE_AWS

Funções

◆ DGenerateKey()

◆ DGenerateKeyMaterial()

◆ DGetUserKey()

◆ DImportKey()

◆ DExportKey()

◆ DPKCS8ImportKey()

◆ DPKCS8ExportKey()

◆ DSetKeyParam()

◆ DGetKeyParam()

◆ DDeriveKey()

◆ DDuplicateKey()

◆ DHashSessionKey()

◆ DDestroyKey()

◆ DGeneratePKCS10CSR()

◆ DAssociatePKCS11Key()

◆ DExportPKCS12()

◆ DImportPKCS12Buffer()

◆ DImportPKCS12()

◆ DRSAPublicKey2Info()

◆ DRSAPrivateKey2Info()

◆ DByokExport()