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
.
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 signe la représentation utf8 d'une chaîne de message |
.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 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 | -> | Settings to generate or load a key pair |
result | 4D.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. It allows to generate a new RSA or ECDSA key, or to load an existing key pair from a PEM definition.
settings
Propriété | Type | Description |
---|---|---|
type | text | Définit le type de clé à créer : " |
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. 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 :
// 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 : 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
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 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é | 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". |
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é | Type | Description |
---|---|---|
success | boolean | True si le message a été déchiffré avec succès |
result | text | Message déchiffré et décodé à l'aide de options.encodingDecrypted |
errors | collection | Si 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
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()
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é | 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". |
Result
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()
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
Release | Modifications |
---|---|
18 R4 | Ajout |
.getPublicKey() : Text
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Text | <- | 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
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 d'une chaîne de message en utilisant les clés de l'objet CryptoKey
et les 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". |
Result
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 bits. Habituellement 2048 (par défaut).
.type
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.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
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 en utilisant les clés de l'objet CryptoKey
et les 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". |
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é | Type | Description |
---|---|---|
success | boolean | True si la signature correspond au message |
errors | collection | Si success est false , peut contenir une collection d'erreurs |