Claves

Descripción detallada

Gestión del ciclo de vida de las claves criptográficas en HSM.

Gestión del ciclo de vida de las claves criptográficas en HSM. Más...

Estructuras de datos
struct	DN_EXPORT_BYOK_AZURE

Definiciones y macros
#define	D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Importa una clave privada RSA. */
#define	D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Importa una clave privada ECC (Curvas Elípticas excepto ECX). */
#define	D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFDF) /* Importar una clave en formato P8 */
#define	D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFDE) /* Importar una clave privada ECX */
#define	DN_FORM_DER (1)
#define	DN_BYOK_TYPE_AZURE (1)
#define	DN_BYOK_TYPE_AWS (2)

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

Definiciones y macros

D_IMPORT_ALG_PRIV_KEY_RSA

#define D_IMPORT_ALG_PRIV_KEY_RSA (0xFFFFFFE1) /* Importar una clave privada RSA. */

#include <dinamo.h>

D_IMPORT_ALG_PRIV_KEY_ECC

#define D_IMPORT_ALG_PRIV_KEY_ECC (0xFFFFFFE0) /* Importa una clave privada ECC (Curvas Elípticas excepto ECX). */

#include <dinamo.h>

D_IMPORT_ALG_PRIV_KEY_P8

#define D_IMPORT_ALG_PRIV_KEY_P8 (0xFFFFFFDF) /* Importar una clave en formato P8 */

#include <dinamo.h>

D_IMPORT_ALG_PRIV_KEY_ECX

#define D_IMPORT_ALG_PRIV_KEY_ECX (0xFFFFDE) /* Importar una clave 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>

Exportar clave BYOK a Azure.

DN_BYOK_TYPE_AWS

#define DN_BYOK_TYPE_AWS (2)

#include <dinamo.h>

Exportar clave BYOK a AWS.

Funciones

DGenerateKey()

int AAP_API DGenerateKey	(	HSESSIONCTX	hSesión,
		char *	szKeyId,
		int	nAlgId,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Crea y almacena en el HSM una clave criptográfica asociada a un algoritmo según los parámetros introducidos.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szKeyId	Identificador de la clave dentro del HSM. Este identificador no debe contener espacios ni caracteres especiales. Los caracteres en mayúsculas y minúsculas distinguen entre mayúsculas y minúsculas. Un identificador de objeto en el HSM puede tener una longitud máxima, en caracteres, de MAX_OBJ_ID (incluido el carácter terminador). Cuando se crean claves en la partición de otro usuario (se requiere permiso), el nombre debe estar completamente cualificado con un FQN(Full Qualified Name: partition_id/obj_id), la longitud máxima para un FQN es MAX_OBJ_ID_FQN_LEN (incluido el carácter terminador).
[en]	nAlgId	Define el algoritmo asociado a la clave criptográfica que se va a generar. Claves simétricas Valor Significado ALG_DES DES de 56 bits con paridad impar. ALG_3DES_112 3DES-EDE(Cifrar-Descifrar-Encriptar) de 112 bits con paridad impar. ALG_3DES_168 3DES-EDE(Cifrar-Descifrar-Encriptar) de 168 bits con paridad impar. ALG_DESX DESX de 192 bits. El tamaño efectivo es de 118 bits. ALG_ARC4 ARC4 con 128 bits. ALG_ARC5 ARC5 con 128 bits, bloque de 8 bytes y utilizando 16 rondas. ALG_AES_128 AES de 128 bits. ALG_AES_192 AES con 192 bits. ALG_AES_256 AES de 256 bits. Claves asimétricas RSA Valor Significado ALG_RSA_512 Par de claves RSA con módulo de 512 bits. ALG_RSA_1024 Par de claves RSA con módulo de 1024 bits. ALG_RSA_2048 Par de claves RSA con módulo de 2048 bits. ALG_RSA_4096 Par de claves RSA con módulo de 4096 bits. ALG_RSA_1152 Par de claves RSA con módulo de 1152 bits. ALG_RSA_1408 Par de claves RSA con módulo de 1408 bits. ALG_RSA_1536 Par de claves RSA con módulo de 1536 bits. ALG_RSA_1976 Par de claves RSA con módulo de 1976 bits. ALG_RSA_1984 Par de claves RSA con módulo de 1984 bits. ALG_RSA_8192 Par de claves RSA con módulo de 8192 bits. ALG_RSA_2304 Par de claves RSA con módulo de 2304 bits. ALG_RSA_2560 Par de claves RSA con módulo de 2560 bits. ALG_RSA_2816 Par de claves RSA con módulo de 2816 bits. ALG_RSA_3072 Par de claves RSA con módulo de 3072 bits. Claves asimétricas ECC Valor Significado ALG_ECC_SECP112R1 Curva SECG/WTLS sobre un cuerpo primo finito de 112 bits(parámetros de dominio de curva elíptica verificablemente aleatorios). ALG_ECC_SECP112R2 Curva SECG sobre un cuerpo primo finito de 112 bits(parámetros de dominio de curva elíptica 2 verificablemente aleatorios). ALG_ECC_SECP128R1 Curva SECG sobre un cuerpo primo finito de 128 bits(parámetros de dominio de curva elíptica aleatoria verificable 1). ALG_ECC_SECP128R2 Curva SECG sobre un cuerpo primo finito de 128 bits(parámetros de dominio de la curva elíptica verificablemente aleatorios 2). ALG_ECC_SECP160K1 Curva SECG sobre un cuerpo primo finito de 160 bits(parámetros de dominio koblitz ). ALG_ECC_SECP160R1 Curva SECG sobre un cuerpo primo finito de 160 bits(parámetros de dominio de curva elíptica 1 verificablemente aleatorios). ALG_ECC_SECP160R2 Curva SECG/WTLS sobre un cuerpo primo finito de 160 bits(parámetros de dominio de curva elíptica 2 verificablemente aleatorios). ALG_ECC_SECP192K1 Curva SECG sobre un cuerpo primo finito de 192 bits(parámetros de dominio koblitz ). ALG_ECC_SECP192R1 Curva SECG/X9.62/NIST sobre un cuerpo primo finito de 192 bits(parámetros de dominio de curva elíptica verificablemente aleatorios 1). ALG_ECC_SECP224K1 Curva SECG sobre un cuerpo primo finito de 224 bits(parámetros de dominio koblitz ). ALG_ECC_SECP224R1 Curva SECG/NIST sobre un cuerpo primo finito de 224 bits(parámetros de dominio de la curva elíptica verificablemente aleatorios 1). ALG_ECC_SECP256K1 Curva SECG sobre un cuerpo primo finito de 256 bits(parámetros de dominio koblitz ). ALG_ECC_SECP256R1 Curva SECG/X9.62 sobre un cuerpo primo finito de 256 bits(parámetros de dominio de curva elíptica verificablemente aleatorios 1). ALG_ECC_SECP384R1 Curva SECG/NIST sobre un cuerpo primo finito de 384 bits(parámetros de dominio de curva elíptica 1 verificablemente aleatorios). ALG_ECC_SECP521R1 Curva SECG/NIST sobre un cuerpo primo finito de 521 bits(parámetros de dominio de curva elíptica 1 verificablemente aleatorios). ALG_ECC_X9_62_PRIME192V1 Curva X9.62 sobre un cuerpo primo finito de 192 bits(parámetros de dominio de la versión 1). ALG_ECC_X9_62_PRIME192V2 Curva X9.62 sobre un cuerpo primo finito de 192 bits(parámetros de dominio de la versión 2). ALG_ECC_X9_62_PRIME192V3 Curva X9.62 sobre un cuerpo primo finito de 192 bits(parámetros de dominio de la versión 3). ALG_ECC_X9_62_PRIME239V1 Curva X9.62 sobre un cuerpo primo finito de 239 bits(parámetros de dominio de la versión 1). ALG_ECC_X9_62_PRIME239V2 Curva X9.62 sobre un cuerpo primo finito de 239 bits(parámetros de dominio de la versión 2). ALG_ECC_X9_62_PRIME239V3 Curva X9.62 sobre un cuerpo primo finito de 239 bits(parámetros de dominio de la versión 3). ALG_ECC_X9_62_PRIME256V1 Curva X9.62 sobre un cuerpo primo finito de 256 bits(parámetros de dominio de la versión 1). ALG_ECC_BRAINPOOL_P160R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 160 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P160T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 160 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P192R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 192 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P192T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 192 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P224R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 224 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P224T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 224 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P256R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 256 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P256T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 256 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P320R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 320 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P320T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 320 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P384R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 384 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P384T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 384 bits(parámetros de dominio retorcidos 1) ALG_ECC_BRAINPOOL_P512R1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 512 bits(parámetros de dominio verificablemente aleatorios 1) ALG_ECC_BRAINPOOL_P512T1 RFC 5639 Curva Brainpool sobre un cuerpo primo finito de 512 bits(parámetros de dominio retorcidos 1) Claves asimétricas ECX Valor Significado ALG_ECX_ED25519 Curva RFC 8032(sólo firma) sobre un cuerpo primo finito de ~256 bits. ALG_ECX_ED448 Curva RFC 8032(sólo firma) sobre un cuerpo primo finito de ~448 bits. ALG_ECX_X25519 Curva RFC 7748 (sólo acuerdo de claves) sobre un cuerpo primo finito de ~256 bits. ALG_ECX_X448 Curva RFC 7748 (sólo acuerdo de claves) sobre un cuerpo primo finito de ~448 bits. Claves HMAC Valor Significado ALG_HMAC_MD5 Clave HMAC MD5 con un tamaño de 16 bytes. ALG_HMAC_SHA1 Clave HMAC SHA1 con un tamaño de 20 bytes. ALG_HMAC_SHA2_256 Clave HMAC SHA2 256 con un tamaño de 32 bytes. ALG_HMAC_SHA2_384 Clave HMAC SHA2 384 con un tamaño de 48 bytes. ALG_HMAC_SHA2_512 Clave HMAC SHA2 512 con un tamaño de 64 bytes.
[en]	dwFlags	Parámetros clave adicionales. Valor Significado CLAVE EXPORTABLE La clave puede exportarse desde el HSM. CLAVE_TEMPORAL La clave sólo existirá mientras la sesión esté activa. Se destruirá cuando se cierre la sesión. El parámetro szKeyId, el identificador de la clave, debe ser NULL. Además de los valores de la tabla anterior, puede añadir una definición de perfil de utilización de claves. Puede definir el perfil de utilización de las teclas (Atributo Perfil de uso), utilizando sólo uno de los valores indicados a continuación. Si no se especifica ninguno de los valores siguientes, el perfil de conmutación se establece como libre para cualquier uso. Es obligatorio definir el perfil de uso cuando el HSM está en RM3. Valor Significado AUP_DIG_SIG generación/verificación de firmas AUP_DATA_CRYPTO cifrado/descifrado de datos AUP_KeK empaquetado/desempaquetado de llaves AUP_MAC Generación/verificación de MAC AUP_KDF función de derivación de claves AUP_CRYPTOGRAM generación/verificación de criptogramas AUP_KEY_TRANSLATE traducción clave AUP_EFT_CVK Generación/verificación de VSC AUP_EFT_VISA_PVK Generación de PVP AUP_EFT_IBM_3624 Generación/validación de PIN AUP_EFT_PEK Cifrado/descifrado del PIN AUP_EFT_BDK DUKPT AUP_EFT_IPEK DUKPT IPEK AUP_EMV_IMK Derivación ICC MK, IDN AUP_EMV_IMKDAC Derivación DAC ICC AUP_EMV_IMKENC Cifrado de datos ICC - PinBlock AUP_EMV_IMKMAC Criptograma de datos ICC - EmvMac AUP_EMV_KeK Envoltorio ICC MK AUP_EMV_IMKKDF Derivación de claves EMV AUP_EMV_IMKACRYPTO Cálculo ARPC AUP_EFT_KeK Envoltura/desenvoltura de llaves EFT AUP_EMV_DIG_SIG Generación/verificación de firmas EMV AUP_EFT_TR31_KBPK Llave de protección TR31 AUP_EFT_TR34_PK firma/sobre TR34 AUP_SPB_PK Generación/verificación de firmas SPB y envoltura de claves
[en]	phKey	Puntero al contexto de la clave generada. Tras su uso, debe liberarse con la función DDestroyKey(). Se puede pasar NULL para no devolver el contexto de la clave.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Atención

En Dinamo todas las claves se almacenan cifradas, independientemente del modo de funcionamiento (NRM, RM1 o RM2).

Notas

A los contextos de clave simétrica se les asignan los siguientes valores por defecto, en su caso:

Parámetros	Valor
Vector de inicialización	Será un vector con todos los bytes iguales a cero y del mismo tamaño que el bloque de operaciones del algoritmo de claves.
Modo de funcionamiento del cifrado simétrico	Se utilizará el modo CBC (cadena de bloques cifrados)
Acolchado	Se utilizará el formato definido en la norma PKCS#5 como relleno.

El tamaño del bloque de operaciones de los algoritmos se ajusta a la tabla siguiente:

Valor	Tamaño del bloque
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

Las claves RSA en HSM se crean preferentemente con un exponente público fijo y definido (tres bytes en la secuencia 01 00 01, valor decimal de 216 + 1 = 65537). Opcionalmente, se puede utilizar un exponente de valor 3 por razones de compatibilidad con sistemas más antiguos, pero no se recomienda.
Las claves ECC se definen con arreglo a normas:

1. Grupo de Normas para una Criptografía Eficaz (SECG)
2. Seguridad de la capa de transporte inalámbrica (WTLS)
3. ANSI X9.62:2005 - Criptografía de clave pública para la industria de servicios financieros, Algoritmo de firma digital de curva elíptica (ECDSA)
4. NIST FIPS PUB 186-4 - Estándar de firma digital (DSS)
5. RFC 5639 - Criptografía de curvas elípticas (ECC) Curvas estándar Brainpool y generación de curvas

Ejemplos

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 y tokenisation.c.

DGenerateKeyMaterial()

int AAP_API DGenerateKeyMaterial	(	HSESSIONCTX	hSesión,
		int	nAlgId,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReservado )

#include <dinamo.h>

Genera una clave criptográfica y devuelve su contenido. Esta operación genera una clave utilizando el HSM y devuelve el contenido de la clave sin persistir la clave en el HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	nAlgId	Define el algoritmo de la clave criptográfica que se va a generar. Esta operación sólo admite algoritmos de clave simétrica. Véase la lista de algoritmos en DGenerateKey().
[en]	pbData	Buffer que contendrá la clave generada. Se puede pasar NULL para recibir el tamaño esperado de pbData en pdwDataLen.
[in,out]	pdwDataLen	Puntero que contiene el tamaño del búfer pbData. Esta variable contendrá el tamaño exacto de los datos copiados en pbData. Si pbData es NULL o el tamaño introducido no es suficiente para completar la operación, pdwDataLen contendrá el tamaño esperado de pbData.
[en]	dwReservado	Reservado para uso futuro.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DGetUserKey()

int AAP_API DGetUserKey	(	HSESSIONCTX	hSesión,
		char *	szKeyId,
		DWORD	dwFlags,
		HKEYCTX *	phKey )

#include <dinamo.h>

Recupera el contexto de una clave, siempre que el usuario actual tenga acceso, almacenada en el HSM. Esta función no crea una nueva clave.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szKeyId	Identificador de la clave dentro del HSM. Este identificador no debe contener espacios ni caracteres especiales. Los caracteres en mayúsculas y minúsculas distinguen entre mayúsculas y minúsculas. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	dwFlags	Pasa cero. De lo contrario, se acepta la siguiente tabla. Valor Significado D_GET_USR_KEY_OFFLINE Generará un manejador de clave basado en parámetros específicos y no acudirá al HSM para comprobar los parámetros introducidos. Para utilizar este indicador, debe pasarse una estructura GET_USR_KEY_OFFLINE debidamente cumplimentada en szKeyId. Tenga en cuenta que no se realiza ninguna comprobación de correlación en los datos introducidos. Pasar datos inválidos generará un handle inválido, incluso si esta función devuelve éxito. D_GET_USR_KEY_NO_PUB Si recupera una clave pública, no intentará exportar su contenido para obtener más detalles. La información de la clave será parcial. Esta opción se utiliza sólo en casos específicos de uso de M de N de partición en el estado de asociado, autorizadodonde no se permite exportar la clave pública.
[fuera]	phKey	Puntero al contexto de la clave generada. Tras su uso, debe liberarse con la función DDestroyKey().

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ver también

DGenerateKey().

Ejemplos

key_attribute.c.

DImportKey()

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

#include <dinamo.h>

Importa una clave criptográfica al HSM. Las claves pueden ser permanentes o temporales. Las claves exportadas con la función DExportKey( ) pueden importarse sin cambiar su formato.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szKeyId	Identificador de la clave dentro del HSM. Este identificador no debe contener espacios ni caracteres especiales. Los caracteres en mayúsculas y minúsculas distinguen entre mayúsculas y minúsculas. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	hKEKey	Contexto de la clave con la que se cifra el blob de la clave que se va a importar - KEK (clave de cifrado de la clave)
[en]	dwBlobType	Formato del búfer de claves en el parámetro pbData. Valor Significado PRIVATEKEY_BLOB_STRICT Se importará un par de claves RSA o EC en formato PRIVATEKEY_BLOB. hKEKey debe ser el contexto de una clave simétrica, una clave pública (interna del HSM, véase PUBLICKEY_BLOB_HSM) o NULL. Se aceptan los siguientes formatos. Para RSA: clave privada (que contiene información sobre el módulo y el exponente público), definida en PKCS#1 v1.5 sección 7.2. Para ECC las claves deben tener el formato ECPrivateKey descrito en RFC 5915. Para claves ECX (EdDSA y XECDH) el formato es el descrito en RFC 8410. PRIVATEKEY_BLOB Mismo comportamiento que PRIVATEKEY_BLOB_STRICT, pero las versiones anteriores de HSM pueden devolver claves RSA como una concatenación de clave privada y clave pública en los formatos definidos en PKCS#1 v1.5, en las secciones 7.1 y 7.2. Esta opción se mantiene por compatibilidad. Utilice PRIVATEKEY_BLOB_STRICT. PRIVATEKEY_BLOB_P8 Se importará un par de claves RSA en formato PRIVATEKEY_BLOB_P8. hKEKey debe ser el contexto de una clave simétrica. El formato blob de la clave es el PrivateKeyInfo definido en PKCS#8. PUBLICKEY_BLOB Se importará una clave pública de un par de claves RSA o EC con el formato PUBLICKEY_BLOB.hKEKey debe ser igual a NULL. El contexto devuelto por la importación de clave pública solo debe utilizarse en operaciones de sobre digital, ya que el HSM no crea de forma persistente objetos RSA con solo la parte pública de la clave siguiendo el estándar de formato PKCS#1 v2.2 DER.Para claves públicas EC (ECC y ECX) el estándar es el formato SubjectPublicKeyInfo DER. SIMPLE_BLOB Se importará una clave simétrica en formato SIMPLE_BLOB.hKEKey debe ser el contexto de una clave privada asociada a la clave pública utilizada para cifrar el blob que se va a importar.El tipo de relleno utilizado para cifrar la clave debe ser 2, tal y como se define en PKCS#1 v1.5 sección 8.1. PLAINTEXTKEY_BLOB Esta opción aún no está disponible para claves RSA. SIMPLE_BLOB_OAEP Define la importación mediante sobre digital utilizando el estándar PKCS#1 versión 2.1, con esquema de cifrado RSAES-OAEP con hash SHA-1. La KEK debe ser una clave privada en el HSM, cuya clave pública correspondiente se utilizó para crear el sobre. El contexto de esta KEK puede obtenerse mediante una llamada a DGetUserKey, donde se introducirá el id de la clave RSA del HSM utilizada para abrir el sobre. Este método de importación puede utilizarse en modos de funcionamiento restringidos. SYM_WRAPPED_KEY_BLOB Define una clave simétrica cifrada por una KEK (Key Encryption Key) también simétrica. El parámetro hKEKey debe contener el contexto de una clave simétrica con los parámetros de uso adecuados ya definidos, como el modo y el relleno. La clave se descifrará y se importará en la base HSM directamente, sin ningún formato específico. HOTP_BLOB Define la importación de un objeto HTOP en la partición de usuario. PUBLICKEY_BLOB_HSM Se importará en el HSM una clave pública de un par de claves RSA/ECC en formato DER. hKEKey debe ser igual a NULL. PUBLICKEY_RSA_PARTS_HSM Se importará una clave pública en el HSM desde el módulo y el exponente público. hKEKey debe ser igual a NULL. La estructura RSA_PUB_KEY_PARTS debidamente completada debe pasarse en pbData. WRAPPED_KEY_BLOB Importar una clave cifrada mediante una KEK (Key Encryption Key). El parámetro hKEKey debe contener el contexto de una clave simétrica con los parámetros de uso adecuados ya definidos, como el modo (según el algoritmo) y el relleno. La clave se descifrará y se importará en la base de datos del HSM directamente, sin ningún formato específico. WRAPPED_KEY_BLOB_P8 Importar una clave cifrada mediante una KEK (Key Encryption Key). El parámetro hKEKey debe contener el contexto de una clave simétrica con los parámetros de uso adecuados ya definidos, como el modo (según el algoritmo) y el relleno. La clave se descifrará y se importará en la base de datos del HSM directamente, sin ningún formato específico. En la operación de exportación de claves, el formato de la clave privada será PKCS#8.
[en]	nAlgId	Indica el algoritmo asociado a la clave criptográfica que se generará. Véase la lista de algoritmos en DGenerateKey(). Utilice D_IMPORT_ALG_PRIV_KEY_RSA cuando la clave privada importada sea RSA y esté cifrada por KEK, el algoritmo específico será detectado automáticamente por el HSM tras abrir el BLOB cifrado.
[en]	dwFlags	Parámetros adicionales de la clave. Consulte las opciones de la función DGenerateKey().
[en]	pbData	Buffer que contiene la clave a importar.
[en]	dwDataLen	Tamaño del bloque de datos con la clave a importar.
[fuera]	phKey	Puntero al contexto de la clave generada. Tras su uso, debe liberarse con la función DDestroyKey.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

Para las claves de sesión y las claves públicas, se recomienda utilizar el indicador TEMPORARY_KEY, para evitar que las claves temporales ocupen espacio innecesario en el HSM.

Formato SIMPLE_BLOB:

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

Estructuras DER PRIVATEKEY_BLOB:

RSAPrivateKey ::= SEQUENCE {
    versión,
    módulo 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)
    coeficiente INTEGER -- (inverso de q) mod p
}

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

Estructura DER de PUBLICKEY_BLOB:

RSAPublicKey ::= SEQUENCE {
    módulo INTEGER, -- n
    publicExponent INTEGER -- e
}

Estructura DER de PUBLICKEY_BLOB_X509:

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

Ver también

Observaciones de DGenerateKey().

Ejemplos

eft_validate_cvv.c, import_export.c, pin_block_translate.c y 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 una clave almacenada en el HSM para que pueda ser transportada. A continuación, la clave puede importarse de nuevo a Dinamo con la función DImportKey().

Parámetros

[en]	hKey	Contexto de la clave a exportar.
[en]	hKEKey	Contexto de la clave con la que se cifrará el bloque de claves - KEK (clave de cifrado de claves).
[en]	dwBlobType	Formato del búfer de claves en el parámetro pbData. Ver parámetro dwBlobType en DImportKey() para la lista de tipos.
[en]	dwFlags	Reservado para uso futuro (debe ser 0).
[en]	pbData	Buffer que contiene los datos de la clave según el parámetro dwBlobType. Este parámetro puede ser NULL para especificar la cantidad de memoria necesaria.
[in,out]	pdwDataLen	Puntero al tamaño del búfer, en bytes, especificado en pbData. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en pbData.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

Sólo las claves creadas como exportables pueden extraerse con esta función, de lo contrario se devolverá el código de error D_INVALID_KEY_STATE.

Ejemplos

gen_ecdh.c, gen_xecdh.c e import_export.c.

DPKCS8ImportKey()

int AAP_API DPKCS8ImportKey	(	HSESSIONCTX	hSesión,
		char *	szKeyId,
		char *	szSecret,
		DWORD	dwKeyAlg,
		DWORD	dwAttrib,
		BYTE *	pbSobreLlave,
		DWORD	dwKeyEnvelopeLen )

#include <dinamo.h>

Importa una clave privada RSA asimétrica envuelta según el estándar PKCS#8 en el HSM. La clave privada RSA puede importarse en texto claro o protegida por una envoltura digital. Para obtener más información sobre los estándares, consulte los documentos de RSA Labs Public-Key Cryptography Standards (PKCS). En los modos de funcionamiento restringidos (RM1 y RM2), las claves RSA sólo pueden importarse a través del estándar PKCS#8 utilizando un sobre digital, derivando una clave AES 256 a partir de una contraseña de al menos 01 carácter y no más de 16, y la derivación se realiza según el estándar PKCS#5 versión 2.0.
El sobre utilizado puede proceder de cualquier sistema que se adhiera a los estándares descritos.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szKeyId	Identificador de la clave RSA que se creará en la base HSM. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	szSecret	Contraseña utilizada para obtener la clave AES 256. Se puede pasar NULL para ninguna contraseña (importación en texto claro) o una contraseña de no ND_MAX_P8_PWD_LEN caracteres más terminador nulo.
[en]	dwKeyAlg	Indica el algoritmo asociado a la clave criptográfica a generar. Valor Significado ALG_RSA_512 Par de claves RSA con módulo de 512 bits. ALG_RSA_1024 Par de claves RSA con módulo de 1024 bits. ALG_RSA_2048 Par de claves RSA con módulo de 2048 bits. ALG_RSA_4096 Par de claves RSA con módulo de 4096 bits. ALG_RSA_1152 Par de claves RSA con módulo de 1152 bits. ALG_RSA_1408 Par de claves RSA con módulo de 1408 bits. ALG_RSA_1536 Par de claves RSA con módulo de 1536 bits. ALG_RSA_1976 Par de claves RSA con módulo de 1976 bits. ALG_RSA_1984 Par de claves RSA con módulo de 1984 bits. ALG_RSA_8192 Par de claves RSA con módulo de 8192 bits. ALG_RSA_2304 Par de claves RSA con módulo de 2304 bits. ALG_RSA_2560 Par de claves RSA con módulo de 2560 bits. ALG_RSA_2816 Par de claves RSA con módulo de 2816 bits. ALG_RSA_3072 Par de claves RSA con módulo de 3072 bits.
[en]	dwAttrib	Parámetros clave adicionales. Valor Significado CLAVE EXPORTABLE La clave puede exportarse en claro desde el HSM.
[en]	pbSobreLlave	Búfer que contiene el sobre PKCS#8 de entrada.
[en]	dwKeyEnvelopeLen	Tamaño en bytes del sobre PKCS#8 entrante.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DPKCS8ExportKey()

int AAP_API DPKCS8ExportKey	(	HSESSIONCTX	hSesión,
		char *	szKeyId,
		char *	szSecret,
		BYTE **	ppbKeyEnvelope,
		DWORD *	pdwKeyEnvelopeLen )

#include <dinamo.h>

Exporta una clave privada RSA asimétrica almacenada en el HSM según el estándar PKCS#8. La clave privada RSA puede exportarse en texto claro o protegida por un sobre digital. Para más información sobre las normas, consulte los documentos de RSA Labs Public-Key Cryptography Standards (PKCS). En los modos de funcionamiento restringidos (RM1 y RM2), las claves RSA exportables sólo se pueden exportar a través del estándar PKCS#8 utilizando un sobre digital, derivando una clave AES 256 a partir de una contraseña con una longitud comprendida entre ND_MIN_P8_PWD_LEN y ND_MAX_P8_PWD_LEN caracteres, y la derivación se realiza de acuerdo con el estándar PKCS#5 versión 2.0. El sobre de salida puede importarse a cualquier sistema que cumpla las normas descritas.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szKeyId	Identificador de la clave RSA a exportar. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	szSecret	Contraseña con una longitud comprendida entre ND_MIN_P8_PWD_LEN y ND_MAX_P8_PWD_LEN más terminador nulo, utilizada para derivar la clave AES 256. Se puede pasar NULL para exportar en texto claro, sin contraseña.
[fuera]	ppbSobreLlave	Puntero que contendrá el sobre PKCS#8 saliente. La asignación de memoria se realiza internamente por la biblioteca. La aplicación que llama es responsable de liberar la memoria asignada. Se debe utilizar la función DFree() para liberar este búfer.
[fuera]	pdwKeyEnvelopeLen	Puntero a DWORD que contendrá el tamaño en bytes del sobre PKCS#8 saliente.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DSetKeyParam()

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

#include <dinamo.h>

Cambia los parámetros de los contextos clave que, en general, influirán en su manipulación.

Parámetros

[en]	hKey	Contexto de la clave a exportar.
[en]	dwParam	Define la operación que se realizará y, en consecuencia, la estructura o los datos pasados en el parámetro pbData. Valor Significado DKP_IV Tipo de pbData: BYTE * Vector de inicialización utilizado con los algoritmos de blockchain según su modo de funcionamiento de cifrado simétrico. El tamaño del vector de inicialización depende del algoritmo simétrico utilizado, ya que tiene la misma longitud que el bloque de operaciones. Más detalles en la sección Observaciones. Sólo válido para claves simétricas. DKP_PADDING Tipo de pbData: DWORD La biblioteca puede trabajar con los siguientes rellenos simétricos: D_NO_PADDING: No se realiza ningún relleno, los datos pasados para la encriptación deben ser ya un múltiplo del tamaño del bloque de la operación. D_PKCS5_PADDINGRelleno: El relleno se realiza siguiendo el patrón definido en PKCS#5. Este es el relleno por defecto si no se define ninguno. D_ZERO_PADDINGSi la longitud de los datos no es múltiplo del tamaño del bloque de operación, se completa con ceros a la izquierda hasta alcanzar un tamaño soportado por el algoritmo. Este tipo de relleno no debe utilizarse con datos en los que pueda haber cero bytes, ya que puede crear ambigüedad en la operación de descifrado. Si los datos sólo contienen texto ASCII, por ejemplo, no hay ningún problema. Sólo válido para claves simétricas. La biblioteca puede trabajar con los siguientes rellenos asimétricos: D_PKCS1_PADDINGRelleno: El relleno se realiza siguiendo el estándar definido en PKCS#1 v1.5. Es el relleno estándar para claves RSA, si no hay ninguno definido. D_PSS_PADDINGEl relleno se realiza siguiendo la norma PSS definida en PKCS#1 EMSA-PSS-ENCODE con el mismo hash que el utilizado en el hash del mensaje, utilizando la función sal con el tamaño máximo disponible en el bloque. Opción no disponible para las suscripciones heredadas. D_PSS_SALT_LEN_MD_PADDINGEl relleno se realiza siguiendo la norma PSS definida en PKCS#1 EMSA-PSS-ENCODE con el mismo hash que el utilizado en el hash del mensaje, utilizando la función sal con el mismo tamaño que la salida hash utilizada en la operación. Opción no disponible para firmas heredadas. D_OAEP_SHA1_PADDINGRelleno: El relleno se realiza siguiendo el estándar PKCS#1 versión 2.1, con esquema de cifrado RSAES-OAEP con hash SHA-1. Opción no disponible para firmas heredadas. D_OAEP_SHA2_256_PADDINGRelleno: El relleno se realiza siguiendo el estándar PKCS#1 versión 2.1, con esquema de cifrado RSAES-OAEP con hash SHA2-256. Opción no disponible para firmas heredadas. D_X931_PADDINGRelleno: El relleno se realiza siguiendo la norma ANSI X9.31. Opción no disponible para firmas heredadas. D_NO_PADDING: Sin relleno, los datos pasados para el cifrado ya deben tener la longitud del bloque de operación para claves RSA. Para RSA sólo está disponible en operaciones heredadas. Para claves de curva elíptica no hay relleno y está disponible en operaciones no heredadas. Opción estándar para claves de curva elíptica. DKP_MODE Tipo de pbData: DWORD Indica el modo de funcionamiento de cifrado del algoritmo de bloques. MODO_ECBLibro de códigos electrónico (BCE) MODE_CBCCadena de bloques cifrados (CBC) MODO_GCMModo Galois/Contador. La etiqueta de autenticación se encuentra justo después de los datos cifrados/descifrados con el tamaño de (tamaño devuelto - tamaño del mensaje en texto claro). MODO_KWAESWRAP según la norma RFC-3394. Se utiliza para cifrar y descifrar otras claves. El relleno utilizado es el definido en el estándar, cualquier otro valor será ignorado. Utiliza el IV por defecto con valor 0xA6A6A6A6A6A6A6A600000000000000000000. MODO_KWP: AESWRAP con relleno según la norma RFC-5649. Se utiliza para cifrar y descifrar otras claves. El relleno utilizado es el definido en el estándar, cualquier otro valor será ignorado. Utiliza el IV estándar con valor 0xA65959A60000000000000000000000000000. MODO_OFB: Output-Feedback. Aún no compatible. Sólo válido para claves simétricas y algoritmos de bloque. DKP_DUEÑO Tipo de pbData: char * Asigna a un usuario el privilegio de poseer la clave. pbData es un puntero a una cadena con el identificador de un usuario HSM. Aún no se admite. DKP_USUARIO Tipo de pbData: char * Asigna a un usuario el privilegio de usuario de la clave. pbData es un puntero a una cadena con el identificador de un usuario HSM. Aún no se admite. DKP_READ_LOCK Tipo de pbData: NULL Marcar la clave como no exportable. Aún no se admite.
[en]	pbData	Puntero a los datos o estructuras especificados en dwParam.
[en]	dwDataLen	Tamaño de los datos o de la estructura especificada en dwParam.
[en]	dwFlags	REMOVE_ATTRIBUTE se puede utilizar para eliminar los privilegios de un usuario sobre una clave. Este indicador sólo debe utilizarse junto con DKP_OWNER o DKP_USER.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DGetKeyParam()

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

#include <dinamo.h>

Recupera parámetros de contextos clave.

Parámetros

[en]	hKey	Contexto de la clave a exportar
[en]	dwParam	Define la operación que se realizará y, en consecuencia, la estructura o los datos pasados en el parámetro pbData. Todos los valores descritos en DSetKeyParam() y mucho más: Valor Significado DKP_ALGID Tipo de pbData: DWORD Recupera el algoritmo criptográfico asociado a la clave. La lista de valores posibles es la misma que la definida para el parámetro nAlgId en la función DGenerateKey (véase la página 36). Si el objeto no es una clave criptográfica, el valor devuelto es ALG_OBJ. DKP_KEYLEN Tipo de pbData: DWORD Recupera el tamaño de la clave en bytes. DKP_ENCRYPTED Tipo de pbData: BOOL Devuelve el estado de la clave dentro del HSM. Si es verdadero, la clave se almacenará cifrada dentro del HSM; si es falso, la clave se almacenará en claro. DKP_KEY_INFO Tipo de pbData: GET_USR_KEY_OFFLINE Devuelve la información básica de la clave. DKP_BLOCK_SIZE Tipo de pbData: DWORD Recupera el tamaño del bloque de claves en bytes. DKP_OBJ_ATTRIBUTES Tipo de pbData: DWORD Recupera los atributos de la clave. DKP_OBJ_STATS Tipo de pbData: DN_OBJ_STATS Recupera la información estadística del objeto.
[en]	pbData	Puntero a los datos o estructuras especificados en dwParam
[en]	pdwDataLen	Tamaño de los datos o de la estructura especificada en dwParam
[en]	dwFlags	Reservado para uso futuro (debe ser 0).

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ver también

DGenerateKey().

Ejemplos

key_attribute.c.

DDeriveKey()

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

#include <dinamo.h>

Deriva una clave a partir del hash introducido. Si el hash aún no está completo, se finalizará y su valor se utilizará como clave simétrica.

Parámetros

[en]	hHash	Contexto Hash creado con DCreateHash.
[en]	szKeyId	Identificador de la clave dentro del HSM. Este identificador no debe contener espacios ni caracteres especiales. Los caracteres en mayúsculas y minúsculas distinguen entre mayúsculas y minúsculas. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	nAlgId	Indica el algoritmo asociado a la clave criptográfica que se generará. Véase la lista de algoritmos en DGenerateKey().
[en]	dwFlags	Parámetros de clave adicionales. Véase la lista de parámetros de clave adicionales en DGenerateKey().
[en]	phKey	Puntero al contexto de la clave generada. Tras su uso, debe liberarse con la función DDestroyKey().

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DDuplicateKey()

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

#include <dinamo.h>

Duplica el contexto de una clave, incluido su estado interno.

Parámetros

[en]	hKey	Contexto clave.
[en]	dwFlags	Reservado para uso futuro (debe ser 0).
[fuera]	phKey	Puntero al contexto de la clave generada. Tras su uso, debe liberarse con la función DDestroyKey().

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

Los contextos de las teclas son independientes, por lo que cuando se libera el contexto original, el nuevo contexto sigue siendo válido.

DHashSessionKey()

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

#include <dinamo.h>

Utiliza el valor de una clave simétrica como dato de entrada para la ejecución de un hash. El contexto hash debe tener un contexto limpio para poder ser utilizado en esta función, es decir, no puede haber sido utilizado con la función DHashData().

Parámetros

[en]	hKey	Contexto clave.
[en]	hHash	Contexto Hash creado con DCreateHash().
[en]	dwFlags	Reservado para uso futuro (debe ser 0).

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

La clave debe estar marcada como exportable para que esta operación tenga lugar.

DDestroyKey()

int AAP_API DDestroyKey	(	HKEYCTX *	phKey,
		DWORD	dwFlags )

#include <dinamo.h>

Libera el contexto de una tecla después de haber sido utilizada. Una vez liberado este contexto, ya no puede ser utilizado por ninguna función y deja de ser válido.

Parámetros

[en]	phKey	Puntero a un contexto clave que será liberado.
[en]	dwFlags	Modificadores de operación. Valor Significado ELIMINAR_DE_HSM Además de liberar el contexto señalado por phKeyextrae físicamente la llave de la base del HSM. Este parámetro sólo debe utilizarse cuando se tenga la certeza de que la clave ya no será necesaria.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ejemplos

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 y verify_pin_block.c.

DGenerarPKCS10CSR()

int AAP_API DGeneratePKCS10CSR	(	HSESSIONCTX	hSesión,
		char *	szPrivateKeyName,
		BYTE	bVersión,
		char *	szDN,
		DWORD	dwOutType,
		DWORD *	pdwCSRLen,
		BYTE **	ppbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Genera una CSR (solicitud de firma de certificado). Se trata de una función especializada de la API de generación de CSR PKCS#10 de HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szPrivateKeyName	Identificador de la clave privada.
[en]	bVersión	CSR versión PKCS#10. Se admite la siguiente tabla. Valor Significado CORE_P10_CSR_VERSION1 PKCS#10 CSR versión 1.
[en]	szDN	DN (Dinstinguished Name), para generar el CSR, con un tamaño máximo de CORE_P10_CSR_DN_MAX_LEN. Los campos DN deben estar separados por '/'.
[en]	dwOutType	Tipo de salida CSR. Se admite la siguiente tabla. Valor Significado P10_CSR_DER Exporta el CSR en formato DER. P10_CSR_PEM Exporta el CSR en formato PEM.
[fuera]	pdwCSRLen	Puntero al tamaño del búfer asignado en ppbCSR.
[fuera]	ppbCSR	Puntero que recibirá el CSR. El tamaño del búfer asignado estará disponible a través de pdwCSRLen. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree().
[en]	dwParam	Parámetros adicionales. Se admite la siguiente tabla. Valor Significado 0 Utiliza el hash estándar HSM en la firma CSR. CORE_P10_HASH_SHA1 Utiliza SHA-1 en la firma CSR. CORE_P10_HASH_SHA224 Utiliza SHA-224 en la firma CSR. CORE_P10_HASH_SHA256 Utiliza SHA-256 en la firma CSR. CORE_P10_HASH_SHA384 Utiliza SHA-384 en la firma CSR. CORE_P10_HASH_SHA512 Utiliza SHA-512 en la firma CSR.

Notas

Ejemplos de campo DN.

/CN=prueba

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

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ejemplos

gen_csr.c.

DAssociatePKCS11Key()

int AAP_API DAssociatePKCS11Key	(	HSESSIONCTX	hSesión,
		char *	szPriKey,
		char *	szPubKey,
		char *	szCert,
		vacío *	pvReservado,
		DWORD	dwReservado )

#include <dinamo.h>

Asocia una clave privada con un certificado y opcionalmente una clave pública siguiendo las especificaciones PKCS#11 Base v2.40 sección 4.6.3 y la utilizada por Firefox.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szPriKey	Nombre de la clave privada a asociar.
[en]	szPubKey	Nombre de la clave pública a asociar. Puede pasar NULL para evitar generar la clave pública asociada. Debe estar relacionada con la clave privada.
[en]	szCert	Nombre del certificado a exportar. Debe estar relacionado con la clave privada.
[en]	pvReservado	Reservado para uso futuro. Debe ser NULL.
[en]	dwReservado	Reservado para uso futuro. Debe ser 0.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

La asociación por defecto se basa en la utilizada por Firefox, que cambia los metadatos del objeto según la tabla siguiente.

Atributo	Valor
CKA_ID	SHA1 del módulo de clave pública. Definido para clave privada, clave pública y certificado.
CKA_LABEL	Id. del certificado. Definido para la clave privada y el certificado.
CKA_SUJETO	Asunto recuperado del certificado. Definido para la clave privada y el certificado.

En el caso de las claves EC, el CKA_ID será el hash SHA1 del valor CKA_PUBLIC_KEY_INFO.

Ver también

DImportPKCS12().

DExportPKCS12()

int AAP_API DExportPKCS12	(	const HSESSIONCTX	hSesión,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szReservado,
		BYTE **	ppbPkcs12,
		DWORD *	pdwPkcs12Len,
		DWORD	dwFlags )

#include <dinamo.h>

Exporta una clave privada y un certificado RSA en formato PKCS#12.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szPkcs12Pwd	Contraseña para el archivo PKCS#12. Pase NULL para generar PKCS#12 sin contraseña.
[en]	szKeyId	Nombre de la clave privada a exportar. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	szCertId	Nombre del certificado a exportar. Debe estar relacionado con la clave privada.
[en]	szReservado	Reservado para uso futuro. Debe ser NULL.
[fuera]	ppbPkcs12	Puntero a un puntero que contendrá el PKCS#12 generado. Esta área de datos se asignará internamente y debe liberarse utilizando DFree().
[fuera]	pdwPkcs12Len	Puntero al tamaño de los datos escritos en ppbPkcs12.
[en]	dwFlags	Pase 0 o una de las opciones de la tabla siguiente. Atributo Valor DN_EXPORT_P12_LEGACY Exporta la clave y el certificado y genera el archivo PKCS#12 en software.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

La exportación PKCS#12 con el indicador DN_EXPORT_P12_LEGACY utiliza RC2 para el cifrado de certificados, TripleDES(CBC) para el cifrado de claves y SHA1 como hash por defecto.

Ver también

DImportPKCS12Buffer() DImportPKCS12().

DImportPKCS12Buffer()

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

#include <dinamo.h>

Importa una clave privada/pública y un certificado desde un buffer en formato PKCS#12.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	pbPkcs12	PKCS#12 que se importará.
[en]	dwPkcs12Len	Tamaño del búfer que contiene PKCS#12 en pbPkcs12.
[en]	szPkcs12Pwd	Contraseña para PKCS#12. Pase NULL en caso de que no haya contraseña.
[en]	szKeyId	Nombre de la clave privada a importar. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	dwKeyAttr	Atributos de la clave privada que se desea importar Véase dwFlags en DGenerateKey() para más detalles sobre los atributos clave.
[en]	szCertId	Nombre del certificado a importar. Debe estar relacionado con la clave privada.
[en]	szPubKeyId	Nombre de la clave pública que se puede importar. Puede ser NULL si no desea que se importe la clave pública.
[en]	dwFlags	Reservado para uso futuro. Debe ser 0.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ver también

DExportPKCS12(), DImportPKCS12().

Ejemplos

pkcs7_sign.c, sign_check_pix_jws.c, sign_verify_dict.c, sign_verify_pix.c y sign_verify_xml.c.

DImportPKCS12()

int AAP_API DImportPKCS12	(	const HSESSIONCTX	hSesión,
		const char *	szPkcs12Archivo,
		const char *	szPkcs12Pwd,
		const char *	szKeyId,
		const DWORD	dwKeyAttr,
		const char *	szCertId )

#include <dinamo.h>

Importa una clave privada/pública y un certificado desde un archivo en formato PKCS#12.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szPkcs12Archivo	Nombre del archivo PKCS#12 que se va a importar.
[en]	szPkcs12Pwd	Contraseña para PKCS#12. Pase NULL en caso de que no haya contraseña.
[en]	szKeyId	Nombre de la clave privada a importar. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	dwKeyAttr	Atributos de la clave privada que se desea importar Véase dwFlags en DGenerateKey() para más detalles sobre los atributos clave.
[en]	szCertId	Nombre del certificado a importar. Debe estar relacionado con la clave privada.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Ver también

DExportPKCS12(), DImportPKCS12Buffer().

DRSAPublicKey2Info()

int AAP_API DRSAPublicKey2Info	(	BYTE *	pbKey,
		DWORD	dwKeyLen,
		DWORD	dwInForm,
		vacío *	pvPubKeyInfo,
		DWORD	dwReservado )

#include <dinamo.h>

Descifra la información de una clave pública RSA. Acepta claves públicas en formato PKCS#1 RSAPublicKey o X.509 SubjectPublicKeyInfo.

Parámetros

[en]	pbKey	Clave pública.
[en]	dwKeyLen	Tamaño del búfer pbKey.
[en]	dwInForm	Formato de introducción de claves en pbKey. Se acepta la tabla siguiente. Atributo Valor DN_FORM_DER Clave en formato DER.
[fuera]	pvPubKeyInfo	Puntero a una estructura DN_RSA_PUB_KEY_INFO.
[en]	dwReservado	Reservado para uso futuro (debe ser 0).

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DRSAPrivateKey2Info()

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

#include <dinamo.h>

Descifra la información de una clave privada RSA. Acepta claves privadas en formato PKCS#1 RSAPrivateKey o PKCS#8 PrivateKeyInfo sin cifrar.

Parámetros

[en]	pbRsa	Llave privada.
[en]	dwRsaLen	Tamaño del búfer pbRsa.
[en]	dwInForm	Formato de introducción de claves en pbRsa. Se acepta la tabla siguiente. Atributo Valor DN_FORM_DER Clave en formato DER.
[fuera]	stRsaInfo	Puntero a una estructura DN_RSA_PRIVATE_KEY_INFO.
[en]	dwReservado	Reservado para uso futuro (debe ser 0).

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

DByokExport()

int AAP_API DByokExport	(	HSESSIONCTX	hSesión,
		const char *	cszKeyId,
		const char *	cszKekId,
		DWORD	dwType,
		const void *	pvData,
		BYTE **	ppbOutData,
		DWORD *	pdwOutDataLen,
		DWORD	dwReservado )

#include <dinamo.h>

Exportar una clave en formato BYOK (Bring Your Own Key) a un proveedor de la nube.

Parámetros

[en]	hSesión	Contexto de la sesión.
[en]	cszKeyId	Identificador de la clave que se va a exportar. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.
[en]	cszKekId	Identificador de la clave KEK que se utilizará para cifrar la clave que se exportará.
[en]	dwType	Tipo de exportación. Se acepta el cuadro siguiente. Atributo Valor DN_BYOK_TYPE_AZURE Exportar clave BYOK a Azure. Pasar la estructura DN_EXPORT_BYOK_AZURE en pvData. DN_BYOK_TYPE_AWS Exportar clave BYOK a AWS. Pasar D_OAEP_SHA1_PADDING o D_OAEP_SHA2_256_PADDING. Tipo DWORD en pvData.
[en]	pvData	Puntero a una estructura de datos específica para cada tipo de exportación. Véase dwType para más detalles.
[fuera]	ppbOutData	Puntero a un puntero que contendrá los datos de salida. Esta área de datos se asignará internamente y debe liberarse utilizando DFree().
[fuera]	pdwOutDataLen	Puntero al tamaño de los datos escritos en ppbOutData.
[en]	dwReservado	Reservado para uso futuro (debe ser 0).

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.