Aller au contenu principal
Version: v19

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.

Exemple

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)

Sommaire

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey    crée un nouvel objet 4D.CryptoKey CryptoKeyencapsulant une paire de clés de chiffrement
.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
VersionModifications
v18 R4Ajout

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

ParamètresTypeDescription
settingsObject->Paramètres pour générer ou charger une paire de clés
result4D.CryptoKey<-Objet contenant une paire de clés de chiffrement

|

La fonction .4D.CryptoKey.new() crée un nouvel objet 4D.CryptoKey CryptoKeyencapsulant 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 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
    sizeentierTaille de la clé RSA en octets

    CryptoKey

    L'objet CryptoKey retourné encapsule une paire de clés de chiffrement. C'est un objet partagé et peut être alors utilisé par de multiples traitements 4D simultanés.

    .curve

    Historique
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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() 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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
    VersionModifications
    v18 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

    |