KMFCryptoOperation : champ d’application, global
La classe KMFCryptoOperation fournit des méthodes permettant d’effectuer des opérations de chiffrement à l’aide d’un Key Management Framework module de chiffrement (KMF) ou d’un Chiffrement de champ module de chiffrement.
Pour utiliser cette API, vous devez avoir déjà créé et configuré un module de chiffrement KMF ou un module de chiffrement CLE. Le module doit avoir une ou plusieurs spécifications cryptographiques et vous devez créer ou importer sa clé associée. Pour plus d’informations, consultez Modules de chiffrement.
L’objet KMFCryptoOperation généré à l’aide de cette API représente une opération de chiffrement, telle qu’un chiffrement symétrique. Utilisez la méthode KMFCryptoOperations() pour créer cet objet, les méthodes du générateur pour définir les propriétés de l’objet et la méthode doOperation() pour exécuter l’opération.
Vous pouvez utiliser cette API dans les applications incluses dans le périmètre et dans les applications globales. Vous devez toujours spécifier l’espace de noms sn_kmf_ns lors de l’appel de cette API.
KMFCryptoOperation : KMFCryptoOperation (chaîne cryptoModuleName, chaîne operationName)
Crée un objet KMFCryptoOperation pour le module et l’opération spécifiés.
Cette API exploite les méthodes de générateur. Les méthodes de générateur mettent à jour les propriétés de l’objet KMFCryptoOperation, telles que la modification du format de sortie souhaité des données. Toutes les méthodes de générateur ne sont pas valides pour toutes les opérations. Les méthodes de générateur disponibles pour chaque opération sont indiquées dans la table des paramètres ci-dessous.
| Nom | Type | Description |
|---|---|---|
| cryptoModuleName | Chaîne | Nom du module cryptographique KMF (Key Management Framework) ou Chiffrement de champ du module de chiffrement à utiliser. Vous devez créer le module avant d’appeler cette méthode. Pour plus d’informations, voir Vue d’ensemble du module de chiffrement. |
| operationName | Chaîne | Nom de l’opération à effectuer. Valeurs valides (insensibles à la casse) :
|
Cet exemple instancie un objet KMFCryptoOperation pour que le module global.sj_cm effectue une opération de chiffrement symétrique. Vous devez inclure l’espace de noms pour les applications globales et à portée.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION");
Cet exemple montre comment spécifier des options pour mettre à jour le type de sortie et le format de sortie par défaut.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION")
.withOutputType("STRING").withOutputFormat("FORMATTED");
var cipherText=op.doOperation("hi");
Cet exemple montre comment effectuer une opération de chiffrement asymétrique à l’aide d’un schéma de chiffrement intégré (EC-IES). Notez que les valeurs longues, telles que signature, ont été tronquées et remplacées par une ellipse pour plus de lisibilité.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_ENCRYPTION")
.withInputFormat("KMFNONE")
.withOutputType("PAYLOAD");
var cipherText = op.doOperation("hi");
/*
cipherText contains an object similar to this JSON: {
"signature": "pkg…",
"ephemeral_key": "BDi…",
"ciphertext": "afFS…"
}
*/
Cet exemple montre comment effectuer une opération de déchiffrement asymétrique à l’aide d’EC-IES.
var op = new
sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
.withAdditionalInput({
"signature": "pkg… ",
"ephemeral_key": "BDi…"
})
.withOutputFormat("KMFNONE");
var clearText = op.doOperation("afFS…");
Cet exemple montre comment générer et vérifier une signature JWT.
// Validating from instance
var moduleName = 'global.jwtimport'; // must have signature generation spec
var header = '{ "alg": "P5512","typ": "JWT"}'; // your header JSON as a string
var payload = '{"sub": "1234567890", "name": "John Doe", "admin": true, "iat": 1516239022)'; // your payload JSON as a string
// SIGN
var api = new sn_kmf_ns.KMFCryptoOperation(moduleName, "JWT_SIGN").withAdditionalInput(header);
var token = api.doOperation(payload);
gs.info("sign = " + token);
// VERIFY
api = new sn_kmf_ns.KMFCrypto0peration(moduleName, "JWT_VERIFY");
var verifyoutput = api.doOperation(token);
gs.info("verify = " + verifyOutput);
KMFCryptoOperation : doOperation(données d’objet)
Effectue l’opération de chiffrement définie par l’objet KMFCryptoOperation actuel sur les données fournies et renvoie le résultat.
| Nom | Type | Description |
|---|---|---|
| données | Objet | Obligatoire sauf si la méthode du générateur withSysId() a déjà été appelée sur l’objet KMFCryptoOperation associé. Données d’entrée sur lesquelles effectuer l’opération de chiffrement. |
| Type | Description |
|---|---|
Dépend du type d’opération.
|
Résultats des données après l’exécution de l’opération spécifiée dans l’objet KMFCryptoOperation associé. |
Cet exemple utilise doOperation() pour créer un MAC.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_GENERATION");
var data = "aGk=";
var mac = op.doOperation(data);
KMFCryptoOperation : withAdditionalInput(Entrée supplémentaire de l’objet)
Définit l’entrée supplémentaire nécessaire pour effectuer l’opération de chiffrement.
Par exemple, lors d’une vérification de code d’authentification de message (MAC), utilisez cette méthode pour transmettre la balise MAC générée. De même, lors de la vérification de signature, utilisez-la pour transmettre la signature. Vous pouvez également utiliser cette méthode pour transmettre des données supplémentaires, un objet KMFEncryptionPayload, lors de l’exécution d’une opération asymétrique avec un chiffrement intégré, tel que le schéma de chiffrement intégré à la courbe elliptique (EC-IES).
| Nom | Type | Description |
|---|---|---|
| additionalInput | Chaîne ou objet | Facultatif, sauf pour les opérations de déchiffrement asymétrique lors de l’utilisation d’EC-IES. Données d’entrée supplémentaires nécessaires pour effectuer l’opération de chiffrement spécifiée dans l’objet KMFCryptoOperation. Formats de chaîne pris en charge :
KMFEncryptionPayload format d’objet : |
| additionalInput.ciphertext | Chaîne (Base64) | Requis pour le déchiffrement asymétrique, facultatif pour toutes les autres opérations. Valeurs valides :
Disponible à partir de l’opération de chiffrement asymétrique lorsque le type de sortie est défini sur payload. |
| additionalInput.derivation_secret | Chaîne (Base64) | Facultatif, uniquement utilisé pour les opérations de chiffrement asymétrique ou de déchiffrement asymétrique avec EC-IES. Secret partagé à utiliser pendant le processus de dérivation de clé du schéma intégré. |
| additionalInput.ephemeral_key | Chaîne (Base64) | Requis pour l’opération de déchiffrement asymétrique lors de l’utilisation d’EC-IES, facultatif pour toutes les autres opérations. Clé publique éphémère à utiliser pendant le processus d’accord de base du schéma intégré. Disponible à partir de l’opération de chiffrement asymétrique lorsque le type de sortie est défini sur payload. |
| additionalInput.ephemeral_key_format | Chaîne | Facultatif, uniquement utilisé pour les opérations de chiffrement asymétrique ou de déchiffrement asymétrique avec EC-IES. Remplace le format de la clé publique représentée par le ephemeral_key paramètre. Valeurs valides :
|
| additionalInput.signature | Chaîne (Base64) | Requis pour l’opération de déchiffrement asymétrique avec EC-IES, en option pour tous les autres. Signature du texte chiffré à valider à l’aide du processus de vérification de signature du schéma intégré. Disponible à partir de l’opération de chiffrement asymétrique lorsque le type de sortie est défini sur payload. |
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withAdditionalInput() pour ajouter une signature basée sur une chaîne à l’objet KMFCryptoOperation.
var signature = "John Doe";
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SIGNATURE_VERIFICATION")
.withAdditionalInput(signature);
var value = GlideStringUtil.base64Encode("Text to encode"); // Default input format is KMFBase64
var result = op.doOperation(String(value));
Cet exemple utilise withAdditionalInput() pour ajouter une signature et une clé éphémère à l’objet KMFCryptoOperation. Notez que les valeurs longues, telles que celles de l’appel et payload de la description doOperation(), ont été tronquées et remplacées par une ellipse pour plus de lisibilité.
var payload = new sn_kmf_ns.KMFEncryptionPayload();
payload.signature = "pkg...";
payload.ephemeral_key = " BDi...";
payload.ephemeral_key_format = "x962";
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
.withAdditionalInput(payload)
.doOperation("afFS...";
KMFCryptoOperation : withAlgorithm(algorithme de chaîne)
Définit l’algorithme associé au matériau clé à encapsuler.
| Nom | Type | Description |
|---|---|---|
| algorithme | Chaîne | Algorithme à utiliser. Valeurs valides :
|
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withAlgorithm() pour changer l’algorithme de chiffrement utilisé en EC.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_WRAPPING").withAlgorithm("EC");
var value = GlideStringUtil.base64Encode("Sample key"); // Default input format is KMFBase64
var result = op.doOperation(String(value));
KMFCryptoOperation : withInputFormat(String inputFormat)
Définit le format des données d’entrée sur lesquelles l’opération de chiffrement sera effectuée. Utilise le format spécifié lors du décodage des données.
| Nom | Type | Description |
|---|---|---|
| Format d’entrée | Chaîne | Format des données d’entrée. Valeurs valides :
Valeur par défaut : valeur déterminée par l’opération spécifiée lors de l’instanciation de l’objet KMFCryptoOperation. Pour plus d'informations, consultez KMFCryptoOperation : KMFCryptoOperation (chaîne cryptoModuleName, chaîne operationName). |
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withInputFormat() pour modifier le format d’entrée afin qu’il n’y ait aucun codage.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION").withInputFormat("KMFNone");
var result = op.doOperation("Text with no encoding"); // Pass in unencrypted String
Cet exemple utilise withInputFormat() pour changer le format d’entrée en KMF_GLIDE_ENCRYPTER_FORMATTED.
var encryptOp = new sn_kmf_ns.KMFCryptoOperation("<module_name>", "SYMMETRIC_DECRYPTION")
.withInputFormat("KMF_GLIDE_ENCRYPTER_FORMATTED")
.withOutputFormat("KMFNone");
var clear_text = encryptOp.doOperation(<encrypted_text>);
KMFCryptoOperation : withOutputFormat(String outputFormat)
Définit le format des données de sortie renvoyées par l’opération de chiffrement. Utilise le format spécifié lors du codage des données.
| Nom | Type | Description |
|---|---|---|
| outputFormat | Chaîne | Format des données de sortie. Valeurs valides :
Valeur par défaut si cette méthode n’est pas appelée : valeur déterminée par l’opération spécifiée lors de l’instanciation de l’objet KMFCryptoOperation. Pour plus d'informations, consultez KMFCryptoOperation : KMFCryptoOperation (chaîne cryptoModuleName, chaîne operationName). |
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withOutputFormat() pour définir le format de sortie du déchiffrement sur KMFNone (la valeur par défaut est KMFBase64.)
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_DECRYPTION").withOutputFormat("KMFNone");
var clear_data = op.doOperation(<FORMATTED_data>); // Pass in default of FORMATTED data
KMFCryptoOperation : withOutputType(String outputType)
Définit le type de données pour les données de sortie renvoyées après l’opération de chiffrement.
| Nom | Type | Description |
|---|---|---|
| Type de sortie | Chaîne | Type de données de sortie. Tous les types de sortie ne sont pas applicables à toutes les opérations. Pour un type non pris en charge, une exception est levée. Valeurs valides (insensibles à la casse) :
Remarque : Lorsque vous spécifiez une sortie de charge utile, la sortie de la méthode doOperation() est un objet KMFEncryptionPayload. Pour plus d’informations sur la structure de cet objet, consultez withAdditionalInput(). Valeur par défaut : valeur déterminée par l’opération, spécifiée lors de l’instanciation de l’objet KMFCryptoOperation. Pour plus d'informations, consultez KMFCryptoOperation : KMFCryptoOperation (chaîne cryptoModuleName, chaîne operationName). |
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withOutputType() pour définir le type de sortie de MAC_VERIFICATION sur Booléen.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_VERIFICATION")
.withOutputType("Boolean").withAdditionalInput(<MAC>);
var value = GlideStringUtil.base64Encode("Text to sign"); // Default input type is KMFBase64
var result = op.doOperation(String(value));
KMFCryptoOperation : withSysId(String sysId)
Définit l’sys_id de la clé à envelopper sur l’objet KMFCryptoOperation. Applicable à l’emballage symétrique et asymétrique des clés.
| Nom | Type | Description |
|---|---|---|
| sysId | Chaîne | Sys_id de la clé à envelopper. Table : clé de module [sys_kmf_module_key] |
| Type | Description |
|---|---|
| Néant |
Cet exemple utilise withSysId() pour définir la clé à encapsuler.
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_WRAPPING").withSysId("0d06ce525b231010f86d1b341d81c777");
var wrappedKey = operation.doOperation(); // No need to pass data when using withSysId()