Edit

CryptoKey

La clase CryptoKey del lenguaje 4D contiene un par de llaves de cifrado asimétrico.

Esta clase está disponible en el almacén de clases de 4D.

Ejemplo

El siguiente código de ejemplo firma y verifica un mensaje utilizando un nuevo par de llaves ECDSA, por ejemplo para hacer un token web JSON ES256.

 // Generar un nuevo par de llaves ECDSA
$key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

  // Obtener la firma como base64
$message:="hello world"
$signature:=$key.sign($message;New object("hash";"SHA256"))

  // Verificar firma
$status:=$key.verify($message;$signature;New object("hash";"SHA256"))
ASSERT($status.success)

Resumen

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey      crea un nuevo objeto 4D.CryptoKey que encapsula un par de llaves de cifrado
.curve : Text     nombre de la curva normalizada de la llave
.decrypt( message : Text ; options : Object ) : Object     descifra el parámetro message utilizando la llave private
.encrypt( message : Text ; options : Object ) : Text     encripta el parámetro message utilizando la llave pública
.getPrivateKey() : Text      devuelve la llave privada del objeto CryptoKey
.getPublicKey( ) : Text      devuelve la llave pública del objeto CryptoKey
.sign (message : Text ; options : Text) : Text     firma la representación utf8 de un message string
.size : Integer     el tamaño de la llave en bits
.type : Text     Nombre del tipo de llave - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : object     verifica la firma base64 contra la representación utf8 del message

4D.CryptoKey.new()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey

Parámetros	Tipo		Descripción
parámetros	Objeto	->	Parámetros para generar o cargar un par de llaves
result	4D.CryptoKey	<-	Objeto que contiene un par de llaves de encriptación

La función 4D.CryptoKey.new() crea un nuevo objeto 4D.CryptoKey que encapsula un par de llaves de cifrado, basado en el parámetro del objeto settings. Permite generar una nueva llave RSA o ECDSA, o cargar un par de llaves existente desde una definición PEM.

parámetros

Propiedad	Tipo	Descripción
curve	texto	Nombre de la curva ECDSA
pem	texto	Definición PEM de una llave de cifrado a cargar
size	integer	Tamaño de la llave RSA en bits
type	texto	Tipo de la llave: "RSA", "ECDSA" o "PEM"

CryptoKey

El objeto CryptoKey devuelto encapsula un par de llaves de cifrado. Es un objeto compartido y, por tanto, puede ser utilizado por varios procesos 4D simultáneamente.

.curve

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.curve : Text

Definido sólo para las llaves ECDSA: el nombre de la curva normalizada de la llave. Generalmente "prime256v1" para ES256 (por defecto), "secp384r1" para ES384, "secp521r1" para ES512.

.decrypt()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.decrypt( message : Text ; options : Object ) : Object

Parámetros	Tipo		Descripción
message	Texto	->	Cadena de mensajes a decodificar utilizando options.encodingEncrypted y descifrar.
options	Objeto	->	Opciones de decodificación
Resultado	Objeto	<-	Estado

La función .decrypt() descifra el parámetro message utilizando la llave private. El algoritmo utilizado depende del tipo de la llave.

La llave debe ser una llave RSA, el algoritmo es RSA-OAEP (ver RFC 3447).

options

Propiedad	Tipo	Descripción
hash	texto	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
encodingEncrypted	texto	Codificación utilizada para convertir el parámetro mensaje en la representación binaria a descifrar. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
encodingDecrypted	texto	Codificación utilizada para convertir el mensaje binario descifrado en la cadena de resultados. Puede ser "UTF-8", "Base64" o "Base64URL". Por defecto es "UTF-8".

Resultado

La función devuelve un objeto "status" con la propiedad success definida como true si el message pudo ser descifrado con éxito.

Propiedad	Tipo	Descripción
success	booleano	True si el mensaje ha sido descifrado con éxito
result	texto	Mensaje descifrado y decodificado utilizando options.encodingDecrypted
errors	colección	Si success es false, puede contener una colección de errores

En caso de que el message no haya podido ser descifrado por no haber sido encriptado con la misma llave o algoritmo, el objeto status que se devuelve contiene una colección de errores en status.errors.

.encrypt()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.encrypt( message : Text ; options : Object ) : Text

Parámetros	Tipo		Descripción
message	Texto	->	Cadena de mensajes a codificar utilizando options.encodingDecrypted y encriptado.
options	Objeto	->	Opciones de codificación
Resultado	Texto	<-	Mensaje encriptado y codificado utilizando la opción options.encodingEncrypted

La función .encrypt() encripta el parámetro message utilizando la llave pública. El algoritmo utilizado depende del tipo de la llave.

La llave debe ser una llave RSA, el algoritmo es RSA-OAEP (ver RFC 3447).

options

Propiedad	Tipo	Descripción
hash	texto	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
encodingEncrypted	texto	Codificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
encodingDecrypted	texto	Codificación utilizada para convertir el parámetro mensaje en la representación binaria a cifrar. Puede ser "UTF-8", "Base64" o "Base64URL". Por defecto es "UTF-8".

Resultado

El valor devuelto es un mensaje encriptado.

.getPrivateKey()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.getPrivateKey() : Text

Parámetros	Tipo		Descripción
Resultado	Texto	<-	Llave privada en formato PEM

La función .getPrivateKey() devuelve la llave privada del objeto CryptoKey en formato PEM, o una cadena vacía si no hay ninguna disponible.

Resultado

El valor devuelto es la llave privada.

.getPublicKey()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.getPublicKey( ) : Text

Parámetros	Tipo		Descripción
Resultado	Texto	<-	Llave pública en formato PEM

La función .getPublicKey() devuelve la llave pública del objeto CryptoKey en formato PEM, o una cadena vacía si no hay ninguna disponible.

Resultado

El valor devuelto es la llave pública.

---## .pem

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.pem : Text

Definición PEM de una llave de encriptación a cargar<! -- END REF -->. Si la llave es una llave privada, se deducirá de ella la llave pública RSA o ECDSA.

.sign()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.sign (message : Text ; options : Text) : Text

Parámetros	Tipo		Descripción
message	Texto	->	Cadena mensaje a firmar
options	Objeto	->	Opciones de firma
Resultado	Texto	<-	Firma en representación Base64 o Base64URL, según la opción "encoding

La función .sign() firma la representación utf8 de un message string utilizando las llaves del objeto CryptoKey y las options suministradas. Devuelve su firma en formato base64 o base64URL, dependiendo del valor del atributo options.encoding que haya pasado.

CryptoKey debe contener una llave válida privada.

options

Propiedad	Tipo	Descripción
hash	texto	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512". Cuando se utiliza para producir un JWT, el tamaño del hash debe coincidir con el tamaño del algoritmo PS@, ES@, RS@ o PS@
encodingEncrypted	texto	Codificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
pss	booleano	Utilice el Probabilistic Signature Scheme (PSS). Se ignora si la llave no es una llave RSA. Pase true al producir un JWT para el algoritmo PS@
encoding	texto	Representación que se utilizará para la firma de resultados. Los valores posibles son "Base64" o "Base64URL". Por defecto es "Base64".

Resultado

CryptoKey debe contener una llave válida privada.

.size

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.size : Integer

Definido sólo para llaves RSA: el tamaño de la llave en bits. Normalmente 2048 (por defecto).

.type

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.type : Text

Nombre del tipo de llave - "RSA", "ECDSA", "PEM"

"RSA": un par de llaves RSA, utilizando settings.size como .size.

"ECDSA": un par de llaves del Algoritmo de Firma Digital de Curva Elíptica, utilizando settings.curve como .curve. Tenga en cuenta que las llaves ECDSA no pueden utilizarse para el cifrado, sino sólo para la firma.

"PEM": una definición de par de llaves en formato PEM, utilizando settings.pem como .pem.

.verify()

Histórico

Versión	Modificaciones
v18 R4	Añadidos

.verify( message : Text ; signature : Text ; options : Object) : object

Parámetros	Tipo		Descripción
message	Texto	->	Cadena mensaje utilizada para generar la firma
signature	Texto	->	Firma a verificar, en representación Base64 o Base64URL, dependiendo del valor de options.encoding
options	Objeto	->	Opciones de firma
Resultado	Objeto	<-	Estado de la verificación

Representación utf8 de la cadena message.

La función .verify() verifica la firma base64 contra la representación utf8 del message utilizando las llaves del objeto CryptoKey y las options proporcionadas.

options

Propiedad	Tipo	Descripción
hash	texto	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512". Cuando se utiliza para producir un JWT, el tamaño del hash debe coincidir con el tamaño del algoritmo PS@, ES@, RS@ o PS@
pss	booleano	Utilice el Probabilistic Signature Scheme (PSS). Se ignora si la llave no es una llave RSA. Pase true al verificar un JWT para el algoritmo PS@
encoding	texto	Representación de la firma facilitada. Puede ser "Base64" o "Base64URL". Por defecto es "Base64".

Resultado

La CryptoKey debe contener una llave pública válida.

La función devuelve un objeto de estado con la propiedad success definida como true si el message pudo ser verificado con éxito (es decir, la firma coincide).

Propiedad	Tipo	Descripción
success	booleano	True si la firma coincide con el mensaje
errors	colección	Si success es false, puede contener una colección de errores