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
.
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
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 |
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é | Type | Description |
---|---|---|
type | text | Définit le type de la 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
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
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 |
result | 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 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é | 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).
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 |