Chaves

Descrição detalhada

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

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:

1. Standards for Efficient Cryptography Group (SECG)
2. Wireless Transport Layer Security (WTLS)
3. ANSI X9.62:2005 - Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA)
4. NIST FIPS PUB 186-4 - Digital Signature Standard (DSS)
5. 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.