KMFCryptoOperation - Inclus, global

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 12 minutes de lecture

    • La classe KMFCryptoOperation fournit des méthodes permettant d’effectuer des opérations cryptographiques à l’aide d’un module de chiffrement (KMF) ou d’un Key Management Framework module de Chiffrement au niveau des colonnes chiffrement (CLE).

    Pour utiliser cette API, vous devez avoir préalablement 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 cryptographique, 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 globales. Vous devez toujours spécifier l’espace de noms sn_kmf_ns lors de l’appel de cette API.

    KMFCryptoOperation : KMFCryptoOperation(String cryptoModuleName, String operationName)

    Crée un objet KMFCryptoOperation pour le module et l’opération spécifiés.

    Cette API exploite les méthodes du générateur. Les méthodes du générateur mettent à jour les propriétés de l’objet KMFCryptoOperation, par exemple en changeant le format de sortie souhaité des données. Les méthodes du générateur ne sont pas toutes valides pour toutes les opérations. Les méthodes de construction disponibles pour chaque opération sont indiquées dans le tableau des paramètres ci-dessous.

    Les méthodes de création suivantes sont valides pour tous les types d’opérations :
    Tableau 1. Paramètres
    Nom Type Description
    cryptoModuleName Chaîne Nom du module de chiffrement KMF (Key Management Framework) ou du module de chiffrement au niveau des colonnes (CLE) à utiliser. Vous devez créer le module avant d’appeler cette méthode. Pour plus d’informations, consultez Vue d’ensemble du module de chiffrement.
    Nom de l’opération Chaîne Nom de l’opération à effectuer.
    Valeurs valides (insensibles à la casse) :
    • ASYMMETRIC_DECRYPTION : Déchiffrement des données à l’aide d’un algorithme de clé asymétrique. Nécessite un module de chiffrement KMF avec un objectif de chiffrement de déchiffrement des données asymétriques.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : Formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 - codé Base64
      • Type de sortie par défaut : chaîne
    • ASYMMETRIC_ENCRYPTION : Chiffrement des données à l’aide d’un algorithme à clé asymétrique. Nécessite un module de chiffrement KMF avec un objectif de chiffrement des données asymétriques.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne . La sortie peut également être un objet KMFEncryptionPayload . RSA et EC-IES sont compatibles avec les deux. Pour plus d’informations sur l’objet KMFEncryptionPayload, consultez withAdditionalInput().
    • ASYMMETRIC_UNWRAPPING : désencapsulation de clé à l’aide d’un algorithme de clé asymétrique. Nécessite un module de chiffrement KMF avec un objectif de chiffrement de désencapsulation de clé asymétrique.
      • Méthodes supplémentaires du générateur : withAlgorithm()
      • Format d’entrée par défaut : Formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 - codé Base64
      • Type de sortie par défaut : chaîne
    • ASYMMETRIC_WRAPPING : Encapsulation de clé à l’aide d’un algorithme de clé asymétrique. Nécessite un module de chiffrement KMF avec un objectif cryptographique d’encapsulation de clé asymétrique.
      • Méthodes compilatrices supplémentaires : withAlgorithm(),withSysId()
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne
    • MAC_GENERATION : Génération d’un code d’authentification de message (MAC). Algorithme de clé symétrique basé sur l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF à des fins de chiffrement d’authenticité symétrique.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne
    • MAC_VERIFICATION : Vérification d’un MAC. Algorithme à clé symétrique basé pour assurer l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF à des fins de chiffrement d’authenticité symétrique.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : KMFNone - Aucun décodage
      • Type de sortie par défaut : booléen
    • SIGNATURE_GENERATION : Génération d’une signature numérique. Algorithme de clé asymétrique basé pour assurer l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF avec un objectif de chiffrement de génération de signature.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne
    • SIGNATURE_VERIFICATION : vérification d’une signature numérique. Algorithme de clé asymétrique basé pour assurer l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF avec un objectif cryptographique de vérification de signature.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : KMFNone - Aucun décodage
      • Type de sortie par défaut : booléen
    • SYMMETRIC_ENCRYPTION : Chiffrement des données à l’aide d’un algorithme à clé symétrique. Si l’algorithme ne préserve pas l’égalité, seule une sortie formatée est autorisée. Nécessite un module de chiffrement KMF avec un objectif de chiffrement symétrique des données.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne
    • SYMMETRIC_DECRYPTION : Déchiffrement des données à l’aide d’un algorithme à clé symétrique. Si l’algorithme ne préserve pas l’égalité, l’entrée KMFBase64 est autorisée. Nécessite un module de chiffrement KMF avec un objectif de chiffrement symétrique des données.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : Formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 - codé Base64
      • Type de sortie par défaut : chaîne
    • SYMMETRIC_WRAPPING : Encapsulation de clé à l’aide d’un algorithme de clé symétrique. Si l’algorithme ne préserve pas l’égalité, seule une sortie formatée est autorisée. Nécessite un module de chiffrement KMF avec un objectif cryptographique d’encapsulation/désencapsulation de clé symétrique.
      • Méthodes supplémentaires du générateur : withAlgorithm() et withSysId()
      • Format d’entrée par défaut : KMFBase64 – codé Base64
      • Format de sortie par défaut : Formaté : formaté selon les spécifications KMF
      • Type de sortie par défaut : chaîne
    • SYMMETRIC_UNWRAPPING : désencapsulation de clé à l’aide d’un algorithme de clé symétrique. Si l’algorithme ne préserve pas l’égalité, l’entrée KMFBase64 est autorisée. Nécessite un module de chiffrement KMF avec un objectif cryptographique d’encapsulation/désencapsulation de clé symétrique.
      • Méthodes supplémentaires du générateur : withAlgorithm()
      • Format d’entrée par défaut : Formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 - codé Base64
      • Type de sortie par défaut : chaîne

    Cet exemple instancie un objet KMFCryptoOperation pour que le module global.sj_cm effectuer une opération de chiffrement symétrique. Vous devez inclure l’espace de noms pour les applications globales et incluses dans le périmètre.

    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 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…");

    KMFCryptoOperation : doOperation(données de l’objet)

    Exécute l’opération de chiffrement définie par l’objet KMFCryptoOperation actuel sur les données fournies et renvoie le résultat.

    Tableau 2. Paramètres
    Nom Type Description
    données Objet Requis, 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.
    Tableau 3. Renvoie
    Type Description
    Dépend du type d’opération.
    • MAC_VERIFICATION et SIGNATURE_VERIFICATION: Booléen
    • Tous les autres : chaîne
    		 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(Object additionalInput)

    Définit l’entrée supplémentaire nécessaire pour effectuer l’opération de chiffrement.

    Par exemple, lors d’une vérification du 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 la signature, utilisez-le 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é à courbe elliptique (EC-IES).

    Remarque :
    Il n’est pas nécessaire que l’entrée supplémentaire soit au même format que celui actuellement défini sur l’objet KMFCryptoOperation.
    Tableau 4. Paramètres
    Nom Type Description
    Entrée supplémentaire Chaîne ou objet Facultatif, à l’exception des 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 :
    • FORMATÉ : formaté selon les spécifications du cadre de travail de gestion des clés (KMF).
    • KMFBASE64 : codé en Base64.

    Format d’objet KMFEncryptionPayload :

    {
  "ciphertext": String,
  "derivation_secret": String,
  "ephemeral_key": String,
  "ephemeral_key_format": String,
  "signature": String
}
    additionalInput.ciphertext Chaîne (Base64) Requis pour le déchiffrement asymétrique, facultatif pour toutes les autres opérations.
    Valeurs valides :
    • Si vous utilisez un algorithme RSA : texte chiffré RSA
    • En cas d’utilisation d’un algorithme EC-IES : Texte chiffré AES intégré

    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, utilisé uniquement 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, utilisé uniquement 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 :
    • x962
    • Der
    additionalInput.signature Chaîne (Base64) Requis pour l’opération de déchiffrement asymétrique avec EC-IES, facultatif 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.
    Tableau 5. Renvoie
    Type Description
    Aucun

    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é à envelopper.

    Tableau 6. Paramètres
    Nom Type Description
    algorithme Chaîne Algorithme à utiliser.
    Valeurs valides :
    • AES : type de clé symétrique
    • EC : type de clé asymétrique
    • HMAC : type de clé symétrique
    • RSA : type de clé asymétrique
    Tableau 7. Renvoie
    Type Description
    Aucun

    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.

    Tableau 8. Paramètres
    Nom Type Description
    Format d’entrée Chaîne Format des données d’entrée.
    Valeurs valides :
    • FORMATÉ : formaté selon les spécifications du cadre de travail de gestion des clés (KMF).
    • KMFBASE64 : codé en Base64.
    • KMFNONE : Pas d’encodage.

    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(String cryptoModuleName, String operationName).
    Tableau 9. Renvoie
    Type Description
    Aucun

    Cet exemple utilise withInputFormat() pour changer le format d’entrée afin qu’il n’ait pas d’encodage.

    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

    KMFCryptoOperation - withOutputFormat(String outputFormat)

    Définit le format des données de sortie retournées par l’opération de chiffrement. Utilise le format spécifié lors du codage des données.

    Tableau 10. Paramètres
    Nom Type Description
    Format de sortie Chaîne Format des données de sortie.
    Valeurs valides :
    • FORMATÉ : formaté selon les spécifications du cadre de travail de gestion des clés (KMF).
    • KMFBASE64 : codé en Base64.
    • KMFNONE : Pas de décodage. Uniquement pris en charge pour MAC_VERIFICATION et SIGNATURE_VERIFICATION.

    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(String cryptoModuleName, String operationName).
    Tableau 11. Renvoie
    Type Description
    Aucun

    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 des données de sortie renvoyées après l’exécution de l’opération de chiffrement.

    Remarque :
    Lorsque vous instanciez l’objet KMFCryptoOperation pour MAC_VERIFICATION les opérations or SIGNATURE_VERIFICATION , vous devez également appeler cette méthode, en transmettant une valeur booléenne, pour définir le type de sortie correct, sinon une exception est levée lors de l’exécution de l’opération.
    Tableau 12. Paramètres
    Nom Type Description
    Type de sortie Chaîne Type des 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) :
    • Chaîne : non valide pour MAC_VERIFICATION les opérations OR SIGNATURE_VERIFICATION .
    • Booléen : valide uniquement pour les opérations or MAC_VERIFICATIONSIGNATURE_VERIFICATION .
    • Charge utile : valide uniquement pour l’opération ASYMMETRIC_ENCRYPTION . Utilisez ce type de sortie pour EC-IES.
    Remarque :
    Lors de la spécification d’une sortie de Payload, la sortie de la méthode doOperation() est un objet KMFEncryptionPayload. Pour plus d’informations sur la structure de cet objet, consultez withAdditionalInput().

    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(String cryptoModuleName, String operationName).
    Tableau 13. Renvoie
    Type Description
    Aucun

    Cet exemple utilise withOutputType() pour définir le type de sortie de MAC_VERIFICATION sur Boolean.

    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(SysId de chaîne)

    Définit la sys_id de la clé à envelopper sur l’objet KMFCryptoOperation. Applicable à l’emballage symétrique et asymétrique des clés.

    Tableau 14. Paramètres
    Nom Type Description
    sysId Chaîne Sys_id de la clé à envelopper. Situé dans la table Clé de module [sys_kmf_module_key].
    Tableau 15. Renvoie
    Type Description
    Aucun

    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()