Versión: 20 R5 BETA

CryptoKey

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

Esta clase está disponible en el "class store" 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 privada
.encrypt( message : Text ; options : Object ) : Text cifra 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 : Object) : Text firma la representación utf8 de una cadena de message
.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()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

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

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

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

settings

Propiedad	Tipo	Descripción
type	text	Define el tipo de clave a crear: "RSA": genera un par de llaves RSA, utilizando .size como tamaño. "ECDSA": genera un par de llaves Elliptic Curve Digital Signature Algorithm, utilizando .curve como curva. Note that ECDSA keys cannot be used for encryption but only for signature. "PEM": loads a key pair definition in PEM format, using .pem.
curve	text	Nombre de la curva ECDSA
pem	text	Definición PEM de una llave de cifrado a cargar
size	integer	Tamaño de la llave RSA en bits

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

Historia

Lanzamiento	Modificaciones
18 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()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

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

Parámetros	Tipo		Descripción
message	Text	->	Cadena mensaje que se descodificará utilizando `options.encodingEncrypted` y se descifrará.
options	Object	->	Opciones de decodificación
Result	Object	<-	Estado

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

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

opciones

Propiedad	Tipo	Descripción
hash	text	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
encodingEncrypted	text	Codificación utilizada para convertir el parámetro `message` en la representación binaria a descifrar. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
encodingDecrypted	text	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 en true si el message pudo ser desencriptado con éxito.

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

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

.encrypt()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

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

Parámetros	Tipo		Descripción
message	Text	->	Cadena mensaje a codificar utilizando `options.encodingDecrypted` y encriptada.
options	Object	->	Opciones de codificación
Result	Text	<-	Mensaje encriptado y codificado utilizando la opción `options.encodingEncrypted`

La función .encrypt() cifra 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).

opciones

Propiedad	Tipo	Descripción
hash	text	Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
encodingEncrypted	text	Codificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
encodingDecrypted	text	Codificación utilizada para convertir el parámetro `message` 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()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

.getPrivateKey() : Text

Parámetros	Tipo		Descripción
Result	Text	<-	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 está disponible.

Resultado

El valor devuelto es la llave privada.

.getPublicKey()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

.getPublicKey() : Text

Parámetros	Tipo		Descripción
Result	Text	<-	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

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

.pem : Text

Definición PEM de una llave de cifrado a cargar. Si la llave es una llave privada, se deducirá de ella la llave pública RSA o ECDSA.

.sign()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

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

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

La función .sign() firma la representación utf8 de una cadena de message 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 le haya pasado.

La CryptoKey debe contener una llave privada válida.

opciones

Propiedad	Tipo	Descripción
hash	text	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	text	Codificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
pss	boolean	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	text	Representation of provided signature. Possible values are "Base64" or "Base64URL". Por defecto es "Base64".

Resultado

La representación utf8 de la cadena message.

.size

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

.size : Integer

Definido sólo para llaves RSA: el tamaño de la llave en bits. .

.type

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

.type : Text

Contiene el nombre del tipo de llave - "RSA", "ECDSA", "PEM" .

"RSA": un par de llaves RSA, utilizando settings.size como .size.
"ECDSA": un par de llaves Elliptic Curve Digital Signature Algorithm, 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": definición de par de llaves en formato PEM, utilizando settings.pem como .pem.

.verify()

Historia

Lanzamiento	Modificaciones
18 R4	Añadidos

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

Parámetros	Tipo		Descripción
message	Text	->	Cadena mensaje utilizada para generar la firma
signature	Text	->	Firma a verificar, en representación Base64 o Base64URL, según el valor de `options.encoding`
options	Object	->	Opciones de firma
Result	Object	<-	Estado de la verificación

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

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

opciones

Propiedad	Tipo	Descripción
hash	text	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	boolean	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	text	Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Por defecto es "Base64".

Resultado

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

En caso de que la firma no se haya podido verificar porque no se ha firmado con el mismo message, llave o algoritmo, el objeto status que se devuelve contiene una colección de errores en status.errors.

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

Ejemplo​

Resumen​

4D.CryptoKey.new()​

settings​

CryptoKey​

.curve​

.decrypt()​

opciones​

Resultado​

.encrypt()​

opciones​

Resultado​

.getPrivateKey()​

Resultado​

.getPublicKey()​

Resultado​

.pem​

.sign()​

opciones​

Resultado​

.size​

.type​

.verify()​

opciones​

Resultado​

Ejemplo

Resumen

4D.CryptoKey.new()

settings

CryptoKey

.curve

.decrypt()

opciones

Resultado

.encrypt()

opciones

Resultado

.getPrivateKey()

Resultado

.getPublicKey()

Resultado

.pem

.sign()

opciones

Resultado

.size

.type

.verify()

opciones

Resultado