CryptoKey
The CryptoKey
class in the 4D language encapsulates an asymmetric encryption key pair.
This class is available from the 4D
class store.
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
creates a new 4D.CryptoKey
object encapsulating an encryption key pair |
| .curve : Text
nombre de la curva normalizada de la llave |
| .decrypt( message : Text ; options : Object ) : Object
decrypts the message parameter using the private key |
| .encrypt( message : Text ; options : Object ) : Text
encrypts the message parameter using the public key |
| .getPrivateKey() : Text
returns the private key of the CryptoKey
object |
| .getPublicKey() : Text
returns the public key of the CryptoKey
object |
| .sign (message : Text ; options : Object) : Text
signs the utf8 representation of a message string |
| .size : Integer
el tamaño de la llave en bits |
| .type : Text
name of the key type - "RSA", "ECDSA", "PEM" |
| .verify( message : Text ; signature : Text ; options : Object) : object
verifies the base64 signature against the utf8 representation of 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 |
The 4D.CryptoKey.new()
function creates a new 4D.CryptoKey
object encapsulating an encryption key pair, based upon the settings object parameter. 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 | Defines the type of the key to create: |
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
The returned CryptoKey
object encapsulates an encryption key pair. 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 | -> | Message string to be decoded using options.encodingEncrypted and decrypted. |
options | Object | -> | Opciones de decodificación |
Result | Object | <- | Estado |
The .decrypt()
function decrypts the message parameter using the private key. El algoritmo utilizado depende del tipo de la llave.
The key must be a RSA key, the algorithm is RSA-OAEP (see RFC 3447).
opciones
Propiedad | Tipo | Descripción |
---|---|---|
hash | text | Algoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512". |
encodingEncrypted | text | Encoding used to convert the message parameter into the binary representation to decrypt. 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
The function returns a status object with success
property set to true
if the message could be successfully decrypted.
Propiedad | Tipo | Descripción |
---|---|---|
success | boolean | True si el mensaje ha sido descifrado con éxito |
result | text | Message decrypted and decoded using the options.encodingDecrypted |
errors | collection | If success is false , may contain a collection of errors |
In case the message couldn't be decrypted because it was not encrypted with the same key or algorithm, the status
object being returned contains an error collection in status.errors
.
.encrypt()
Historia
Lanzamiento | Modificaciones |
---|---|
18 R4 | Añadidos |
.encrypt( message : Text ; options : Object ) : Text
Parámetros | Tipo | Descripción | |
---|---|---|---|
message | Text | -> | Message string to be encoded using options.encodingDecrypted and encrypted. |
options | Object | -> | Opciones de codificación |
Result | Text | <- | Message encrypted and encoded using the options.encodingEncrypted |
The .encrypt()
function encrypts the message parameter using the public key. El algoritmo utilizado depende del tipo de la llave.
The key must be a RSA key, the algorithm is RSA-OAEP (see 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 | Encoding used to convert the message parameter into the binary representation to encrypt. 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 |
The .getPrivateKey()
function returns the private key of the CryptoKey
object in PEM format, or an empty string if none is available.
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 |
The .getPublicKey()
function returns the public key of the CryptoKey
object in PEM format, or an empty string if none is available.
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 |
The .sign()
function signs the utf8 representation of a message string using the CryptoKey
object keys and provided options. It returns its signature in base64 or base64URL format, depending on the value of the options.encoding
attribute you passed.
The CryptoKey
must contain a valid private key.
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. Pass true when producing a JWT for PS@ algorithm |
encoding | text | Representation of provided signature. Possible values are "Base64" or "Base64URL". Por defecto es "Base64". |
Resultado
The utf8 representation of the message string.
.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
Contains the name of the key type - "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": a key pair definition in PEM format, using
settings.pem
as .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 | -> | Signature to verify, in Base64 or Base64URL representation, depending on options.encoding value |
options | Object | -> | Opciones de firma |
Result | Object | <- | Estado de la verificación |
The .verify()
function verifies the base64 signature against the utf8 representation of message using the CryptoKey
object keys and provided options.
The CryptoKey
must contain a valid public key.
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. Pass true when verifying a JWT for PS@ algorithm |
encoding | text | Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Por defecto es "Base64". |
Resultado
The function returns a status object with success
property set to true
if message
could be successfully verified (i.e. the signature matches).
In case the signature couldn't be verified because it was not signed with the same message, key or algorithm, the status
object being returned contains an error collection in status.errors
.
Propiedad | Tipo | Descripción |
---|---|---|
success | boolean | True si la firma coincide con el mensaje |
errors | collection | If success is false , may contain a collection of errors |