Saltar al contenido principal
Versión: 20

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.

Ver también

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
LanzamientoModificaciones
18 R4Añadidos

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

ParámetrosTipoDescripción
settingsObject->Parámetros para generar o cargar un par de llaves
resultado4D.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

PropiedadTipoDescripción
typetextDefine el tipo de la llave 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. Tenga en cuenta que las llaves ECDSA no pueden utilizarse para el cifrado, sino sólo para la firma.
  • "PEM": carga una definición de par de llaves en formato PEM, utilizando .pem.
  • curvetextNombre de la curva ECDSA
    pemtextDefinición PEM de una llave de cifrado a cargar
    sizeintegerTamañ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
    LanzamientoModificaciones
    18 R4Añ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
    LanzamientoModificaciones
    18 R4Añadidos

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

    ParámetrosTipoDescripción
    messageText->Cadena de mensajes a decodificar utilizando options.encodingEncrypted y descifrar.
    optionsObject->Opciones de decodificación
    ResultObject<-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

    PropiedadTipoDescripción
    hashtextAlgoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
    encodingEncryptedtextCodificación utilizada para convertir el parámetro mensaje en la representación binaria a descifrar. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
    encodingDecryptedtextCodificació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.

    PropiedadTipoDescripción
    successbooleanTrue si el mensaje ha sido descifrado con éxito
    resultadotextMensaje descifrado y decodificado utilizando options.encodingDecrypted
    errorscollectionSi 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
    LanzamientoModificaciones
    18 R4Añadidos

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

    ParámetrosTipoDescripción
    messageText->Cadena de mensajes a codificar utilizando options.encodingDecrypted y encriptado.
    optionsObject->Opciones de codificación
    ResultText<-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
    PropiedadTipoDescripción
    hashtextAlgoritmo Digest a utilizar. Por ejemplo: "SHA256", "SHA384" o "SHA512".
    encodingEncryptedtextCodificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
    encodingDecryptedtextCodificació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
    LanzamientoModificaciones
    18 R4Añadidos

    .getPrivateKey() : Text

    ParámetrosTipoDescripción
    ResultText<-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
    LanzamientoModificaciones
    18 R4Añadidos

    .getPublicKey() : Text

    ParámetrosTipoDescripción
    ResultText<-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
    LanzamientoModificaciones
    18 R4Añ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
    LanzamientoModificaciones
    18 R4Añadidos

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

    ParámetrosTipoDescripción
    messageText->Cadena mensaje a firmar
    optionsObject->Opciones de firma
    ResultText<-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

    PropiedadTipoDescripción
    hashtextAlgoritmo 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@
    encodingEncryptedtextCodificación utilizada para convertir el mensaje binario encriptado en la cadena de resultados. Puede ser "Base64", o "Base64URL". Por defecto es "Base64".
    pssbooleanUtilice 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@
    encodingtextRepresentation 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
    LanzamientoModificaciones
    18 R4Añadidos

    .size : Integer

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

    .type

    Histórico
    LanzamientoModificaciones
    18 R4Añadidos

    .type : Text

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

    • "RSA": un par de llaves RSA, utilizando lsettings.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
    LanzamientoModificaciones
    18 R4Añadidos

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

    ParámetrosTipoDescripción
    messageText->Cadena mensaje utilizada para generar la firma
    signatureText->Firma a verificar, en representación Base64 o Base64URL, dependiendo del valor de options.encoding
    optionsObject->Opciones de firma
    ResultObject<-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 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

    PropiedadTipoDescripción
    hashtextAlgoritmo 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@
    pssbooleanUtilice 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@
    encodingtextEncoding 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).

    PropiedadTipoDescripción
    successbooleanTrue si la firma coincide con el mensaje
    errorscollectionSi success es false, puede contener una colección de errores