Version: Next

CryptoKey

The CryptoKey class in the 4D language encapsulates an asymmetric encryption key pair.

This class is available from the 4D class store.

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 4D.CryptoKey object encapsulating an encryption key pair | | .curve : Text
nom de la courbe normalisée de la clé | | .decrypt( message : Text ; options : Object ) : Object
decrypts the message parameter using the private key | | .encrypt( message : Text ; options : Object ) : Text
encrypts the message parameter using the public key | | .getPrivateKey() : Text
returns the private key of the CryptoKey object | | .getPublicKey() : Text
returns the public key of the CryptoKey object | | .sign (message : Text ; options : Object) : Text
signs the utf8 representation of a message string | | .size : Integer
la taille de la clé en octets | | .type : Text
name of the key type - "RSA", "ECDSA", "PEM" | | .verify( message : Text ; signature : Text ; options : Object) : object
verifies the base64 signature against the utf8 representation of 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
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
type	text	Defines the type of the key to create: "RSA": generates a RSA key pair, using .size as size. "ECDSA": generates an Elliptic Curve Digital Signature Algorithm key pair, using .curve as curve. Note that ECDSA keys cannot be used for encryption but only for signature. "PEM": loads a key pair definition in PEM format, using .pem.
curve	text	Nom de la courbe ECDSA
pem	text	Définition PEM d'une clé de chiffrement à charger
size	entier	Taille de la clé RSA en octets

CryptoKey

The returned CryptoKey object encapsulates an encryption key pair. C'est un objet partagé et peut être alors utilisé par de multiples traitements 4D simultanés.

.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	->	Message string to be decoded using `options.encodingEncrypted` and decrypted.
options	Object	->	Options de décodage
Résultat	Object	<-	Statut

The .decrypt() function decrypts the message parameter using the private key. L'algorithme utilisé dépend du type de clé.

The key must be a RSA key, the algorithm is RSA-OAEP (see RFC 3447).

options

Propriété	Type	Description
hash	text	Algorithme de hachage à utiliser. Par exemple : "SHA256", "SHA384" ou "SHA512".
encodingEncrypted	text	Encoding used to convert the `message` parameter into the binary representation to decrypt. 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

The function returns a status object with success property set to true if the message could be successfully decrypted.

Propriété	Type	Description
success	boolean	True si le message a été déchiffré avec succès
result	text	Message decrypted and decoded using the `options.encodingDecrypted`
errors	collection	If `success` is `false`, may contain a collection of errors

In case the message couldn't be decrypted because it was not encrypted with the same key or algorithm, the status object being returned contains an error collection in status.errors.

.encrypt()

Historique

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
message	Text	->	Message string to be encoded using `options.encodingDecrypted` and encrypted.
options	Object	->	Options de chiffrement
Résultat	Text	<-	Message encrypted and encoded using the `options.encodingEncrypted`

The .encrypt() function encrypts the message parameter using the public key. L'algorithme utilisé dépend du type de clé.

The key must be a RSA key, the algorithm is RSA-OAEP (see 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	Encoding used to convert the `message` parameter into the binary representation to encrypt. 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

The .getPrivateKey() function returns the private key of the CryptoKey object in PEM format, or an empty string if none is available.

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

The .getPublicKey() function returns the public key of the CryptoKey object in PEM format, or an empty string if none is available.

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"

The .sign() function signs the utf8 representation of a message string using the CryptoKey object keys and provided options. It returns its signature in base64 or base64URL format, depending on the value of the options.encoding attribute you passed.

The CryptoKey must contain a valid private key.

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. Pass `true` when producing a JWT for PS@ algorithm
encoding	text	Représentation à utiliser pour la signature. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64".

Résultat

The utf8 representation of the message string.

.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 : Text

Contains the name of the key type - "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 .curve. A noter que les clés ECDSA ne peuvent pas être utilisées pour le chiffrement, mais uniquement pour la signature.
"PEM": a key pair definition in PEM format, using settings.pem as .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 to verify, in Base64 or Base64URL representation, depending on `options.encoding` value
options	Object	->	Options de signature
Résultat	Object	<-	Statut de la vérification

The .verify() function verifies the base64 signature against the utf8 representation of message using the CryptoKey object keys and provided options.

The CryptoKey must contain a valid public key.

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. Pass `true` when verifying a JWT for PS@ algorithm
encoding	text	Représentation de la signature fournie. Valeurs possibles : "Base64" ou "Base64URL". La valeur par défaut est "Base64".

Résultat

The function returns a status object with success property set to true if message could be successfully verified (i.e. the signature matches).

In case the signature couldn't be verified because it was not signed with the same message, key or algorithm, the status object being returned contains an error collection in status.errors.

Propriété	Type	Description
success	boolean	True si la signature correspond au message
errors	collection	If `success` is `false`, may contain a collection of errors

Exemple​

Sommaire​

4D.CryptoKey.new()​

settings​

CryptoKey​

.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​

Exemple

Sommaire

4D.CryptoKey.new()

settings

CryptoKey

.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