KMFCryptoOperation - Champ d’application, global

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 12 minutes de lecture

    • La classe KMFCryptoOperation fournit des méthodes pour 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, voir Modules cryptographiques.

    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 globales. Vous devez toujours spécifier l’espace de noms sn_kmf_ns lorsque vous appelez 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 de générateur. Les méthodes du 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 le tableau des paramètres ci-dessous.

    Les méthodes de générateur 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 du Cadre de travail de gestion des clés (KMF) 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 cryptographique.
    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 cryptographique de déchiffrement de 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é en Base64
      • Type de sortie par défaut : chaîne
    • ASYMMETRIC_ENCRYPTION : 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 données asymétriques.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : KMFBase64 : codé en 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 une clé asymétrique Désencapsulation à des fins cryptographiques.
      • Méthodes de générateur supplémentaires : withAlgorithm()
      • Format d’entrée par défaut : formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 : codé en 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 de générateur supplémentaires : withAlgorithm(),withSysId()
      • Format d’entrée par défaut : KMFBase64 : codé en 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 à clé symétrique basé sur l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF avec un objectif cryptographique d’authenticité symétrique.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 : codé en 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é sur l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF avec un objectif cryptographique d’authenticité symétrique.
      • Méthodes de générateur supplémentaires : withAdditionalInput()
      • Format d’entrée par défaut : KMFBase64 : codé en 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 à clé asymétrique basé sur l’intégrité et l’authentification des données. Nécessite un module de chiffrement KMF avec un objectif cryptographique de génération de signature.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 : codé en 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 à clé asymétrique basé sur 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é en 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 de clé symétrique. Si l’algorithme ne préserve pas l’égalité, seule la sortie formatée est autorisée. Nécessite un module de chiffrement KMF avec un objectif de chiffrement et de déchiffrement de données symétriques.
      • Méthodes de générateur supplémentaires : aucune
      • Format d’entrée par défaut : KMFBase64 : codé en 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 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 de chiffrement et de déchiffrement de données symétriques.
      • 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é en 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 la 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 de générateur supplémentaires : withAlgorithm() et withSysId()
      • Format d’entrée par défaut : KMFBase64 : codé en 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 de générateur supplémentaires : withAlgorithm()
      • Format d’entrée par défaut : formaté : formaté selon les spécifications KMF
      • Format de sortie par défaut : KMFBase64 : codé en Base64
      • Type de sortie par défaut : chaîne

    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 des raisons 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)

    Effectue 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 de la vérification d’un 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
    additionalInput Chaîne ou objet Facultatif, à l’exception des opérations de déchiffrement asymétriques 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é 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
    • Si vous utilisez un algorithme EC-IES : texte chiffré AES intégré

    Disponible à partir de l’opération 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 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 :
    • x962
    • Der
    additionalInput.signature Chaîne (Base64) Requis pour l’opération de déchiffrement asymétrique avec EC-IES, en option pour tous les autres. La 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 Chiffrement asymétrique lorsque le type de sortie est défini sur payload.
    Tableau 5. Renvoie
    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é à 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
    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 de données pour les 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é Base64.
    • KMF_GLIDE_ENCRYPTER_FORMATTED : prend en charge les déchiffrages des valeurs chiffrées KMF et des valeurs chiffrées GlideEncrypter.
    • KMFNONE : Pas d’encodage.

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

    Cet exemple utilise withInputFormat() pour modifier le format d’entrée afin qu’il n’y 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

    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 qui sont renvoyé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
    outputFormat 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é 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
    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’exécution de l’opération de chiffrement.

    Remarque :
    Lorsque vous instancierez l’objet KMFCryptoOperation pour MAC_VERIFICATION ou SIGNATURE_VERIFICATION des opérations, vous devez également appeler cette méthode, en transmettant une valeur booléenne, pour définir le type de sortie correct ou une exception est levée lorsque vous exécutez l’opération.
    Tableau 12. Paramètres
    Nom Type Description
    Type de sortie Chaîne Type de données de sortie.

    Tous les types de sorties 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 OU SIGNATURE_VERIFICATION .
    • Booléen : uniquement valide pour MAC_VERIFICATION les opérations ou SIGNATURE_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 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 lorsque l’objet KMFCryptoOperation a été instancié. Pour plus d'informations, consultez KMFCryptoOperation : KMFCryptoOperation(String cryptoModuleName, String operationName).
    Tableau 13. Renvoie
    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é à encapsuler sur l’objet KMFCryptoOperation. Applicable à l’encapsulation symétrique et asymétrique des clés.

    Tableau 14. Paramètres
    Nom Type Description
    sysId Chaîne Sys_id de la clé à envelopper.

    Table : Clé de module [sys_kmf_module_key]
    Tableau 15. Renvoie
    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()