Aller au contenu principal
Version: 19

CryptoKey

La classe CryptoKey du langage 4D contient une paire de clés de chiffrement asymétrique.

Cette classe est disponible depuis le "class store" de 4D.

Voir aussi

For a comprehensive overview of this class, please refer to the CryptoKey: encrypt, decrypt, sign, and verify! blog post.

Sommaire

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey
creates a new 4D.CryptoKey object encapsulating an encryption key pair
.curve : Texte
nom normalisé de la courbe de la clé
.decrypt( message : Text ; options : Object ) : Object
déchiffre le paramètre message à l'aide de la clé privée
.encrypt( message : Text ; options : Object ) : Text
crypte le paramètre message à l'aide de la clé publique
.getPrivateKey() : Text
retourne la clé privée de l'objet CryptoKey
.getPublicKey() : Text
retourne la clé publique de l'objet CryptoKey
.sign (message : Text ; options : Object) : Text
signe la représentation utf8 de la chaîne message
.size : Integer
la taille de la clé en octets
.type : Texte
nom du type de clé - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : object
vérifie la signature base64 par rapport à la représentation utf8 du message

4D.CryptoKey.new()

Historique
ReleaseModifications
18 R4Ajout

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

ParamètresTypeDescription
settingsObject->Settings to generate or load a key pair
result4D.CryptoKey<-Objet contenant une paire de clés de chiffrement

The 4D.CryptoKey.new() function creates a new 4D.CryptoKey object encapsulating an encryption key pair, based upon the settings object parameter. It allows to generate a new RSA or ECDSA key, or to load an existing key pair from a PEM definition.

settings

PropriétéTypeDescription
typetextDéfinit le type de la clé à créer :
  • "RSA" : génère une paire de clés RSA, en utilisant .size comme taille.
  • "ECDSA" : génère une paire de clés Elliptic Curve Digital Signature Algorithm, en utilisant .curve comme courbe. A noter que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.
  • "PEM" : charge une définition de paire de clés au format PEM, en utilisant .pem.
  • curvetextNom de la courbe ECDSA
    pemtextDéfinition PEM d'une clé de chiffrement à charger
    sizeintegerTaille de la clé RSA en octets

    CryptoKey

    The returned CryptoKey object encapsulates an encryption key pair. It is a shared object and can therefore be used by multiple 4D processes simultaneously.

    Exemple 1

    Un message est signé par une clé privée et la signature est vérifiée par la clé publique correspondante. Le code suivant signe et vérifie une signature de message simple.

    • Côté bob :
    // Créer le message
    $message:="hello world"
    Folder(fk desktop folder).file("message.txt").setText($message)

    // Créer une clé
    $type:=New object("type";"RSA")
    $key:=4D.CryptoKey.new($type)

    // Récupérer et stocker une clé publique
    Folder(fk desktop folder).file("public.pem").setText($key.getPublicKey())

    // Récupérer et stocker une signature en base64
    Folder(fk desktop folder).file("signature").setText($key.sign($message;$type))

    /*Bob envoie le message, la clé publique et la signature à Alice*/
    • Côté Alice :
    // Get message, public key & signature
    $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").getText()

    // Create a key
    $type:=New object("type";"PEM";"pem";$publicKey)
    $key:=4D.CryptoKey.new($type)

    // Verify signature
    If ($key.verify($message;$signature;$type).success)
    // The signature is valid

    End if

    Exemple 2

    L'extrait de code suivant illustre la signature et la vérification d'un message à l'aide d'une nouvelle paire de clés ECDSA, afin de créer, par exemple, un token Web JSON ES256.

     // Générer une nouvelle paire de clés ECDSA
    $key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

    // Obtenir une signature en base64
    $message:="hello world"
    $signature:=$key.sign($message;New object("hash";"SHA256"))

    // Vérifier la signature
    $status:=$key.verify($message;$signature;New object("hash";"SHA256"))
    ASSERT($status.success)

    .curve

    Historique
    ReleaseModifications
    18 R4Ajout

    .curve : Texte

    Défini uniquement pour les clés ECDSA : le nom normalisé de la courbe de la clé. Généralement "prime256v1" pour ES256 (défaut), "secp384r1" pour ES384, "secp521r1" pour ES512.

    .decrypt()

    Historique
    ReleaseModifications
    18 R4Ajout

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

    ParamètresTypeDescription
    messageText->Chaine message à déchiffrer à l'aide de options.encodingEncrypted et decrypted.
    optionsObject->Options de décodage
    RésultatObject<-Statut

    La fonction .decrypt() déchiffre le paramètre message à l'aide de la clé privée. L'algorithme utilisé dépend du type de clé.

    La clé doit être une clé RSA, l'algorithme est RSA-OAEP (voir RFC 3447).

    options

    PropriétéTypeDescription
    hashtextAlgorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512".
    encodingEncryptedtextChiffrement utilisé pour convertir le paramètre message en représentation binaire à déchiffrer. Peut être "Base64" ou "Base64URL". La valeur par défaut est "Base64".
    encodingDecryptedtextEncodage utilisé pour convertir le message binaire déchiffré en chaîne de résultat. Peut être "UTF-8", "Base64" ou "Base64URL". La valeur par défaut est "UTF-8".

    Résultat

    La fonction renvoie un objet "status" avec la propriété success définie sur true si le message a pu être déchiffré avec succès.

    PropriétéTypeDescription
    successbooleanTrue si le message a été déchiffré avec succès
    resulttextMessage déchiffré et décodé à l'aide de options.encodingDecrypted
    errorscollectionSi success est mis sur false, il peut contenir une collection d'erreurs

    Si le message n'a pas pu être déchiffré parce qu'il n'a pas été chiffré avec la même clé ou le même algorithme, l'objet status renvoyé contient une collection d'erreurs dans status.errors.

    .encrypt()

    Historique
    ReleaseModifications
    18 R4Ajout

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

    ParamètresTypeDescription
    messageText->Chaine message à chiffrer à l'aide de options.encodingDecrypted et encrypted.
    optionsObject->Options de chiffrement
    RésultatText<-Message encrypted and encoded using the options.encodingEncrypted

    La fonction .encrypt() crypte le paramètre message à l'aide de la clé publique. L'algorithme utilisé dépend du type de clé.

    La clé doit être une clé RSA, l'algorithme est RSA-OAEP (voir RFC 3447).

    options
    PropriétéTypeDescription
    hashtextAlgorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512".
    encodingEncryptedtextChiffrement utilisé pour convertir le message chiffré binaire en chaîne de résultat. Peut être "Base64" ou "Base64URL". La valeur par défaut est "Base64".
    encodingDecryptedtextChiffrement utilisé pour convertir le paramètre message en représentation binaire à chiffrer. Peut être "UTF-8", "Base64" ou "Base64URL". La valeur par défaut est "UTF-8".

    Résultat

    La valeur retournée est un message chiffré.

    .getPrivateKey()

    Historique
    ReleaseModifications
    18 R4Ajout

    .getPrivateKey() : Text

    ParamètresTypeDescription
    RésultatText<-Clé primaire au format PEM

    La fonction .getPrivateKey() retourne la clé privée de l'objet CryptoKey au format PEM, ou une chaîne vide si aucune n'est disponible.

    Résultat

    La valeur retournée est la clé privée.

    .getPublicKey()

    Historique
    ReleaseModifications
    18 R4Ajout

    .getPublicKey() : Text

    ParamètresTypeDescription
    RésultatText<-Clé publique au format PEM

    La fonction getPublicKey() retourne la clé publique de l'objet CryptoKey au format PEM, ou une chaîne vide si aucune n'est disponible.

    Résultat

    La valeur retournée est la clé publique.


    .pem

    Historique
    ReleaseModifications
    18 R4Ajout

    .pem : Text

    Définition PEM d'une clé de chiffrement à charger. Si la clé est une clé privée, la clé publique RSA ou ECDSA en sera déduite.

    .sign()

    Historique
    ReleaseModifications
    18 R4Ajout

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

    ParamètresTypeDescription
    messageText->Chaîne message à signer
    optionsObject->Options de signature
    RésultatText<-Signature en représentation Base64 ou Base64URL, selon l'option "encoding"

    La fonction sign() signe la représentation utf8 de la chaîne message à l'aide des clés objet CryptoKey et des options fournies. Elle retourne sa signature au format base64 ou base64URL, selon la valeur de l'attribut options.encoding que vous avez passé.

    CryptoKey doit contenir une clé privée valide.

    options

    PropriétéTypeDescription
    hashtextAlgorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512". Lorsqu'elle est utilisée pour produire un JWT, la taille du hachage doit correspondre à la taille de l'algorithme PS@, ES@, RS@ ou PS@
    encodingEncryptedtextChiffrement utilisé pour convertir le message chiffré binaire en chaîne de résultat. Peut être "Base64" ou "Base64URL". La valeur par défaut est "Base64".
    pssbooleanUtilise le Probabilistic Signature Scheme (PSS). Ignoré si la clé n'est pas une clé RSA. Passez true lors de la production d'un JWT pour l'algorithme PS@
    encodingtextReprésentation à utiliser pour la signature. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64".

    Résultat

    La représentation utf8 de la chaîne message.

    .size

    Historique
    ReleaseModifications
    18 R4Ajout

    .size : Integer

    Défini uniquement pour les clés RSA : la taille de la clé en octets. Habituellement 2048 (par défaut).

    .type

    Historique
    ReleaseModifications
    18 R4Ajout

    .type : Texte

    Contient le nom du type de clé - "RSA", "ECDSA", "PEM" .

    • "RSA" : paire de clés RSA, utilise settings.size pour la .size.
    • "ECDSA" : paire de clés Elliptic Curve Digital Signature Algorithm, utilise settings.curve pour la propriété .curve. A noter que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.
    • "PEM" : Définition de paire de clés au format PEM, utilise settings.pem pour la propriété .pem.

    .verify()

    Historique
    ReleaseModifications
    18 R4Ajout

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

    ParamètresTypeDescription
    messageText->Chaîne message utilisée pour générer la signature
    signatureText->Signature à vérifier, en représentation Base64 ou Base64URL, selon la valeur options.encoding
    optionsObject->Options de signature
    RésultatObject<-Statut de la vérification

    La fonction .verify() vérifie la signature base64 par rapport à la représentation utf8 du message à l'aide des clés objet CryptoKey et des options fournies.

    La CryptoKey doit contenir une clé publique valide.

    options

    PropriétéTypeDescription
    hashtextAlgorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512". Lorsqu'elle est utilisée pour produire un JWT, la taille du hachage doit correspondre à la taille de l'algorithme PS@, ES@, RS@ ou PS@
    pssbooleanUtilise le Probabilistic Signature Scheme (PSS). Ignoré si la clé n'est pas une clé RSA. Passez true lors de la vérification d'un JWT pour l'algorithme PS@
    encodingtextReprésentation de la signature fournie. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64".

    Résultat

    La fonction retourne un objet status avec la propriété success définie sur true si le message a pu être déchiffré avec succès (c'est-à-dire si la signature est correspondante).

    La fonction retourne un objet status avec la propriété success définie sur true si le message a pu être déchiffré avec succès (c'est-à-dire si la signature est correspondante).

    PropriétéTypeDescription
    successbooleanTrue si la signature correspond au message
    errorscollectionSi success est mis sur false, il peut contenir une collection d'erreurs