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

Pour une présentation complète de cette classe, nous vous recommandons de lire l'article de blog CryptoKey : crypter, décrypter, signer et vérifier !.

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

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
settings	Object	->	Paramètres pour générer ou charger une paire de clés
Résultat	4D.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. 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é	Type	Description
type	text	Dé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.
curve	text	Nom de la courbe ECDSA
pem	text	Définition PEM d'une clé de chiffrement à charger
size	integer	Taille 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

Release	Modifications
18 R4	Ajout

.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

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
message	Text	->	Chaine message à déchiffrer à l'aide de `options.encodingEncrypted` et decrypted.
options	Object	->	Options de décodage
Résultat	Object	<-	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é	Type	Description
hash	text	Algorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512".
encodingEncrypted	text	Chiffrement 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".
encodingDecrypted	text	Encodage 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é	Type	Description
success	boolean	True si le message a été déchiffré avec succès
Résultat	text	Message déchiffré et décodé à l'aide de `options.encodingDecrypted`
errors	collection	Si `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

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
message	Text	->	Chaine message à chiffrer à l'aide de `options.encodingDecrypted` et encrypted.
options	Object	->	Options de chiffrement
Résultat	Text	<-	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é	Type	Description
hash	text	Algorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512".
encodingEncrypted	text	Chiffrement 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".
encodingDecrypted	text	Chiffrement 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

Release	Modifications
18 R4	Ajout

.getPrivateKey() : Text

Paramètres	Type		Description
Résultat	Text	<-	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

Release	Modifications
18 R4	Ajout

.getPublicKey() : Text

Paramètres	Type		Description
Résultat	Text	<-	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

Release	Modifications
18 R4	Ajout

.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

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
message	Text	->	Chaîne message à signer
options	Object	->	Options de signature
Résultat	Text	<-	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é	Type	Description
hash	text	Algorithme 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@
encodingEncrypted	text	Chiffrement 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".
pss	boolean	Utilise 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@
encoding	text	Repré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

Release	Modifications
18 R4	Ajout

.size : Integer

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

.type

Historique

Release	Modifications
18 R4	Ajout

.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

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
message	Text	->	Chaîne message utilisée pour générer la signature
signature	Text	->	Signature à vérifier, en représentation Base64 ou Base64URL, selon la valeur `options.encoding`
options	Object	->	Options de signature
Résultat	Object	<-	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é	Type	Description
hash	text	Algorithme 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@
pss	boolean	Utilise 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@
encoding	text	Repré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).

Propriété	Type	Description
success	boolean	True si la signature correspond au message
errors	collection	Si `success` est mis sur `false`, il peut contenir une collection d'erreurs

Sommaire​

4D.CryptoKey.new()​

settings​

CryptoKey​

Exemple 1​

Exemple 2​

.curve​

.decrypt()​

options​

Résultat​

.encrypt()​

options​

Résultat​

.getPrivateKey()​

Résultat​

.getPublicKey()​

Résultat​

.pem​

.sign()​

options​

Résultat​

.size​

.type​

.verify()​

options​

Résultat​

Sommaire

4D.CryptoKey.new()

settings

CryptoKey

Exemple 1

Exemple 2

.curve

.decrypt()

options

Résultat

.encrypt()

options

Résultat

.getPrivateKey()

Résultat

.getPublicKey()

Résultat

.pem

.sign()

options

Résultat

.size

.type

.verify()

options

Résultat