Aller au contenu principal
Version: Next

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 également

Pour une vue d'ensemble complète de cette classe, veuillez vous reporter au blog CryptoKey : chiffrer, déchiffrer, signer et vérifier!.

Sommaire

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey
crée un nouvel objet 4D.CryptoKey encapsulant une paire de clés de chiffrement
.curve : Text
nom de la courbe normalisée de la clé
.decrypt( message : Text ; options : Object ) : Object
déchiffre le paramètre message en utilisant la clé privée
.encrypt( message : Text ; options : Object ) : Text
chiffre le paramètre message à l'aide de la clé publique
.getPrivateKey() : Text
renvoie la clé privée de l'objet CryptoKey
.getPublicKey() : Text
renvoie la clé publique de l'objet CryptoKey
.sign (message : Text ; options : Object) : Text
.sign (message : Blob ; options : Object) : Text

signs the utf8 representation of a message string or Blob
.size : Integer
la taille de la clé en bits
.type : Text
nom du type de clé - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : Object
*.verify**( message : Blob ; 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->Paramètres pour générer ou charger une paire de clés
Résultat4D.CryptoKey<-Objet contenant une paire de clés de chiffrement

La fonction 4D.CryptoKey.new() crée un nouvel objet 4D.CryptoKey encapsulant une paire de clés de chiffrement, en fonction du paramètre settings. Elle permet de générer une nouvelle clé RSA ou ECDSA, ou de charger une paire de clés existante à partir de la définition PEM.

settings

PropriétéTypeDescription
typetextDéfinit le type de 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. Notez 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

    L'objet CryptoKey retourné encapsule une paire de clés de chiffrement. C'est un objet partagé qui peut donc être utilisé simultanément par plusieurs process 4D.

    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 :
    // Récupérer le message, la clé publique et la 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()

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

    // Vérifier la signature
    If ($key.verify($message;$signature;$type).success)
    // La signature est valide

    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 : Text

    Défini uniquement pour les clés ECDSA : le nom de la courbe normalisée 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 en utilisant 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".

    Result

    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
    RésultattextMessage déchiffré et décodé à l'aide de options.encodingDecrypted
    errorscollectionSi success est false, 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 chiffré et encodé à l'aide de options.encodingEncrypted

    La fonction .encrypt() chiffre 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".

    Result

    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() renvoie la clé privée de l'objet CryptoKey au format PEM, ou une chaîne vide s'il n'y en a pas.

    Result

    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() renvoie la clé publique de l'objet CryptoKey au format PEM, ou une chaîne vide s'il n'y en a pas.

    Result

    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
    20 R8Support of message as Blob
    18 R4Ajout

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

    ParamètresTypeDescription
    messageText OR Blob->Message to sign
    optionsObject->Options de signature
    RésultatText<-Signature en représentation Base64 ou Base64URL, selon l'option "encoding"

    The .sign() function signs the utf8 representation of a message string or Blob using the CryptoKey object keys and provided options. 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@
    encodingtextRepresentation to be used for result signature. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64".

    Result

    The utf8 representation of the message.

    .size

    Historique
    ReleaseModifications
    18 R4Ajout

    .size : Integer

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

    .type

    Historique
    ReleaseModifications
    18 R4Ajout

    .type : Text

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

    • "RSA" : paire de clés RSA, utilise settings.size pour la taille .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
    20 R8Support of message as Blob
    18 R4Ajout

    .verify( message : Text ; signature : Text ; options : Object) : Object
    *.verify**( message : Blob ; signature : Text ; options : Object) : Object

    ParamètresTypeDescription
    messageText OR Blob->Message that was used to produce the 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 en utilisant les clés de l'objet CryptoKey et les 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".

    Result

    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 false, peut contenir une collection d'erreurs