KMFCryptoOperation - Champ d’application, global

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 12 minutes de lecture

    • La classe KMFCryptoOperation fournit des méthodes pour effectuer des opérations cryptographiques à l’aide d’un module cryptographique KMF ou d’un module de chiffrement CLE.

    Pour utiliser cette API, vous devez déjà avoir créé et configuré un module cryptographique Key Management Framework (KMF) ou un module de chiffrement CLE (Column Level Encryption). 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. Toutes les méthodes de générateur ne sont pas valides pour toutes les opérations. Les méthodes de création 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 cryptographique Key Management Framework (KMF) ou du module de chiffrement CLE (Column Level Encryption) à 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 à clé asymétrique. Nécessite un module cryptographique KMF avec un objectif cryptographique 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é en 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 cryptographique KMF avec un objectif cryptographique 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 cryptographique KMF avec un objectif cryptographique de désencapsulation de clé asymétrique.
      • Méthodes de compilation 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 cryptographique KMF avec un objectif cryptographique d’encapsulation de clé asymétrique.
      • Méthodes de compilation 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). L’algorithme de clé symétrique basé sur assure l’intégrité et l’authentification des données. Nécessite un module cryptographique 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é 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 basé sur une clé symétrique pour assurer l’intégrité et l’authentification des données. Nécessite un module cryptographique 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é 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 basé sur une clé asymétrique pour assurer l’intégrité et l’authentification des données. Nécessite un module cryptographique 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é 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 basé sur une clé asymétrique pour assurer l’intégrité et l’authentification des données. Nécessite un module cryptographique 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 la sortie formatée est autorisée. Nécessite un module de chiffrement KMF avec un objectif cryptographique de chiffrement/dé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 cryptographique de chiffrement/dé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é 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 compilation supplémentaires : 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 de compilation 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 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 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…");

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

    Exécute l’opération cryptographique 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 Nécessaire, 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
    		 Les données résultent de l’exécution de l’opération spécifiée dans l’objet KMFCryptoOperation associé.

    Cet exemple utilise la fonction 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 cryptographique spécifiée dans l’objet KMFCryptoOperation.
    Formats de chaîne pris en charge :
    • FORMATTED : formaté selon les spécifications du Key Management Framework (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
    • 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) Obligatoire 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, 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 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 cryptographique 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 :
    • FORMATTED : formaté selon les spécifications du Key Management Framework (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
    Néant

    Cet exemple utilise withInputFormat() pour modifier 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 de données 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
    Format de sortie Chaîne Format des données de sortie.
    Valeurs valides :
    • FORMATTED : formaté selon les spécifications du Key Management Framework (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
    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 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 lorsque vous exécutez 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 les opérations OR MAC_VERIFICATIONSIGNATURE_VERIFICATION .
    • Booléen : uniquement valide 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
    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 le 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
    Néant

    Cet exemple utilise withSysId() pour définir la clé à envelopper.

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