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
.
Para obtener una visión general de esta clase, consulte la página CryptoKey: ¡Cifrar, descifrar, firmar y verificar! en el blog.
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 mensaje utilizando la llave privada |
.encrypt( message : Text ; options : Object ) : Text encripta el parámetro mensaje 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 mensaje |
.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 mensaje |
4D.CryptoKey.new()
Histórico
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 |
resultado | 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, basado en el parámetro objeto 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 la llave a crear: |
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.
Ejemplo 1
Un mensaje está firmado por una llave privada y la firma es verificada por la llave pública correspondiente. El siguiente código firma y verifica una firma de mensaje simple.
- Lado bob:
// Crear el mensaje
$message:="hello world"
Folder(fk desktop folder).file("message.txt").setText($message)
// Crear una clave
$type:=New object("type";"RSA")
$key:=4D.CryptoKey.new($type)
// Obtener la llave pública y guardarla
Folder(fk desktop folder).file("public.pem").setText($key.getPublicKey())
// Obtener firma como base64 y guardarla
Folder(fk desktop folder).file("signature").setText($key.sign($message;$type))
/*Bob envía el mensaje, la llave pública y la firma a Alice*/
- Lado Alice:
// Obtener mensaje, llave pública y firma
$message:=Folder(fk desktop folder).file("message.txt").getText()
$publicKey:=Folder(fk desktop folder).file("public.pem").getText()
$signature:=Folder(fk desktop folder).file("signature"). etText()
// Crear una llave
$type:=New object("type";"PEM";"pem";$publicKey)
$key:=4D.CryptoKey.new($type)
// Verificar la firma
If ($key.verify($message;$signature;$type).success)
// La firma es válida
End if
Ejemplo 2
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)
.curve
Histórico
Lanzamiento | Modificaciones |
---|---|
18 R4 | Añadidos |
.curve : Text
Definido sólo para 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
Lanzamiento | Modificaciones |
---|---|
18 R4 | Añadidos |
.decrypt( message : Text ; options : Object ) : Object
Parámetros | Tipo | Descripción | |
---|---|---|---|
message | Text | -> | Cadena de mensajes a decodificar utilizando options.encodingEncrypted y descifrar. |
options | Object | -> | Opciones de decodificación |
Result | Object | <- | Estado |
La función .decrypt()
descifra el parámetro mensaje 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).
options
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 mensaje 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". |
Result
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 | boolean | True si el mensaje ha sido descifrado con éxito |
resultado | 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 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
Lanzamiento | Modificaciones |
---|---|
18 R4 | Añadidos |
.encrypt( message : Text ; options : Object ) : Text
Parámetros | Tipo | Descripción | |
---|---|---|---|
message | Text | -> | Cadena de mensajes a codificar utilizando options.encodingDecrypted y encriptado. |
options | Object | -> | Opciones de codificación |
Result | Text | <- | Mensaje encriptado y codificado utilizando la opción options.encodingEncrypted |
La función .encrypt()
encripta el parámetro mensaje 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 | 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 mensaje en la representación binaria a cifrar. Puede ser "UTF-8", "Base64", o "Base64URL". Por defecto es "UTF-8". |
Result
El valor devuelto es un mensaje encriptado.
.getPrivateKey()
Histórico
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 hay ninguna disponible.
Result
El valor devuelto es la llave privada.
.getPublicKey()
Histórico
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.
Result
El valor devuelto es la llave pública.
.pem
Histórico
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()
Histórico
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 mensaje utilizando las llaves del objeto CryptoKey
y las opciones 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 | 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". |
Result
CryptoKey
debe contener una llave válida privada.
.size
Histórico
Lanzamiento | Modificaciones |
---|---|
18 R4 | Añadidos |
.size : Integer
Definido sólo para llaves RSA: el tamaño de la llave en bits. .
.type
Histórico
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 l
settings.size
como .size. - "ECDSA": un par de llaves del Algoritmo 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": una definición de par de llaves en formato PEM, utilizando
settings.pem
como .pem.
.verify()
Histórico
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, dependiendo del 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 mensaje utilizando las llaves del objeto CryptoKey
y las opciones suministradas.
La CryptoKey
debe contener una llave pública válida.
options
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". |
Result
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 | boolean | True si la firma coincide con el mensaje |
errors | collection | Si success es false , puede contener una colección de errores |