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 creates a new |
.curve : Texte nom de la courbe normalisée de la clé. |
.decrypt( message : Text ; options : Object ) : Object déchiffre le paramètre message à l'aide de la clé private key |
.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 |
.getPublicKey( ) : Text retourne la clé publique de l'objet |
.sign (message : Text ; options : Text) : Text signe la représentation utf8 de la chaîne message |
.size : Integer la taille de la clé en bits |
.type : Texte Name of the key type - "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
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey
Paramètres | Type | Description | |
---|---|---|---|
settings | Objet | -> | Paramètres pour générer ou charger une paire de clés |
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. 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 |
---|---|---|
curve | Texte | Name of ECDSA curve |
pem | Texte | Définition PEM d'une clé de chiffrement à charger |
size | integer | Size of RSA key in bits |
type | Texte | Type of the key: "RSA", "ECDSA", or "PEM" |
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
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.curve : Texte
Défini uniquement pour les clés ECDSA : le nom de la courbe normalisée de la clé. Usually "prime256v1" for ES256 (default), "secp384r1" for ES384, "secp521r1" for ES512.
.decrypt()
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.decrypt( message : Text ; options : Object ) : Object
Paramètres | Type | Description | |
---|---|---|---|
message | Texte | -> | Chaine message à déchiffrer à l'aide de options.encodingEncrypted et decrypted. |
options | Objet | -> | Options de décodage |
Résultat | Objet | <- | Statut |
La fonction .encrypt()
déchiffre le paramètre message à l'aide de la clé private key. 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 | Texte | Algorithme de hachage à utiliser. For example: "SHA256", "SHA384", or "SHA512". |
encodingEncrypted | Texte | 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 | Texte | 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 | Texte | 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é car il n'a pas été chiffré avec la même clé ou le même algorithme, l'objet status
retourné contient une collection d'erreurs dans status.errors
.
.encrypt()
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.encrypt( message : Text ; options : Object ) : Text
Paramètres | Type | Description | |
---|---|---|---|
message | Texte | -> | Chaine message à chiffrer à l'aide de options.encodingDecrypted et encrypted. |
options | Objet | -> | Options de chiffrement |
Résultat | Texte | <- | 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 | Texte | Algorithme de hachage à utiliser. For example: "SHA256", "SHA384", or "SHA512". |
encodingEncrypted | Texte | 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 | Texte | 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
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.getPrivateKey() : Text
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Texte | <- | 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
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.getPublicKey( ) : Text
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Texte | <- | 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
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.pem : Text
PEM definition of an encryption key to load. Si la clé est une clé privée, la clé publique RSA ou ECDSA en sera déduite.
.sign()
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.sign (message : Text ; options : Text) : Text
Paramètres | Type | Description | |
---|---|---|---|
message | Texte | -> | Chaîne message à signer |
options | Objet | -> | Options de signature |
Résultat | Texte | <- | 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 d'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é.
La cryptoKey
doit contenir une clé privée valide.
options
Propriété | Type | Description |
---|---|---|
hash | Texte | Algorithme de hachage à utiliser. For example: "SHA256", "SHA384", or "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 | Texte | 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 | Texte | ERepresentation to be used for result signature. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64". |
Résultat
Représentation utf8 de la chaîne message.
.size
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.size : Integer
Défini uniquement pour les clés RSA : la taille de la clé en bits. Habituellement 2048 (par défaut).
.type
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.type : Texte
Name of the key type - "RSA", "ECDSA", "PEM"
settings.size
as .size.settings.curve
as .curve. A noter que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.settings.pem
as .pem.
.verify()
Historique
Version | Modifications |
---|---|
v18 R4 | Ajoutées |
.verify( message : Text ; signature : Text ; options : Object) : object
Paramètres | Type | Description | |
---|---|---|---|
message | Texte | -> | Chaîne message utilisée pour générer la signature |
signature | Texte | -> | Signature à vérifier, en représentation Base64 ou Base64URL, selon la valeur options.encoding |
options | Objet | -> | Options de signature |
Résultat | Objet | <- | 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 d'objet cryptoKey
et des options fournies.
La cryptoKey
doit contenir une clé publique valide.
options
Propriété | Type | Description |
---|---|---|
hash | Texte | Algorithme de hachage à utiliser. For example: "SHA256", "SHA384", or "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 | Texte | 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).
Si la signature n'a pas pu être vérifiée car elle n'a pas été signée avec le même message, la clé ou l'algorithme, l'objet status
retourné contient une collection d'erreurs dans status.errors
.
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 |