IBM Cloud Docs
Opérations de chiffrement : API GREP11

Opérations de chiffrement : API GREP11

IBM Cloud® Hyper Protect Crypto Services fournit un ensemble de fonctions de cryptographie exécutées dans un module HSM(Hardware Security Module)A physical appliance that provides on-demand encryption, key management, and key storage as a managed service. du cloud. Vous pouvez effectuer des opérations de chiffrement en accédant à distance à ces fonctions à l'aide des appels d'API Enterprise PKCS #11 (EP11) sur gRPC (également appelés GREP11).

Pour plus d'informations sur la façon dont les fonctions GREP11 sont liées à PKCS #11 et EP11, voir la présentation de GREP11.

L'API GREP11 peut traiter jusqu'à 500 demandes par seconde pour une seule unité de chiffrement.

Accès à l'API

Un noeud final d'API GREP11, une clé d'API d'ID de service et un noeud final IAM sont nécessaires pour l'initialisation avant d'effectuer des appels de fonction d'API GREP11. Pour plus d'informations, voir Génération d'une demande d'API GREP11.

Traitement des erreurs

GREP11 s'appuie sur la spécification gRPC pour le traitement des erreurs. Lorsqu'une erreur se produit, les clients gRPC reçoivent un Mémoire tampon du protocole message Status.

message Status {
    int32 code = 1;
    string message = 2;
    repeated google.protobuf.Any details = 3;
}

Dans le message d'erreur,

  • code inclut le code d'état, qui doit être une valeur énumérée (enum) de la zone google.rpc.Code.
  • message inclut un message d'erreur destiné au développeur, en anglais. Tout message d'erreur destiné à l'utilisateur doit être localisé et envoyé dans la zone google.rpc.Status.details ou localisé par l'utilisateur.
  • details répertorie les messages portant les détails de l'erreur. Un ensemble courant de types de message est à la disposition de l'API pour qu'elle puisse l'utiliser.

GREP11 se sert de la zone Detail pour indiquer des informations de code d'erreur supplémentaires.

message Grep11Error {
    uint64 Code = 1;
    string Detail = 2;
    bool Retry = 3;
}

Le champ Code peut être converti vers la valeur CK_RV dans PKCS #11. Cette zone contient les codes d'erreur définis par la spécification PKCS #11 ou les extensions de fournisseur définies par EP11. EP11 n'utilise qu'un sous-ensemble des valeurs de retour définies par PKCS #11. Pour plus d'informations, voir la section 10.1.6 Valeurs de retour dans Enterprise PKCS #11 Library structure.

Un exemple dans Golang qui traite les erreurs est disponible.

Liste des fonctions GREP11

Les fonctions PKCS #11 qui sont suivies d'un astérisque (*) dans le tableau sont implémentées par EP11 sur gRPC. Les autres ne sont pas implémentées.

Tableau 1. Décrit les fonctions implémentées dans EP11 sur gRPC
PKCS #11 Enterprise PKCS #11 Enterprise PKCS #11 sur gRPC Description
C_Initialize N/A N/A Initialise Cryptoki.
C_Finalize N/A N/A Nettoie diverses ressources associées à Cryptoki.
C_GetInfo N/A N/A Obtient des informations générales sur Cryptoki.
C_GetFunctionList N/A N/A Obtient les points d'entrée des fonctions de la bibliothèque Cryptoki.
C_GetSlotList N/A N/A Obtient une liste d'attributs dans le système.
C_GetSlotInfo N/A N/A Obtient des informations sur un attribut particulier.
C_GetTokenInfo N/A N/A Obtient des informations sur un jeton particulier.
C_WaitForSlotEvent N/A N/A Attend qu'un événement d'emplacement (insertion de jeton, retrait, etc.) se produise.
C_GetMechanismList* m_GetMechanismList GetMechanismList Obtient une liste des mécanismes pris en charge par un jeton.
C_GetMechanismInfo* m_GetMechanismInfo GetMechanismInfo Obtient des informations sur un mécanisme particulier.
C_InitToken N/A N/A Initialise un jeton.
C_InitPIN N/A N/A Initialise le code PIN de l'utilisateur standard.
C_SetPIN N/A N/A Modifie le code PIN de l'utilisateur actuel.
C_OpenSession N/A N/A Ouvre une connexion entre une application et un jeton particulier ou configure un rappel d'application pour une insertion de jeton.
C_CloseSession N/A N/A Ferme une session.
C_CloseAllSessions N/A N/A Ferme toutes les sessions avec un jeton.
C_GetSessionInfo N/A N/A Obtient des informations sur la session.
C_GetOperationState N/A N/A Obtient l'état des opérations de chiffrement d'une session.
C_SetOperationState N/A N/A Définit l'état des opérations de chiffrement d'une session.
C_Login N/A N/A Se connecte à un jeton.
C_Logout N/A N/A Se déconnecte d'un jeton.
C_CreateObject N/A N/A Crée un objet.
C_CopyObject N/A N/A Crée une copie d'un objet.
C_DestroyObject N/A N/A Détruit un objet.
C_GetObjectSize N/A N/A Obtient la taille d'un objet en octets.
C_GetAttributeValue* m_GetAttributeValue GetAttributeValue Obtient une valeur d'attribut d'un objet.
C_SetAttributeValue* m_SetAttributeValue SetAttributeValue Modifie une valeur d'attribut d'un objet. Seuls les attributs booléens peuvent être modifiés.
C_FindObjectsInit N/A N/A Initialise une opération de recherche d'objet.
C_FindObjects N/A N/A Poursuit une opération de recherche d'objet.
C_FindObjectsFinal N/A N/A Termine une opération de recherche d'objet.
C_EncryptInit* m_EncryptInit EncryptInit Initialise une opération de chiffrement.
C_Encrypt* m_Encrypt Chiffrer Chiffre des données ne comportant qu'une seule partie.
C_EncryptUpdate* m_EncryptUpdate EncryptUpdate Poursuit une opération de chiffrement à plusieurs parties.
C_EncryptFinal* m_EncryptFinal EncryptFinal Termine une opération de chiffrement à plusieurs parties.
N/A m_EncryptSingle EncryptSingle Extension IBM, variante non standard d'Encrypt. Traite les données en un seul passage, avec un seul appel. Ne renvoie aucun état à l'hôte autre que des données chiffrées.
N/A m_ReencryptSingle ReencryptSingle Extension IBM, variante non standard d'Encrypt. Déchiffre les données à l'aide de la clé d'origine, puis chiffre les données brutes à l'aide d'un seul appel dans le module HSM en cloud. Ne renvoie aucun état à l'hôte autre que les données rechiffrées.
C_DecryptInit* m_DecryptInit DecryptInit Initialise une opération de déchiffrement.
C_Decrypt* m_Decrypt Decrypt Déchiffre des données chiffrées ne comportant qu'une seule partie.
C_DecryptUpdate* m_DecryptUpdate DecryptUpdate Poursuit une opération de déchiffrement à plusieurs parties.
C_DecryptFinal* m_DecryptFinal DecryptFinal Termine une opération de déchiffrement à plusieurs parties.
N/A m_DecryptSingle DecryptSingle Extension IBM, variante non standard d'Decrypt. Traite les données en un seul passage, avec un seul appel. Ne renvoie aucun état à l'hôte autre que des données déchiffrées.
C_DigestInit* m_DigestInit DigestInit Initialise une opération d'assimilation de messages.
C_Digest* m_Digest Condensé Assimile les données en une seule partie. La longueur des données d'entrée ne peut être égale à zéro et le pointeur qui pointe vers l'emplacement des données d'entrée ne peut être nul.
C_DigestUpdate* m_DigestUpdate DigestUpdate Poursuit une opération d'assimilation à plusieurs parties. La longueur des données d'entrée ne peut être égale à zéro et le pointeur qui pointe vers l'emplacement des données d'entrée ne peut être nul.
C_DigestKey N/A N/A Assimile une clé.
C_DigestFinal* m_DigestFinal DigestFinal Termine une opération d'assimilation à plusieurs parties.
N/A m_DigestSingle DigestSingle Extension IBM, extension non standard, combinaison de DigestInit et Digest. Assimile les données en un seul passage, avec un seul appel, sans qu'un état d'assimilation intermédiaire soit construit et que des allers-retours soient nécessaires
C_SignInit* m_SignInit SignInit Initialise une opération de signature.
C_Sign* m_Sign Signer Signe des données ne comportant qu'une seule partie.
C_SignUpdate* m_SignUpdate SignUpdate Poursuit une opération de signature à plusieurs parties.
C_SignFinal* m_SignFinal SignFinal Termine une opération de signature à plusieurs parties.
C_SignRecoverInit N/A N/A Initialise une opération de signature, dans laquelle les données sont récupérées depuis la signature.
C_SignRecover N/A N/A Signe des données ne comportant qu'une seule partie, dans laquelle les données sont récupérées depuis la signature.
N/A m_SignSingle SignSingle Extension IBM, extension non standard, combinaison de SignInit et Sign. Signe ou effectue des opérations MAC sur des données, en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. Ne renvoie aucun état à l'hôte autre que le résultat.
C_VerifyInit* m_VerifyInit VerifyInit Initialise une opération de vérification.
C_Verify* m_Verify Vérifier Vérifie une signature sur des données ne comportant qu'une seule partie.
C_VerifyUpdate* m_VerifyUpdate VerifyUpdate Poursuit une opération de vérification à plusieurs parties.
C_VerifyFinal* m_VerifyFinal VerifyFinal Termine une opération de vérification à plusieurs parties.
C_VerifyRecoverInit N/A N/A Initialise une opération de vérification dans laquelle les données sont récupérées depuis la signature.
C_VerifyRecover N/A N/A Vérifie une signature sur des données ne comportant qu'une seule partie, dans laquelle les données sont récupérées depuis la signature.
N/A m_VerifySingle VerifySingle Extension IBM, extension non standard, combinaison de VerifyInit et Verify. Signe ou effectue des opérations MAC sur des données, en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. Ne renvoie aucun état à l'hôte autre que le résultat de la vérification.
C_DigestEncryptUpdate N/A N/A Poursuit des opérations de chiffrement et d'assimilation à plusieurs parties.
C_DecryptDigestUpdate N/A N/A Poursuit des opérations de déchiffrement et d'assimilation à plusieurs parties.
C_SignEncryptUpdate N/A N/A Poursuit des opérations de chiffrement et de signature à plusieurs parties.
C_DecryptVerifyUpdate N/A N/A Poursuit des opérations de déchiffrement et de vérification à plusieurs parties.
C_GenerateKey* m_GenerateKey GenerateKey Génère une clé secrète.
C_GenerateKeyPair* m_GenerateKeyPair GenerateKeyPair Génère une paire de clés publiques et privées.
C_WrapKey* m_WrapKey WrapKey Encapsule (chiffre) une clé.
C_UnwrapKey* m_UnwrapKey UnwrapKey Désencapsule (déchiffre) une clé.
N/A N/A RewrapKeyBlob Transfère la propriété d'un BLOB qui est contrôlé par la clé principale en cours vers la nouvelle clé principale lorsque celle-ci est validée. Cette fonction est une commande d'administration particulière prise en charge uniquement par GREP11.
C_DeriveKey* m_DeriveKey DeriveKey Dérive une clé depuis une clé de base.
C_SeedRandom N/A N/A Ajoute un matériel initial au générateur de nombres aléatoires.
C_GenerateRandom* m_GenerateRandom GenerateRandom Génère des données aléatoires. La longueur des données aléatoires ne peut être égale à zéro et le pointeur qui pointe vers l'emplacement des données aléatoires ne peut être nul. La longueur maximale des données aléatoires pouvant être demandées est de 1 million d'octets.
C_GetFunctionStatus N/A N/A Fonction existante qui renvoie toujours CKR_FUNCTION_NOT_PARALLEL.
C_CancelFunction N/A N/A Fonction existante qui renvoie toujours CKR_FUNCTION_NOT_PARALLEL.

Mécanismes pris en charge

Un mécanisme est qualifié de processus permettant d'implementer une opération de chiffrement. Il peut varier en fonction du niveau de microprogramme de la carte de chiffrement. Le tableau ci-après présente les mécanismes actuellement pris en charge et indique leur relation avec les catégories de fonction GREP11 courantes.

Tableau 2. Décrit les mécanismes GREP11 pris en charge
Groupe de fonctions Mécanismes pris en charge
Chiffrer et déchiffrer CKM_RSA_PKCS1, CKM_RSA_PKCS_OAEP1, CKM_AES_ECB, CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD
Signer et vérifier CKM_RSA_PKCS1, CKM_RSA_PKCS_PSS1, CKM_RSA_X9_311, CKM_SHA1_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_SHA1_RSA_PKCS_PSS, CKM_SHA224_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS, CKM_SHA1_RSA_X9_31, CKM_DSA1, CKM_DSA_SHA1, CKM_ECDSA1, CKM_ECDSA_SHA1, CKM_ECDSA_SHA224, CKM_ECDSA_SHA256, CKM_ECDSA_SHA384, CKM_ECDSA_SHA512, CKM_SHA1_HMAC, CKM_SHA256_HMAC, CKM_SHA384_HMAC, CKM_SHA512_HMAC, CKM_SHA512_224_HMAC, CKM_SHA512_256_HMAC, CKM_IBM_ED25519_SHA5124, CKM_IBM_ECDSA_OTHER2, CKM_IBM_DILITHIUM3
Condensé CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512, CKM_SHA512_224, CKM_SHA512_256
Génération d'une clé ou génération d'une paire de clés CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_RSA_X9_31_KEY_PAIR_GEN, CKM_DSA_KEY_PAIR_GEN, CKM_DSA_PARAMETER_GEN, CKM_EC_KEY_PAIR_GEN (CKM_ECDSA_KEY_PAIR_GEN), CKM_DH_PKCS_KEY_PAIR_GEN, CKM_DH_PKCS_PARAMETER_GEN, CKM_GENERIC_SECRET_KEY_GEN, CKM_AES_KEY_GEN, CKM_DES2_KEY_GEN, CKM_DES3_KEY_GEN, CKM_IBM_DILITHIUM
Encapsuler et désencapsuler CKM_RSA_PKCS, CKM_RSA_PKCS_OAEP, CKM_AES_ECB, CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD
Dériver CKM_ECDH1_DERIVE, CKM_DH_PKCS_DERIVE, CKM_DES3_ECB_ENCRYPT_DATA, CKM_SHA1_KEY_DERIVATION, CKM_SHA224_KEY_DERIVATION, CKM_SHA256_KEY_DERIVATION, CKM_SHA384_KEY_DERIVATION, CKM_SHA512_KEY_DERIVATION, CKM_IBM_BTC_DERIVE

1 : Ce mécanisme prend en charge uniquement les opérations à une seule partie qui ne sont pas en mesure d'utiliser les fonctions de mise à jour GREP11, telles que EncryptUpdate, DecryptUpdateet DigestUpdate.

2 : Ce mécanisme n'est disponible que pour les opérations GREP11 SignSingle et VerifySingle.

3 : Ce mécanisme n'est pas pris en charge par la carte de chiffrement IBM 4768 et n'est pas disponible pour les opérations SignUpdate et VerifyUpdate.

4: Ce mécanisme prend en charge les opérations à une seule partie (SignInit, Sign, VerifyInit, Verify), SignSingle et VerifySingle.

Attributs et types de clés pris en charge

Les attributs GREP11 définissent les caractéristiques d'objet qui configurent l'utilisation et l'accès d'un objet. Le tableau ci-après affiche les attributs pris en charge et leur relation avec les divers types de clé pris en charge.

Tableau 3. Décrit les attributs pris en charge
Attribut Description Types de clé pris en charge
CKA_CHECK_VALUE Somme de contrôle de la clé Clés AES, clés DES
CKA_COPYABLE Si la valeur est CKA_TRUE, l'objet peut être copié à l'aide de la fonction PKCS#11 C_CopyObject Clés privées EC, clés publiques EC, clés privées RSA, clés publiques RSA, clés privées DH, clés publiques DH, clés privées DSA, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_DECRYPT CK_TRUE si la clé prend en charge le déchiffrement. Clés privées EC, clés privées RSA, clés privées DH, clés privées DSA, clés AES, clés DES, clés génériques
CKA_DERIVE CK_TRUE si la clé prend en charge la dérivation de clés (d'autres clés peuvent être dérivées de cette clé). La valeur par défaut est CK_FALSE. Clés privées EC, clés publiques EC, clés privées RSA, clés publiques RSA, clés privées DH, clés publiques DH, clés privées DSA, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_EC_PARAMS (CKA_ECDSA_PARAMS) Codage DER d'une valeur de paramètres ANSI X9.62. Clés privées EC, clés publiques EC
CKA_ENCRYPT CK_TRUE si la clé prend en charge le chiffrement. Clés publiques EC, clés publiques RSA, clés publiques DH, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_EXTRACTABLE CK_TRUE si la clé peut être extraite et encapsulée. Clés privées EC, clés privées RSA, clés privées DH, clés privées DSA, clés AES, clés DES, clés génériques
CKA_IBM_PQC_PARAMS Paramètres de soutien pour les mécanismes de cryptographie post-quantique. Dans le cas du mécanisme de Dilithium CKM_IBM_DILITHIUM, il fournit un identificateur d'objet (OID) mobilisé qui représente la force de l'algorithme de Dilithium à utiliser. Actuellement, seule la force de Dilithium 4 round 2 est prise en charge. Clés de Dilithium
CKA_TYPE_CLÉ Type de clé. Clés privées EC, clés publiques EC, clés privées RSA, clés publiques RSA, clés privées DH, clés publiques DH, clés privées DSA, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_LOCAL CK_TRUE uniquement si la clé a été générée localement (sur le jeton) avec un appel C_GenerateKey ou C_GenerateKeyPair ou créé avec un appel C_CopyObject en tant que copie d'une clé, dont l'attribut CKA_LOCAL a été défini sur CK_TRUE. Clés privées EC, clés publiques EC, clés privées RSA, clés publiques RSA, clés privées DH, clés publiques DH, clés privées DSA, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_MODIFIABLE Défini sur CK_TRUE si l'objet peut être modifié. Clés privées EC, clés publiques EC, clés privées RSA, clés publiques RSA, clés privées DH, clés publiques DH, clés privées DSA, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_MODULUS_BITS Longueur en bits du module n. Clés publiques RSA
CKA_PUBLIC_EXPONENT Exposant public e. Clés privées RSA
INFO-KEY_CKA_PUBLIC_INFO Codage DER de SubjectPublicKeyInfo pour la clé publique. La valeur est dérivée des données de clé publique sous-jacentes et est vide par défaut. clés publiques RSA, clés publiques EC
CKA_SIGN CK_TRUE si la clé prend en charge les signatures lorsque la signature est une annexe des données. Clés privées EC, clés privées RSA, clés privées DH, clés privées DSA, clés AES, clés DES, clés génériques
CKA_TRUSTED Le certificat ou la clé sont fiables pour l'application pour laquelle ils ont été créés. Clés publiques EC, clés publiques RSA, clés publiques DH, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_UNWRAP CK_TRUE si la clé prend en charge le désencapsulage (peut être utilisé pour désencapsuler d'autres clés). Clés privées EC, clés privées RSA, clés privées DH, clés privées DSA, clés AES, clés DES, clés génériques
CKA_VALUE_LEN Longueur en octets de la valeur de clé. Clés AES
CKA_VERIFY CK_TRUE si la clé prend en charge les vérifications pour lesquelles la signature constitue une annexe aux données Clés publiques EC, clés publiques RSA, clés publiques DH, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_WRAP CK_TRUE si la clé prend en charge l'encapsulage (peut être utilisé pour encapsuler d'autres clés). Clés publiques EC, clés publiques RSA, clés publiques DH, clés publiques DSA, clés AES, clés DES, clés génériques
CKA_WRAP_WITH_TRUSTED CK_TRUE si la clé peut être encapsulée uniquement avec une clé d'encapsulage dont la valeur CKA_TRUSTED est définie sur CK_TRUE. La valeur par défaut est CK_FALSE. Clés privées EC, clés privées RSA, clés privées DH, clés privées DSA, clés AES, clés DES, clés génériques

Courbes prises en charge

La bibliothèque EP11 prend en charge des types de courbes limités pour certains mécanismes. Le tableau suivant répertorie les noms des courbes prises en charge pour les différents mécanismes. Le nombre dans le nom de courbe désigne le nombre de bits pris en charge.

Courbes prises en charge pour la génération de clés Elliptic Curve (EC)

Le mécanisme CKM_EC_KEY_PAIR_GEN est pris en charge lorsque vous appelez la fonction GenerateKeyPair pour générer des clés Elliptic Curve (EC). Les paramètres des noms de courbe doivent être spécifiés en tant qu'identificateurs d'objet (OID) à l'aide de CKA_EC_PARAMS. Vous pouvez obtenir l'ID objet en recherchant le nom de la courbe dans le référentiel d'ID objet.

Tableau 4. Types de courbe pris en charge pour la génération de clés EC
Mécanisme GREP11 Types de courbe pris en charge Noms de courbe pris en charge
CKM_EC_KEY_PAIR_GEN Courbes du National Institute of Standards and Technology(NIST)
  • P-192, ou secp192r1 et prime192v1.
  • P-224, ou secp224r1.
  • P-256, ou secp256r1 et prime256v1.
  • P-384, ou secp384r1.
  • P-521, ou secp521r.
CKM_EC_KEY_PAIR_GEN Courbes de pool de cerveaux standard(BP)
  • BP-160R, ou brainpoolP160r1.
  • BP-192R, ou brainpoolP192r1.
  • BP-224R ou brainpoolP224r1.
  • BP-256R, ou brainpoolP256r1.
  • BP-320R, ou brainpoolP320r1.
  • BP-384R, ou brainpoolP384r1.
  • BP-512R, ou brainpoolP512r1.
CKM_EC_KEY_PAIR_GEN Courbes Twisted Brain pool(BP)
  • BP-160T, ou brainpoolP160t1.
  • BP-192T, ou brainpoolP192t1.
  • BP-224T, ou brainpoolP224t1.
  • BP-256T, ou brainpoolP256t1.
  • BP-320T, ou brainpoolP320t1.
  • BP-384T, ou brainpoolP384t1.
  • BP-512T, ou brainpoolP512t1.
CKM_EC_KEY_PAIR_GEN Normes relatives aux courbes SEC(Standards for Efficient Cryptography)
  • secp256k1
CKM_EC_KEY_PAIR_GEN Courbes d'Edwards
  • Ed25519

Courbes prises en charge pour le chiffrement des actifs numériques et la génération de signatures

Les courbes suivantes sont prises en charge pour les mécanismes liés à l'actif numérique et à la signature numérique.

Tableau 5. Types de courbe pris en charge pour le chiffrement des actifs numériques et des signatures
Norme et schéma Mécanisme GREP11 Types de courbe pris en charge Noms de courbe pris en charge
BIP32/BIP44 CKM_IBM_BTC_DÉRIVER Normes relatives aux courbes SEC(Standards for Efficient Cryptography)
  • secp256k1
SLIP10 CKM_IBM_BTC_DÉRIVER Courbes du National Institute of Standards and Technology(NIST)
  • P-256, également appelé secp256r1 et prime256v1
SLIP10 CKM_IBM_BTC_DÉRIVER Normes relatives aux courbes SEC(Standards for Efficient Cryptography)
  • secp256k1
SLIP10 CKM_IBM_BTC_DÉRIVER Courbes d'Edwards
  • Ed25519
EdDSA CKM_IBM_ED25519_SHA512 Courbes d'Edwards
  • Ed25519
Schnorr CKM_IBM_ECDSA_OTHER Normes relatives aux courbes SEC(Standards for Efficient Cryptography)
  • secp256k1
Schnorr CKM_IBM_ECDSA_OTHER Courbes du National Institute of Standards and Technology(NIST)
  • P-256, également appelé secp256r1 et prime256v1
Schnorr CKM_IBM_ECDSA_OTHER Courbes de pool de cerveaux standard(BP)
  • BP-256R, également appelé brainpoolP256r1
Schnorr CKM_IBM_ECDSA_OTHER Courbes Twisted Brain pool(BP)
  • BP-256T, également appelé brainpoolP256t1
Schnorr ECSG_IBM_ECSDSA_S256
  • secp256r1
  • secp256k1
  • BP-256R, également appelé brainpoolP256r1
  • BP-256T, également appelé brainpoolP256t1
Schnorr-Zilliqa ECSG_IBM_ECSDSA_COMPR_MULTI
  • secp256r1
  • secp256k1
  • BP-256R, également appelé brainpoolP256r1
  • BP-256T, également appelé brainpoolP256t1

Exécution d'opérations de chiffrement à l'aide de fonctions GREP11

Vous pouvez effectuer des opérations de chiffrement en appelant les fonctions GREP11 qui sont définies en fonction de l'implémentation EP11 de la spécification PKCS #11. Les descriptions de fonction suivantes sont créées en fonction de la spécification PKCS #11, avec des remarques spécifiques à EP11. Toutes les définitions de paramètres se trouvent sous la forme EP11 d'origine. Pour plus d'informations sur EP11, voir Enterprise PKCS #11(EP11)Library structure.

Les paramètres des fonctions EP11 sont mappés aux types de tampon de protocole qui peuvent se trouver dans les fonctions suivantes. Vous pouvez en savoir plus sur les types de mémoire tampon de protocole dans Google Developers.

Puisque la bibliothèque EP11 est un sous-ensemble de la bibliothèque d'API PKCS #11 et que les fonctions GREP11 sont des variantes des fonctions EP11 correspondantes, les fonctions EP11 équivalentes dans EP11 et PKCS #11 sont également répertoriées dans les tableaux de fonctions GREP11 pour votre référence.

GREP11 prend en charge tout langage de programmation avec une bibliothèque gRPC. A l'heure actuelle, seuls des fragments ou des exemples de code pour Golang et JavaScript sont inclus dans la référence d'API. Le contenu sera enrichi ultérieurement. Les fragments de code sont basés sur les référentiels GitHub externes suivants qui fournissent des exemples complets d'utilisation de l'API GREP11. Certains fragments de code font référence à des fonctions d'assistance dans les référentiels d'exemples.

Extraction d'algorithmes de chiffrement pris en charge

Vous pouvez utiliser les fonctions ci-après pour extraire les algorithmes ou des mécanismes de chiffrement qui sont pris en charge par GREP11. Ces informations vous permettent de comprendre les mécanismes spécifiques qui peuvent être définis lorsque vous appelez une fonction. Pour obtenir la liste complète des mécanismes pris en charge, vous pouvez également voir les mécanismes classés par groupes de fonctions.

GetMechanismList

La fonction GetMechanismList permet d'obtenir la liste des types de mécanismes pris en charge par un jeton.

Description Effectue une liaison à la fonction EP11 m_GetMechanismList, qui est une implémentation de la fonction PKCS #11 C_GetMechanismList.
Paramètres
    message GetMechanismListRequest {
    }
    message GetMechanismListResponse {
      repeated uint64 Mechs = 2;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description Implémentation de la fonction PKCS #11 C_GetMechanismList.
Paramètres
    CK_RV m_GetMechanismList (
      CK_SLOT_ID slot,
      CK_MECHANISM_TYPE_PTR mechs, CK_ULONG_PTR mechslen,
      cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GetMechanismList. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

La fonction C_GetMechanismList est utilisé pour obtenir une liste des types de mécanismes pris en charge par un jeton. SlotID est l'ID de l'emplacement du jeton ; pulCount pointe vers l'emplacement qui reçoit le nombre de mécanismes.

Il existe deux façons pour une application d'appeler C_GetMechanismList :

  1. Si pMechanismList est NULL_PTR, tous les paramètres C_GetMechanismList retournent (dans *pulCount) le nombre de mécanismes, sans renvoyer une liste de mécanismes. Le contenu de *pulCount sur l'entrée associée à C_GetMechanismList n'a pas de signification dans ce cas, et l'appel renvoie la valeur CKR_OK.
  2. Si laListe de commande n'est pas NULL_PTR, alors le * comptage doit contenir la taille (en termes d'éléments CK_MÉCANISM_TYPE ) de la mémoire tampon pointée par laliste de commande. Si la taille de ce tampon est suffisante pour contenir la liste des mécanismes, cette dernière y est envoyée et CKR_OK est retourné. Dans le cas contraire, l'appel à C_GetMechanismList renvoie la valeur CKR_BUFFER_TOO_SMALL. Dans un cas comme dans l'autre, la valeur *pulCount est définie pour contenir le nombre de mécanismes.

Comme C_GetMechanismList n'alloue pas d'espace propre, une application appelle souvent C_GetMechanismList deux fois. Ce comportement n'est cependant pas nécessaire.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismList)(
      CK_SLOT_ID slotID,
      CK_MECHANISM_TYPE_PTR pMechanismList,
      CK_ULONG_PTR pulCount
    );
    
Valeur de retour CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, CKR_ARGUMENTS_BAD.

Fragments de code

  • Fragment de code Golang

    GetMechanismListRequest := &pb.GetMechanismListRequest {
    }
    
    GetMechanismListResponse, err := cryptoClient.GetMechanismList(context.Background(), GetMechanismListRequest)
    
  • Fragment de code JavaScript

    client.GetMechanismList({}, (err, data) => {
      if (err) throw err;
    
      console.log('MECHANISMS:', data.Mechs);
    });
    

GetMechanismInfo

La fonction GetMechanismInfo obtient des informations sur un mécanisme particulier.

Description Effectue une liaison à la fonction EP11 m_GetMechanismInfo, qui est une implémentation de la fonction PKCS #11 C_GetMechanismInfo.
Paramètres
    message GetMechanismInfoRequest {
      uint64 Mech = 2;
    }
    message GetMechanismInfoResponse {
      MechanismInfo MechInfo = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description Implémentation de la fonction PKCS #11 C_GetMechanismInfo.
Paramètres
    CK_RV m_GetMechanismInfo (
      CK_SLOT_ID slot,
      CK_MECHANISM_TYPE mech,
      CK_MECHANISM_INFO_PTR mechInfo,
      cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GetMechanismInfo. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_GetmécanismInfo obtient des informations sur un mécanisme particulier pouvant être pris en charge par un jeton. slotID est l'ID de l'emplacement du jeton ; Type est le type de mécanisme ; pInfo pointe vers l'emplacement qui reçoit les informations du mécanisme.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismInfo)(
      CK_SLOT_ID slotID,
      CK_MECHANISM_TYPE type,
      CK_MECHANISM_INFO_PTR pInfo
    );
    
Valeur de retour CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_OK, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, CKR_ARGUMENTS_BAD.

Fragments de code

  • Fragment de code Golang

    GetMechanismInfoRequest := &pb.GetMechanismInfoRequest {
        Mech: ep11.CKM_RSA_PKCS,
    }
    
    GetMechanismInfoResponse, err := cryptoClient.GetMechanismInfo(context.Background(), GetMechanismInfoRequest)
    
  • Fragment de code JavaScript

    client.GetMechanismInfo({
      Mech: ep11.CKM_AES_KEY_GEN
      }, (err, data) => {
        if (err) throw err;
    
        console.log('MECHANISM INFO:', data.MechInfo);
    });
    

Génération et dérivation de clés

GREP11 fournit les fonctions ci-après afin de générer des clés cryptographiques symétriques et asymétriques. En fonction du mécanisme et de la longueur de clé que vous spécifiez, vous pouvez générer différents types de clés pour différents usages. Vous pouvez également dériver une clé depuis une clé de base afin d'étendre des clés dans des clés plus longues ou d'obtenir les clés d'un format requis.

GenerateKey

La fonction GenerateKey génère une clé secrète pour le chiffrement symétrique.

Description Effectue une liaison à la fonction EP11 m_GenerateKey, qui est une implémentation de la fonction PKCS #11 C_GenerateKey.
Paramètres
    message GenerateKeyRequest {
      Mechanism Mech = 1;
      Modèle map<uint64,AttributeValue> = 6 ;
    }
    message GenerateKeyResponse {
      bytes KeyBytes = 4;
      bytes CheckSum = 5;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_GenerateKey.

Les clés TDES sont générées avec une parité correcte, ce qui n'est pas observable par l'hôte. Mais nécessaire pour une interopérabilité adéquate : d'autres implémentations PKCS #11 doivent rejeter les clés DES avec des problèmes de parité.

Si un objet est lié à une session, (pin, plen) doit être renvoyé par Connexion à cette session. Le fait de laisser pin à NULL a pour effet de créer un objet public, non lié à une session de connexion.

(clé, klen) renvoie l'objet blob de clés. (csum, clen) contient la somme de contrôle de la clé, c'est-à-dire les octets les plus significatifs d'un bloc tous zéro chiffré par la clé. NULL clen est possible, pour les mécanismes de clé symétrique, par exemple, sans paramètres CKA_CHECK_VALUE (comme RC4).

ptempl n'est utilisé que si la longueur de clé (soit l'attribut CKA_VALUE_LEN attribute) est requise par le mécanisme. Si ce dernier spécifie implicitement la taille de la clé, aucune vérification de taille n'est effectuée pour ptempl.

La génération de paramètres DSA et DH ignore (csum, clen), générant uniquement des structures de paramètres.

Paramètres DSA, DH (CKM_DSA_PARAMETER_GEN) : nombre de bits du module de transmission dans CKA_PRIME_BITS des attributs. Ecrit la structure P,Q,G en tant que sortie en texte en clair (et donc pas en tant qu'objet blob).

L'objet blob pin est généré en sortie de Login.

L'élément PKCS #11 phKey n'est mappé à aucun paramètre EP11. (La bibliothèque hôte doit lier la clé encapsulée au descripteur.)

Paramètres
    CK_RV m_GenerateKey (
      CK_MECHANISM_PTR mech,
      CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
      const unsigned char *pin, size_t pinlen,
      unsigned char * key, size_t * keylen,
      unsigned char *checkSum, size_t *checkSumlen,
      cible target_t
      );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GenerateKey. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_GenerateKey génère une clé secrète ou un ensemble de paramètres de domaine, créant un nouvel objet. HSession est l'indicateur de la session ; Mécanisme pointe vers le mécanisme de génération ; Canevas pointe vers le modèle pour la nouvelle clé ou l'ensemble de paramètres de domaine ; UlCount est le nombre d'attributs dans le modèle ; PhKey pointe vers l'emplacement qui reçoit le descripteur de la nouvelle clé ou de l'ensemble de paramètres de domaine.

Si le mécanisme de génération est pour la génération de paramètres de domaine, l'attribut CKA_CLASSE a la valeur PARAMÈTRE_DOMAINE_CKO_; sinon, il a la valeur CKO_SECRET_CLÉ.

Etant donné que le type de clé ou de paramètres de domaine à générer est implicite dans le mécanisme de génération, le modèle n'a pas besoin de fournir un type de clé. S'il fournit un type de clé incohérent avec le mécanisme de génération, C_GenerateKey échoue et renvoie le code d'erreur CKR_TEMPLATE_INCOHÉRENCE. L'attribut CKA_CLASSE est traité de la même manière.

Si un appel à C_GenerateKey ne peut pas prendre en charge le modèle précis qui lui est fourni, il échoue et est renvoyé sans créer d'objet.

L'objet créé par un appel réussi à C_GenerateKey a l'attribut CKA_LOCAL défini sur CK_TRUE.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GenerateKey)(
      CK_SESSION_HANDLE hSession
      CK_MECHANISM_PTR pMechanism,
      CK_ATTRIBUTE_PTR pTemplate,
      CK_ULONG ulCount,
      CK_OBJECT_HANDLE_PTR phKey
      );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Setup the AES key's attributes
    keyTemplate := ep11.EP11Attributes{
        ep11.CKA_VALUE_LEN:   keyLen / 8,
        ep11.CKA_WRAP:        false,
        ep11.CKA_UNWRAP:      false,
        ep11.CKA_ENCRYPT:     true,
        ep11.CKA_DECRYPT:     true,
        ep11.CKA_EXTRACTABLE: false,
    }
    
    GenerateKeyRequest := &pb.GenerateKeyRequest{
        Mech:     &pb.Mechanism{Mechanism: ep11.CKM_AES_KEY_GEN},
        Template: util.AttributeMap(keyTemplate),
    }
    
    GenerateKeyResponse, err := cryptoClient.GenerateKey(context.Background(), GenerateKeyRequest)
    
  • Fragment de code JavaScript

    let keyLen = 128;
    
    let keyTemplate = new util.AttributeMap(
      new util.Attribute(ep11.CKA_VALUE_LEN, keyLen / 8),
      new util.Attribute(ep11.CKA_WRAP, false),
      new util.Attribute(ep11.CKA_UNWRAP, false),
      new util.Attribute(ep11.CKA_ENCRYPT, true),
      new util.Attribute(ep11.CKA_DECRYPT, true),
      new util.Attribute(ep11.CKA_EXTRACTABLE, false),
      new util.Attribute(ep11.CKA_TOKEN, true)
      );
    client.GenerateKey({
      Mech: { Mechanism: ep11.CKM_AES_KEY_GEN },
      Template: keyTemplate,
      KeyId: uuidv4()
    }, (err, data={}) => {
      cb(err, data.KeyBytes, data.CheckSum);
    });
    
    

GenerateKeyPair

La fonction GenerateKeyPair génère une paire de clé publique et de clé privée.

Description Effectue une liaison à la fonction EP11 m_GenerateKeyPair, qui est une implémentation de la fonction PKCS #11 C_GenerateKeyPair.
Paramètres
    message GenerateKeyPairRequest {
      Mechanism Mech = 1;
      map<uint64,AttributeValue> PrivKeyTemplate = 7 ;
      map<uint64,AttributeValue> PubKeyTemplate = 8 ;
      }
    message GenerateKeyPairResponse {
      bytes PrivKeyBytes = 5;
      bytes PubKeyBytes = 6;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_GenerateKeyPair.

Les paramètres de paire de clés sont extraits des paramètres pmech, ppublic et pprivate. Pour les clés RSA, ppublic spécifie la taille de module.

En mode FIPS, seuls les modules RSA de 1024 + 256 N octets sont pris en charge (entier N). Le mode non FIPS peut générer des clés d'un nombre pair de bits compris entre les limites de la liste de paramètres du mécanisme.

La clé publique est formatée comme un SPKI standard (sujet d'information de clé publique), lisible par la plupart des bibliothèques. Son intégrité est protégée par un code d'authentification de message spécifique au transport, qui ne fait pas partie du SPKI lui-même. La génération de paramètres DSA renvoie une structure non SPKI dans la zone de clé publique.

Si vous associez un objet à une session, (pin, plen) doit être renvoyé par Connexion à cette session. Le fait de laisser pin à la valeur NULL crée un objet public, qui survit à la session de connexion.

Retourne une clé privée encapsulée à (key, klen), une clé publique en tant que structure ASN.1/DER associée à un élément MAC dans (pubkey, pklen).

Les combinaisons de paramètres prises en charge suivantes avec des notes spéciales vont au-delà de ce qui est documenté par PKCS #11 :

Les clés RSA rejettent les exposants publics au-dessous de 17 (0x11). Les points de contrôle peuvent restreindre davantage le minimum accepté. L'exposant Fermat4, 0x10001, est contrôlé par un point de contrôle spécifique, correspondant aux restrictions de l'exposant public de FIPS 186-3 (section B. 3.1).

Les paramètres de courbe (CKM_EC_KEY_PAIR_GEN) de clés EC peuvent être spécifiés en tant qu'identificateurs OID ou comme noms symboliques (variante namedCurve). Les noms symboliques pris en charge sont "P-nnn" pour les courbes NIST (nnn est un nombre de bits préférentiel pris en charge, 192-521), "BP-nnnR" pour la courbe BP normale. (Les noms doivent être fournis sous forme de chaînes ASCII, non terminées par des valeurs nulles.)

Les clés DSA (CKM_DSA_KEY_PAIR_GEN) passent la structure P,Q,G en tant qu'attribut CKA_IBM_STRUCT_PARAMS d'attributs publics. Les paramètres P, Q, G individuels peuvent ne pas être transmis par des paramètres PKCS #11 normaux, ils doivent être combinés en une structure unique.

Les clés DH (CKM_DH_PKCS_KEY_PAIR_GEN) passent la structure P,G en tant qu'attribut CKA_IBM_STRUCT_PARAMS d'attributs publics. Les paramètres P,G individuels peuvent ne pas être transmis par des paramètres PKCS #11 normaux, ils doivent être combinés en une structure unique. Lorsque vous sélectionnez un nombre de bits de clé privée (X), utilisez l'attribut XCP_U32_VALUE_BITS. S'il n'est pas présent, ou si un 0 explicite est fourni, le nombre de bits est sélectionné en fonction d'un nombre de bits P.

L'utilisation de l'état de session (Connexion) remplace l'utilisation standard des sessions. Le mappage est en dehors de la portée de la bibliothèque.

L'objet blob pin est généré en sortie de Login.

L'élément PKCS #11 hSession n'est mappé à aucun paramètre EP11. (L'appel n'est pas directement associé à une session.)

L'élément PKCS #11 phPublicKey n'est mappé à aucun paramètre EP11. (La bibliothèque hôte doit associer pubkey (SPKI) à un descripteur.)

L'élément PKCS #11 phPrivateKey n'est mappé à aucun paramètre EP11. (La bibliothèque hôte doit associer une clé privée à un descripteur.)

Paramètres
    CK_RV m_GenerateKeyPair (
      CK_MECHANISM_PTR mech,
      CK_ATTRIBUTE_PTR pubKeyTemplate, CK_ULONG pubKeyTemplatelen,
      CK_ATTRIBUTE_PTR privKeyTemplate, CK_ULONG privKeyTemplatelen,
      const unsigned char *pin, size_t pinlen,
      unsigned char *privKey, size_t *privKeylen,
      unsigned char *pubKey, size_t *pubKeylen,
      cible target_t
      );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GenerateKeyPair. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_GenerateKeyPair génère une paire de clés publiques et privées, créant de nouveaux objets clés. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme de génération de clés ; pPublicKeyTemplate pointe vers le modèle pour la clé publique ; ulPublicKeyAttributeCount est le nombre d'attributs dans le modèle de clé publique ; pPrivateKeyTemplate pointe vers le modèle pour la clé privée ; ulPrivateKeyAttributeCount est le nombre d'attributs dans le modèle de clé privée ; phPublicKey pointe vers l'emplacement qui reçoit le descripteur de la nouvelle clé publique ; phPrivateKey pointe vers l'emplacement qui reçoit la poignée de la nouvelle clé privée.

Puisque les types de clés à générer sont implicites dans le mécanisme de génération des paires de clés, les modèles n'ont pas besoin de fournir les types de clé. Si l'un des modèles fournit un type de clé qui n'est pas cohérent avec le mécanisme de génération de clés, C_GenerateKeyPair échoue et renvoie le code d'erreur CKR_TEMPLATE_INCOHÉRENCE. L'attribut CKA_CLASS est traité de façon similaire.

Si un appel à C_GenerateKey ne peut pas prendre en charge les modèles précis qui lui sont fournis, il échoue et est renvoyé sans créer d'objets de clé.

Un appel à C_GenerateKeyPair ne crée jamais une seule clé et est renvoyé. Un appel peut échouer et ne pas créer de clés ; ou il peut réussir et créer une paire de clés publiques et privées correspondantes.

Les objets clés créés par un appel réussi à C_GenerateKeyPair ont les attributs CKA_LOCAL définis sur CK_TRUE.

Notez avec soin l'ordre des arguments dans C_GenerateKeyPair. Les deux derniers arguments n'ont pas le même ordre que dans le document Cryptoki version 1.0 d'origine. L'ordre de ces deux arguments a causé malheureusement une certaine confusion.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GenerateKeyPair)(
      CK_SESSION_HANDLE hSession,
      CK_MECHANISM_PTR pMechanism,
      CK_ATTRIBUTE_PTR pPublicKeyTemplate,
      CK_ULONG ulPublicKeyAttributeCount,
      CK_ATTRIBUTE_PTR pPrivateKeyTemplate,
      CK_ULONG ulPrivateKeyAttributeCount,
      CK_OBJECT_HANDLE_PTR phPublicKey,
      CK_OBJECT_HANDLE_PTR phPrivateKey
      );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Generate RSA key pair
    publicExponent := []byte{0x11}
    publicKeyTemplate := ep11.EP11Attributes{
        ep11.CKA_ENCRYPT:         true,
        ep11.CKA_VERIFY:          true,
        ep11.CKA_MODULUS_BITS:    2048,
        ep11.CKA_PUBLIC_EXPONENT: publicExponent,
        ep11.CKA_EXTRACTABLE:     false,
    }
    privateKeyTemplate := ep11.EP11Attributes{
        ep11.CKA_PRIVATE:     true,
        ep11.CKA_SENSITIVE:   true,
        ep11.CKA_DECRYPT:     true,
        ep11.CKA_SIGN:        true,
        ep11.CKA_EXTRACTABLE: false,
    }
    GenerateKeypairRequest := &pb.GenerateKeyPairRequest{
        Mech:            &pb.Mechanism{Mechanism: ep11.CKM_RSA_PKCS_KEY_PAIR_GEN},
        PubKeyTemplate:  util.AttributeMap(publicKeyTemplate),
        PrivKeyTemplate: util.AttributeMap(privateKeyTemplate),
    }
    GenerateKeyPairResponse, err := cryptoClient.GenerateKeyPair(context.Background(), GenerateKeypairRequest)
    
  • Fragment de code JavaScript

    const publicKeyTemplate = new util.AttributeMap(
      new util.Attribute(ep11.CKA_ENCRYPT, true),
      new util.Attribute(ep11.CKA_VERIFY, true),
      new util.Attribute(ep11.CKA_MODULUS_BITS, 2048),
      new util.Attribute(ep11.CKA_PUBLIC_EXPONENT, publicExponent),
      new util.Attribute(ep11.CKA_EXTRACTABLE, false)
    );
    
    const privateKeyTemplate = new util.AttributeMap(
      new util.Attribute(ep11.CKA_PRIVATE, true),
      new util.Attribute(ep11.CKA_SENSITIVE, true),
      new util.Attribute(ep11.CKA_DECRYPT, true),
      new util.Attribute(ep11.CKA_SIGN, true),
      new util.Attribute(ep11.CKA_EXTRACTABLE, false),
    );
    
    client.GenerateKeyPair({
      Mech: {
        Mechanism: ep11.CKM_RSA_PKCS_KEY_PAIR_GEN
      },
      PubKeyTemplate: publicKeyTemplate,
      PrivKeyTemplate: privateKeyTemplate,
      PubKeyId: uuidv4(),
      PrivKeyId: uuidv4()
    }, (err, response) => {
      callback(err, response);
    });
    

DeriveKey

La fonction DeriveKey dérive une clé depuis une clé de base.

Description Effectue une liaison à la fonction EP11 m_DeriveKey, qui est une implémentation de la fonction PKCS #11 C_DeriveKey.
Paramètres
    message DeriveKeyRequest {
        Mechanism Mech = 1;
        bytes BaseKey = 3;
        bytes Data = 4;
        Modèle map<uint64,AttributeValue> = 8 ;
    }
    message DeriveKeyResponse {
        bytes NewKeyBytes = 6;
        bytes CheckSum = 7;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DeriveKey.

L'objet blob basekey,bklen doit être mappé à partir du paramètre PKCS #11 hBaseKey.

L'élément PKCS #11 hSession n'est mappé à aucun paramètre EP11. (L'appel n'est pas directement associé à une session.)

L'élément PKCS #11 phKey n'est mappé à aucun paramètre EP11. (La bibliothèque hôte doit lier la clé retournée au descripteur.)

Paramètres
    CK_RV m_DeriveKey (
        CK_MECHANISM_PTR mech,
        CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
        const unsigned char *baseKey, size_t baseKeylen,
        const unsigned char *data, size_t datalen,
        const unsigned char *pin, size_t pinlen,
        unsigned char *newKey, size_t *newKeylen,
        unsigned char *checkSum, size_t *checkSumlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DeriveKey. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DeriveKey dérive une clé d'une clé de base, créant un nouvel objet clé. HSession est le descripteur de la session ; pMechanism pointe vers une structure qui spécifie le chanisme de dérivation de clé ; hBaseKey est l'indicateur de la Clé de base ; pTemplate pointe vers le modèle pour la nouvelle clé ; ulAttributeCount est le nombre d'attributs dans le modèle ; et PhKey pointe vers l'emplacement qui reçoit la poignée de la clé dérivée.

Les valeurs des attributs CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE et KA_NEVER_EXTRACTABLE de la clé de base affectent les valeurs que ces attributs peuvent contenir pour la clé nouvellement dérivée. Voir la description de chaque mécanisme de dérivation de clé dans la section 5.16.2 de la Spécification de l'interface de programmation PKCS #11 pour toutes les contraintes de ce type.

Si un appel à C_DeriveKey ne peut pas prendre en charge le modèle précis qui lui est fourni, il échoue et est renvoyé sans créer d'objet de clé.

L'objet de clé créé par un appel réussi à C_DeriveKey a l'attribut CKA_LOCAL défini sur CK_FALSE.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DeriveKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hBaseKey,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulAttributeCount,
        CK_OBJECT_HANDLE_PTR phKey
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN

Fragments de code

  • Fragment de code Golang

    // Derive AES key for Alice
    deriveKeyTemplate := ep11.EP11Attributes{
        ep11.CKA_CLASS:     ep11.CKO_SECRET_KEY,
        ep11.CKA_KEY_TYPE:  ep11.CKK_AES,
        ep11.CKA_VALUE_LEN: 128 / 8,
        ep11.CKA_ENCRYPT:   true,
        ep11.CKA_DECRYPT:   true,
    }
    // Extract Bob's EC coordinates
    combinedCoordinates, err := util.GetPubkeyBytesFromSPKI(bobECKeypairResponse.PubKeyBytes)
    if err != nil {
        return nil, fmt.Errorf("Bob's EC public key cannot obtain coordinates: %s", err)
    }
    
    aliceDeriveKeyRequest := &pb.DeriveKeyRequest{
        Mech:     &pb.Mechanism{Mechanism: ep11.CKM_ECDH1_DERIVE, Parameter: util.SetMechParm(combinedCoordinates)},
        Template: util.AttributeMap(deriveKeyTemplate),
        BaseKey:  aliceECKeypairResponse.PrivKeyBytes,
    }
    
    // Derive AES key for Alice
    aliceDeriveKeyResponse, err := cryptoClient.DeriveKey(context.Background(),  aliceDeriveKeyRequest)
    
  • Fragment de code JavaScript

    //results are created through GenerateKeyPair
    const [alice, bob] = results;
    
    const deriveKeyTemplate = new util.AttributeMap(
    new util.Attribute(ep11.CKA_CLASS, ep11.CKO_SECRET_KEY),
    new util.Attribute(ep11.CKA_KEY_TYPE, ep11.CKK_AES),
    new util.Attribute(ep11.CKA_VALUE_LEN, 128/8),
    new util.Attribute(ep11.CKA_ENCRYPT, true),
    new util.Attribute(ep11.CKA_DECRYPT, true),
    );
    
    const derived = [];
    
    async.eachSeries([
    { PubKey: bob.PubKeyBytes, PrivKey: alice.PrivKeyBytes },
    { PubKey: alice.PubKeyBytes, PrivKey: bob.PrivKeyBytes }
    ], (data, cb) => {
    const combinedCoordinates = util.getPubKeyBytesFromSPKI(data.PubKey);
    
    client.DeriveKey({
      Mech: {
        Mechanism: ep11.CKM_ECDH1_DERIVE,
        ParameterB: combinedCoordinates
      },
      Template: deriveKeyTemplate,
      BaseKey: data.PrivKey
    }, (err, data={}) => {
      if (!err) {
        derived.push(data);
      }
    
      cb(err);
    });
    }
    

Protection des clés

Vous pouvez protéger une clé en l'encapsulant, puis la déchiffrer en appelant la fonction de désencapsulage.

WrapKey

La fonction WrapKey encapsule (chiffre) une clé.

Description Effectue une liaison à la fonction EP11 m_WrapKey, qui est une implémentation de la fonction PKCS #11 C_WrapKey.
Paramètres
    message WrapKeyRequest {
        bytes Key = 1;
        bytes KeK = 2;
        bytes MacKey = 3;
        Mechanism Mech = 4;
    }
    message WrapKeyResponse {
        bytes Wrapped = 5;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description Implémentation de la fonction PKCS #11 C_WrapKey.
Paramètres
    CK_RV m_WrapKey (
        const unsigned char *key, size_t keylen,
        const unsigned char *keK, size_t keKlen,
        const unsigned char *macKey, size_t macKeylen,
        const CK_MECHANISM_PTR mech,
        CK_BYTE_PTR wrapped, CK_ULONG_PTR wrappedlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_WrapKey return values. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_WrapKey encapsule (c'est-à-dire chiffre) une clé privée ou secrète. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme d'encapsulage ; hWrappingKey est le descripteur de la clé d'encapsulage ; HKey est le descripteur de la clé à encapsuler ; PWrappedKey pointe vers l'emplacement qui reçoit la clé encapsulée ; et PulWrappedKeyLen pointe vers l'emplacement qui reçoit la longueur de la clé encapsulée.

C_WrapKey utilise la convention décrite à la section 5.2 de la Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'attribut CKA_WRAP de la clé d'encapsulage, qui indique si la clé prend en charge l'encapsulage, doit être CK_TRUE. L'attribut CKA_EXTRACTABLE de la clé à encapsuler doit aussi être CK_TRUE.

Si la clé à encapsuler ne peut pas être chiffrée pour une raison en rapport avec le jeton, en dépit du fait que son attribut CKA_EXTRACTABLE est défini à CK_TRUE, C_WrapKey échoue avec le code d'erreur CKR_KEY_NOT_WRAPPABLE. Si elle ne peut pas être encapsulée avec la clé et le mécanisme d'encapsulage spécifiés, C_WrapKey échoue avec le code d'erreur CKR_KEY_SIZE_RANGE.

C_WrapKey peut être utilisé dans les situations suivantes :

  • Pour encapsuler une clé secrète avec une clé publique qui prend en charge le chiffrement et le déchiffrement.
  • Pour encapsuler une clé secrète avec une autre clé secrète. Une attention particulière doit être accordée à la taille des clés et à la force du mécanisme sinon le jeton risque de ne pas autoriser l'opération.
  • Pour encapsuler une clé privée avec une clé secrète.

Les jetons varient selon les types de clés qui peuvent être encapsulés par les mécanismes utilisés.

Pour partitionner les clés d'encapsulage de sorte qu'elles ne puissent encapsuler qu'un sous-ensemble de clés extractibles, l'attribut CKA_WRAP_MODÈLE peut être utilisé sur la clé d'encapsulage pour spécifier un ensemble d'attributs pouvant être comparé aux attributs de la clé à encapsuler. Si tous les attributs correspondent selon les règles C_FindObject de correspondance d'attributs, l'opération d'encapsulage s'effectue. La valeur de cet attribut est un modèle d'attribut et la taille est le nombre d'éléments dans le modèle multiplié par la taille de CK_ATTRIBUTE. Si cet attribut n'est pas fourni, tout modèle est acceptable. Si un attribut n'est pas présent, il n'est pas vérifié. Si une non concordance d'attribut se produit lors d'une tentative d'encapsulage d'une clé, la fonction renvoie CKR_KEY_HANDLE_INVALID.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_WrapKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hWrappingKey,
        CK_OBJECT_HANDLE hKey,
        CK_BYTE_PTR pWrappedKey,
        CK_ULONG_PTR pulWrappedKeyLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, CKR_KEY_NOT_WRAPPABLE, CKR_KEY_SIZE_RANGE, CKR_KEY_UNEXTRACTABLE, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_WRAPPING_KEY_HANDLE_INVALID, CKR_WRAPPING_KEY_SIZE_RANGE, CKR_WRAPPING_KEY_TYPE_INCONSISTENT.

Fragments de code

  • Fragment de code Golang

    WrapKeyRequest := &pb.WrapKeyRequest {
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_RSA_PKCS},
        KeK:  GenerateKeyPairResponse.PubKeyBytes,
        Key:  GenerateKeyResponse.KeyBytes,
    }
    
    WrapKeyResponse, err := cryptoClient.WrapKey(context.Background(), WrapKeyRequest)
    
  • Fragment de code JavaScript

    client.WrapKey({
      Mech: {
        Mechanism: ep11.CKM_RSA_PKCS
      },
      KeK: rsa.PubKeyBytes,
      Key: aes.KeyBytes
    }, (err, data={}) => {
      cb(err, data.Wrapped);
    });
    

UnwrapKey

La fonction UnwrapKey désencapsule (déchiffre) une clé.

Description Effectue une liaison à la fonction EP11 m_UnwrapKey, qui est une implémentation de la fonction PKCS #11 C_UnwrapKey.
Paramètres
    message UnwrapKeyRequest {
        bytes Wrapped = 1;
        bytes KeK = 2;
        bytes MacKey = 3;
        Mechanism Mech = 5;
        Modèle map<uint64,AttributeValue> = 9 ;
    }
    message UnwrapKeyResponse {
        bytes UnwrappedBytes = 7;
        bytes CheckSum = 8;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_UnwrapKey.

Uwmech indique le mécanisme de chiffrement utilisé pour déchiffrer les données encapsulées. Templ est une liste de paramètres Clé (paire), indiquant comment transformer les données non encapsulées en une nouvelle clé (doit inclure TYPE_CLÉ_TYPE).

L'objet généré est renvoyé sous la forme (unwrapped, uwlen), en tant qu'objet blob. Les clés symétriques renvoient leur clé de contrôle (3 octets) sous la forme (csum, cslen) ; les objets de clé publique renvoient leur clé publique en tant qu'informations SPKI dans (csum, cslen). Les deux formes sont suivies d'une valeur au format big endian de 4 octets, qui code le nombre de bits de la clé non encapsulée.

Lorsqu'un SPKI est transformé en SPKI MACed, il faut utiliser CKM_IBM_TRANSPORTKEY comme mécanisme de désencapsulage. Ce mode fournit les informations SPKI brutes sous forme de données encapsulées et ignore la clé KEK (Key Encryption Key).

UnwrapKey produit des clés DES ajustées en parité (dans les blobs), mais tolère les entrées avec une parité incorrecte.

Paramètres
    CK_RV m_UnwrapKey (
        const CK_BYTE_PTR wrapped, CK_ULONG wrappedlen,
        const unsigned char *keK, size_t keKlen,
        const unsigned char *macKey, size_t macKeylen,
        const unsigned char *pin, size_t pinlen,
        const CK_MECHANISM_PTR mech,
        const CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
        unsigned char * unwrap, size_t * unwrappedlen,
        CK_BYTE_PTR checkSum, CK_ULONG *checkSumlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_UnwrapKey. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_UnwrapKey désencapsule(c'est à dire, déchiffre) une clé encapsulée, créant une nouvelle clé privée ou un objet de clé secrète. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme de décompression ; hUnwrappingKey est le descripteur de la clé de décompression ; PWrappedKey pointe vers la clé encapsulée ; UlWrappedKeyLen est la longueur de la clé encapsulée ; pTemplate pointe vers le modèle pour la nouvelle clé ; ulAttributeCount est le nombre d'attributs dans le modèle ; PhKey pointe vers l'emplacement qui reçoit la poignée de la clé récupérée.

L'attribut CKA_UNWRAP de la clé de désencapsulage, qui indique si la clé prend en charge l'encapsulage, doit être CK_TRUE.

La nouvelle clé a l'attribut CKA_ALWAYS_SENSITIVE défini sur CK_FALSEet l'attribut CKA_NEVER_EXTRACTABLE défini sur CK_FALSE. L'attribut CKA_EXTRACTABLE est défini par défaut à CK_TRUE.

Certains mécanismes peuvent modifier ou tenter de modifier le contenu de la structure pMechanism en même temps que la clé est désencapsulée.

Si un appel à C_UnwrapKey ne peut pas prendre en charge le modèle précis qui lui est fourni, il échoue et est renvoyé sans créer d'objet de clé.

L'objet de clé créé par un appel réussi à C_UnwrapKey a l'attribut CKA_LOCAL défini sur CK_FALSE.

Pour partitionner les clés de désencapsulage afin qu'elles puissent désencapsuler uniquement un sous-ensemble de clés, l'attribut CKA_UNWRAP_TEMPLATE peut être utilisé sur la clé de désencapsulage pour spécifier un ensemble d'attributs ajouté aux attributs de la clé à désencapsuler. Si les attributs ne sont pas en conflit avec le modèle d'attribut fourni par l'utilisateur, dans pTemplate, l'opération de désencapsulage se poursuit. La valeur de cet attribut est un modèle d'attribut et la taille est le nombre d'éléments dans le modèle multiplié par la taille de CK_ATTRIBUTE. Si cet attribut n'est pas présent sur la clé de désencapsulage, aucun attribut supplémentaire n'est ajouté. Si un conflit d'attributs se produit lors d'une tentative de déencapsulage d'une clé, la fonction SHALL renvoie CKR_TEMPLATE_INCOHÉRENCE.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_UnwrapKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hUnwrappingKey,
        CK_BYTE_PTR pWrappedKey,
        CK_ULONG ulWrappedKeyLen,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulAttributeCount,
        CK_OBJECT_HANDLE_PTR phKey
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_UNWRAPPING_KEY_HANDLE_INVALID, CKR_UNWRAPPING_KEY_SIZE_RANGE, CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT, CKR_USER_NOT_LOGGED_IN, CKR_WRAPPED_KEY_INVALID, CKR_WRAPPED_KEY_LEN_RANGE

Fragments de code

  • Fragment de code Golang

    aesUnwrapKeyTemplate := ep11.EP11Attributes{
        ep11.CKA_CLASS:       ep11.CKO_SECRET_KEY,
        ep11.CKA_KEY_TYPE:    ep11.CKK_AES,
        ep11.CKA_VALUE_LEN:   128 / 8,
        ep11.CKA_ENCRYPT:     true,
        ep11.CKA_DECRYPT:     true,
        ep11.CKA_EXTRACTABLE: true, // must be true to be wrapped
    }
    UnwrapKeyRequest := &pb.UnwrapKeyRequest{
        Mech:     &pb.Mechanism{Mechanism: ep11.CKM_RSA_PKCS},
        KeK:      GenerateKeyPairResponse.PrivKeyBytes,
        Wrapped:  WrapKeyResponse.Wrapped,
        Template: util.AttributeMap(aesUnwrapKeyTemplate),
    }
    
    // Unwrap the AES key
    UnwrapKeyResponse, err := cryptoClient.UnwrapKey(context.Background(), UnwrapKeyRequest)
    
  • Fragment de code JavaScript

    const aesUnwrapKeyTemplate = new util.AttributeMap(
    new util.Attribute(ep11.CKA_CLASS, ep11.CKO_SECRET_KEY),
    new util.Attribute(ep11.CKA_KEY_TYPE, ep11.CKK_AES),
    new util.Attribute(ep11.CKA_VALUE_LEN, 128/8),
    new util.Attribute(ep11.CKA_ENCRYPT, true),
    new util.Attribute(ep11.CKA_DECRYPT, true),
    new util.Attribute(ep11.CKA_EXTRACTABLE, true)
    );
    
    client.UnwrapKey({
        Mech: {
            Mechanism: ep11.CKM_RSA_PKCS
        },
        KeK: rsa.PrivKeyBytes,
        Wrapped: wrapped,
        Template: aesUnwrapKeyTemplate
    }, (err, data={}) => {
        cb(err, wrapped, data.UnwrappedBytes, data.CheckSum);
    });
    

RewrapKeyBlob

La fonction RewrapKeyBlob chiffre à nouveau les objets BLOB générés avec la nouvelle clé principale validée qui est contenue dans le module HSM. Les clés qui sont à nouveau chiffrées ne peuvent être utilisées qu'une fois le module HSM finalisé avec la nouvelle clé principale validée.

Cette fonction est une commande d'administration particulière prise en charge uniquement par GREP11. Il n'existe pas de fonction EP11 ni PKCS #11 pour RewrapKeyBlob.

Description Transfère la propriété d'un BLOB qui est contrôlé par la clé principale en cours vers la nouvelle clé principale lorsque celle-ci est validée.
Paramètres
    message RewrapKeyBlobRequest {
    	bytes WrappedKey = 1;
    }
    message RewrapKeyBlobResponse {
    	bytes RewrappedKey = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.

Fragments de code

  • Fragment de code Golang

    RewrapKeyBlobRequest := &pb.RewrapKeyBlobRequest {
        WrappedKey: GenerateKeyResponse.KeyBytes,
    }
    
    // Rewrap an existing key blob using the HSM's new wrapping key
    RewrapKeyBlobResponse, err := cryptoClient.RewrapKeyBlob(context.Background(),  RewrapKeyBlobRequest)
    
  • Fragment de code JavaScript

    client.RewrapKeyBlob({
      WrappedKey: wrappedKey
    }, (err, response) => {
      callback(err, response);
    });
    

Extraction et modification d'attributs pour les clés

Lorsque vous générez des clés ou effectuez des opérations de clé, vous définissez un modèle d'attribut comme l'un des paramètres. Vous pouvez extraire les attributs d'un objet de clé spécifique et modifier certains attributs une fois la clé créée.

GetAttributeValue

La fonction GetAttributeValue obtient une valeur d'attribut d'un objet.

Description Effectue une liaison à la fonction EP11 m_GetAttributeValue, qui est une implémentation de la fonction PKCS #11 C_GetAttributeValue.
Paramètres
    message GetAttributeValueRequest {
        bytes Object = 1;
        Attributs map<uint64,AttributeValue> = 3 ;
    }
    message GetAttributeValueResponse {
        Attributs map<uint64,AttributeValue> = 4 ;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_GetAttributeValue.

N'utilise pas le paramètre hSession, car ne représente pas ou n'a pas besoin de sessions (partie d'objet blob).

EP11 utilise des méthodes plus simples pour décoder, comme l'énumération des valeurs effectives au lieu de rester plus générique.

Paramètres
    CK_RV m_GetAttributeValue (
        const unsigned char *object, size_t objectlen,
        CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeslen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GetAttributeValue. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_GetAttributeValue obtient la valeur d'un ou plusieurs attributs d'un objet. HSession est le descripteur de la session ; HObjet est le descripteur de l'objet ; pTemplate pointe vers un modèle qui spécifie les valeurs d'attribut à obtenir et reçoit les valeurs d'attribut ; UlCount est le nombre d'attributs dans le modèle.

Pour chaque élément triple (type, pValue, ulValueLen) du modèle, C_GetAttributeValue effectue l'algorithme suivant

  1. Si l'attribut spécifié (par la zone de type) pour l'objet est sensible ou non extractible, la zone ulValueLen de cet élément triple est modifiée pour contenir la valeur CK_UNAVAILABLE_INFORMATION.
  2. Autrement, si la valeur spécifiée pour l'objet n'est pas valide (l'objet ne possède pas un tel attribut), la zone ulValueLen de cet élément triple est modifiée pour contenir la valeur CK_UNAVAILABLE_INFORMATION.
  3. Autrement, si la zone pValue comporte la valeur NULL_PTR, la zone ulValueLen est modifiée pour contenir la longueur exacte de l'attribut spécifié pour l'objet.
  4. Sinon, si la longueur indiquée dans ulValueLen est suffisante pour contenir la valeur de l'attribut indiqué pour l'objet, alors cet attribut est copié dans la mémoire tampon qui est à pValue, et la zone ulValueLen est modifiée pour contenir la longueur exacte de l'attribut.
  5. Autrement, la zone ulValueLen est modifiée pour contenir la valeur CK_UNAVAILABLE_INFORMATION.

Si le cas 1 s'applique à l'un des attributs demandés, l'appel doit renvoyer la valeur CKR_ATTRIBUTE_SENSITIVE. Si le cas 2 s'applique à l'un des attributs demandés, l'appel doit renvoyer la valeur CKR_ATTRIBUTE_TYPE_INVALID. Si le cas 5 s'applique à l'un des attributs demandés, l'appel doit renvoyer la valeur CKR_BUFFER_TOO_SMALL. Comme d'habitude, si plusieurs de ces codes d'erreur sont applicables, Cryptoki peut renvoyer n'importe lequel d'entre eux. Si aucun d'entre eux ne s'applique à l'un des attributs demandés, CKR_OK est renvoyé.

Dans le cas particulier d'un attribut dont la valeur est un tableau d'attributs, par exemple CKA_WRAP_MODÈLE, où il est transmis avec pValue non NULL, alors si la pValue des éléments de la matrice est NULL_PTR, alors le UlValueLen des éléments de la matrice est défini sur la longueur requise. Si la valeur pValue des éléments dans la matrice n'est pas NULL_PTR, l'élément ulValueLen des attributs dans cette matrice doit refléter l'espace vers lequel pointe la valeur pValue correspondante, et pValue est rempli, s'il y a suffisamment de place. Par conséquent, il est important d'initialiser le contenu d'une mémoire tampon avant que C_GetAttributeValue ne soit appelée pour obtenir une valeur de tableau de ce type. Si une valeur ulValueLen de la grappe n'est pas suffisamment grande, elle est définie sur CK_UNAVAILABLE_INFORMATION et la fonction renvoie CKR_BUFFER_TOO_SMALL, comme elle le fait si un attribut de l'argument pTemplate a une valeur ulValueLen trop petite. Tout attribut dont la valeur est une grappe d'attributs est identifiable par l'ensemble CKF_ARRAY_ATTRIBUTE du type d'attribut.

Les codes d'erreur CKR_ATTRIBUTE_SENSITIVE, CKR_ATTRIBUTE_TYPE_INVALID et CKR_BUFFER_TOO_SMALL ne signalent pas les erreurs réelles pour C_GetAttributeValue. Si un appel à C_GetAttributeValue renvoie l'une de ces trois valeurs, l'appel doit néanmoins avoir traité chaque attribut du modèle fourni à C_GetAttributeValue. Chaque attribut du modèle dont la valeur peut être renvoyée par l'appel à C_GetAttributeValue est renvoyé par l'appel à C_GetAttributeValue.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GetAttributeValue)(
        CK_SESSION_HANDLE hSession,
        CK_OBJECT_HANDLE hObject,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulCount
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_SENSITIVE, CKR_ATTRIBUTE_TYPE_INVALID, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OBJECT_HANDLE_INVALID, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    // Only retrieve supported EP11 attributes
    attributeList := ep11.EP11Attributes{
        ep11.CKA_DECRYPT: false, // attribute where you would like to retrieve its current value
    }
    
    GetAttributeValueRequest := &pb.GetAttributeValueRequest{
        Object:     GenerateKeyPairResponse.PrivKeyBytes,
        Attributes: util.AttributeMap(attributeList),
    }
    
    GetAttributeValueResponse, err := cryptoClient.GetAttributeValue(context.Background(), GetAttributeValueRequest)
    
  • Fragment de code JavaScript

    const attributeTemplate = new util.AttributeMap(
    new util.Attribute(ep11.CKA_SIGN, 0)
    );
    
    client.GetAttributeValue({
      Object: keys.PrivKey,
      Attributes: attributeTemplate
    }, (err, response) => {
      callback(err, response);
      console.log('ATTRIBUTE:', response.Attributes);
    });
    

SetAttributeValue

La fonction SetAttributeValue modifie une valeur d'attribut d'un objet.

Description Effectue une liaison à la fonction EP11 m_SetAttributeValue, qui est une implémentation de la fonction PKCS #11 C_SetAttributeValue.
Paramètres
    message SetAttributeValueRequest {
        bytes Object = 1;
        Attributs map<uint64,AttributeValue> = 3 ;
    }
    message SetAttributeValueResponse {
        bytes Object = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_SetAttributeValue.

Compression d'attributs : voir _GetAttrValue

Actuellement, Ep11 n'envoie que des attributs booléens, tous les autres attributs sont gérés par l'hôte (et EP11 ne modifie pas les matrices, comme WRAP_TEMPLATE).

N'utilise pas le paramètre PKCS #11 hSession, car ne représente pas ou n'a pas besoin de sessions (partie d'objet blob).

Paramètres
    CK_RV m_SetAttributeValue (
        unsigned char *object, size_t objectlen,
        CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeslen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_SetAttributeValue. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_SetAttributeValue modifie la valeur d'un ou plusieurs attributs d'un objet. HSession est le descripteur de la session ; HObjet est le descripteur de l'objet ; pTemplate pointe vers un modèle qui spécifie les valeurs d'attribut à modifier et leurs nouvelles valeurs ; UlCount est le nombre d'attributs dans le modèle.

Certains objets peuvent ne pas être modifiés. L'appel de C_SetAttributeValue sur de tels objets entraîne le code d'erreur CKR_ACTION_PROHIBITED. Une application peut consulter l'attribut CKA_MODIFIABLE de l'objet pour déterminer si un objet peut être modifié ou non.

Seuls les objets de session peuvent être modifiés durant une session en lecture seule.

Le modèle peut spécifier de nouvelles valeurs pour tous les attributs de l'objet qui peuvent être modifiés. Si le modèle spécifie une valeur d'attribut incompatible avec d'autres attributs existants de l'objet, l'appel échoue avec le code retour CKR_TEMPLATE_INCOHÉRENCE.

Tous les attributs ne peuvent pas être modifiés ; voir la section 4.1.2 de Spécification de l'interface de programmation PKCS #11 pour plus d'informations.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_SetAttributeValue)(
        CK_SESSION_HANDLE hSession,
        CK_OBJECT_HANDLE hObject,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulCount
    );
    
Valeur de retour CKR_ACTION_PROHIBITED, CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OBJECT_HANDLE_INVALID, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Only set supported R/W EP11 attributes
    attributeList := ep11.EP11AttributeP{
        CKA_DECRYPT: true,
    }
    
    SetAttributeValueRequest := &pb.SetAttributeValueRequest{
        Object:     GenerateKeyPair.PrivKeyBytes,
        Attributes: util.AttributeMap(attributeList),
    }
    SetAttributeValueResponse, err := cryptoClient.SetAttributeValue(context.Background(), SetAttributeValueRequest)
    
  • Fragment de code JavaScript

    const attributeTemplate = new util.AttributeMap(
    new util.Attribute(ep11.CKA_SIGN, true)
    );
    
    client.SetAttributeValue({
      Object: keys.PrivKey,
      Attributes: attributeTemplate
    }, (err, response) => {
      callback(err, response);
    });
    

Génération de données aléatoires

Vous pouvez générer des données aléatoires de haute qualité, par exemple, des valeurs d'initialisation (IV), un code confidentiel et un mot de passe, à utiliser dans des opérations de chiffrement.

GenerateRandom

La fonction GenerateRandom génère des données aléatoires. Lorsque vous utilisez cette fonction, prenez soin de ne pas définir une longueur de données aléatoires égale à zéro et assurez-vous que le pointeur vers l'emplacement des données aléatoires n'est pas NULL.

Description Effectue une liaison à la fonction EP11 m_GenerateRandom, qui est une implémentation de la fonction PKCS #11 C_GenerateRandom.
Paramètres
    message GenerateRandomRequest {
        uint64 Len = 1;
    }
    message GenerateRandomResponse {
        bytes Rnd = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_GenerateRandom.

GenerateRandom est l'équivalent de la fonction PKCS #11 d'origine. En interne, l'entropie alimentée par matériel est passée via un élément DRNG compatible (ANSI X9.31/ISO 18031, en fonction de la version Clic).

La bibliothèque hôte peut générer des nombres aléatoires sans répartition vers le système de backend, si une fonctionnalité appropriée est disponible sur l'hôte. Cette fonctionnalité n'est pas appliquée dans l'implémentation actuelle.

Cette fonction ne prend pas en charge les requêtes de taille.

Paramètres
    CK_RV m_GenerateRandom (
        CK_BYTE_PTR rnd, CK_ULONG rndlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_GenerateRandom. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description C_GenerateRandom génère des données aléatoires ou pseudo-aléatoires. HSession est le descripteur de session ; pRandomData pointe vers l'emplacement qui reçoit les données aléatoires ; UlRandomLen est la longueur en octets des données aléatoires ou pseudo-aléatoires à générer.
Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_GenerateRandom)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pRandomData,
        CK_ULONG ulRandomLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALISEE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_ANNULE, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_RANDOM_NO_RNG, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    GenerateRandomRequest := &pb.GenerateRandomRequest {
      Len: 1024,
    }
    
    GenerateRandomResponse, err := cryptoClient.GenerateRandom(context.Background(), GenerateRandomRequest)
    
  • Fragment de code JavaScript

    client.GenerateRandom({
      Len: ep11.AES_BLOCK_SIZE
    }, (err, response) => {
      callback(err, response);
    });
    

Chiffrement et déchiffrement de données

En spécifiant le mécanisme de chiffrement, vous pouvez effectuer des fonctions de chiffrement et de déchiffrement symétriques ou asymétriques. Vous devrez peut-être appeler une série de sous-fonctions pour chiffrer ou déchiffrer les données. Par exemple, l'opération de chiffrement de données à plusieurs parties est composée des sous-opérations EncryptInit, EncryptUpdate et EncryptFinal.

EncryptInit

La fonction EncryptInit initialise une opération de chiffrement. Vous devez d'abord appeler cette fonction pour effectuer un chiffrement.

Description Effectue une liaison à la fonction EP11 m_EncryptInit, qui est une implémentation de la fonction PKCS #11 C_EncryptInit.
Paramètres
    message EncryptInitRequest {
        Mechanism Mech = 2;
        bytes Key = 3;
    }
    message EncryptInitResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_EncryptInit.

L'objet BLOB (key, klen) peut être un objet de clé publique ou un objet BLOB de clé secrète. Le type de clé doit être cohérent avec pmech.

Pour les mécanismes de clé publique, (key, klen) doit contenir des informations SPKI. L'intégrité de ces informations SPKI est protégée par une clé MAC, tel que renvoyé par GenerateKeyPair ou bien UnwrapKey. L'état Encrypt est créé sans restrictions de session.

Pour les mécanismes de clés secrètes, l'état Encrypt hérite de restrictions d'objet de session depuis (key, klen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

(key, klen) doit être un objet blob de clé.

Paramètres
    CK_RV m_EncryptInit (
        unsigned char * state, size_t * statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *key, size_t keylen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_EncryptInit. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_EncryptInit initialise une opération de chiffrement. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme de chiffrement ; HKey est le descripteur de la clé de chiffrement.

L'attribut CKA_ENCRYPT de la clé de chiffrement, qui indique si la clé prend en charge le chiffrement, doit être CK_TRUE.

Après avoir appelé la fonction C_EncryptInit, l'application peut appeler la fonction C_Encrypt pour chiffrer les données en une seule partie ou appeler C_EncryptUpdate zéro ou plusieurs fois, suivi de la fonction C_EncryptFinal pour chiffrer les données en plusieurs parties. L'opération de chiffrement est active jusqu'à ce que l'application utilise un appel à C_Encrypt ou C_EncryptFinal pour obtenir l'élément final du texte chiffré. Pour traiter des données supplémentaires (en une ou plusieurs parties), l'application doit à nouveau appeler C_EncryptInit.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_EncryptInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    
Valeur de retour CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Generate 16 bytes of random data for the initialization vector
    GenerateRandomRequest := &pb.GenerateRandomRequest{
        Len: (uint64)(ep11.AES_BLOCK_SIZE),
    }
    GenerateRandomResponse, err := cryptoClient.GenerateRandom(context.Background(), GenerateRandomRequest)
    if err != nil {
        return nil, fmt.Errorf("GenerateRandom error: %s", err)
    }
    iv := GenerateRandomResponse.Rnd[:ep11.AES_BLOCK_SIZE]
    fmt.Println("Generated IV")
    
    EncryptInitRequest := &pb.EncryptInitRequest{
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Key:  GenerateKeyResponse.KeyBytes,
    }
    
    EncryptInitResponse, err := cryptoClient.EncryptInit(context.Background(), EncryptInitRequest)
    
  • Fragment de code JavaScript

    client.EncryptInit({
    	Mech: {
        Mechanism: ep11.CKM_AES_CBC_PAD,
        ParameterB: iv
      },
      Key: key
    }, (err, data={}) => {
      cb(err, data.State);
    });
    

Chiffrer

La fonction Encrypt chiffre des données ne comportant qu'une seule partie. Vous n'avez pas besoin d'exécuter les sous-opérations EncryptUpdate et EncryptFinal pour un chiffrement à partie unique. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter EncryptInit.

Description Effectue une liaison à la fonction EP11 m_Encrypt, qui est une implémentation de la fonction PKCS #11 C_Encrypt.
Paramètres
    message EncryptRequest {
        bytes State = 1;
        bytes Plain = 2;
    }
    message EncryptResponse {
        bytes Ciphered = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_Encrypt.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis EncryptInit.

Paramètres
    CK_RV m_Encrypt (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Encrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Encrypt chiffre les données à une seule partie. HSession est le descripteur de la session ; pData pointe vers les données ; UlDataLen est la longueur en octets des données ; pEncryptedData pointe vers l'emplacement qui reçoit les données chiffrées ; PulEncryptedDataLen pointe vers l'emplacement qui contient la longueur en octets des données chiffrées.

C_Encrypt utilise la convention décrite à la section 5.2 de Spécification de l'API PKCS #11 sur la production de la sortie.

L'opération de chiffrement doit être initialisée avec C_EncryptInit. Un appel à C_Encrypt arrête toujours l'opération de chiffrement active à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire à la mise en attente du texte chiffré.

C_Encrypt, qui ne peut pas être utilisé pour mettre fin à une opération à plusieurs parties, doit être appelé après C_EncryptInit sans intervention d'appels C_EncryptUpdate.

Pour certains mécanismes de chiffrement, les données d'entrée en texte brut ont certaines contraintes de longueur (soit parce que le mécanisme ne peut chiffrer que des parties relativement courtes de texte brut, soit parce que les données d'entrée du mécanisme doivent être constituées d'un nombre entier de blocs). Si ces contraintes ne sont pas respectées, C_Encrypt échoue avec le code de retour CKR_DATA_LEN_RANGE.

Le texte en clair et le texte chiffré peuvent être au même endroit, c'est-à-dire qu'il est correct si pData et pEncryptedData pointent vers le même emplacement.

Pour la plupart des mécanismes, C_Encrypt est l'équivalent d'une séquence d'opérations C_EncryptUpdate suivies de C_EncryptFinal.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_Encrypt)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pEncryptedData,
        CK_ULONG_PTR pulEncryptedDataLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    plainText := "Encrypt this message"
    
    EncryptRequest := &pb.EncryptRequest {
        State: EncryptInitResponse.State,
        Plain: plainText,
    }
    
    EncryptResponse, err := cryptoClient.Encrypt(context.Background(), EncryptRequest)
    
  • Fragment de code JavaScript

    client.Encrypt({
      State: state,
      Plain: Buffer.from(message)
    }, (err, response) => {
      callback(err, response);
    });
    

EncryptUpdate

La fonction EncryptUpdate poursuit une opération de chiffrement à plusieurs parties. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter EncryptInit.

Description Effectue une liaison à la fonction EP11 m_EncryptUpdate, qui est une implémentation de la fonction PKCS #11 C_EncryptUpdate.
Paramètres
    message EncryptUpdateRequest {
        bytes State = 1;
        bytes Plain = 2;
    }
    message EncryptUpdateResponse {
        bytes State = 1;
        bytes Ciphered = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_EncryptUpdate.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis EncryptInit.

Paramètres
    CK_RV m_EncryptUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_EncryptUpdate. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_EncryptUpdate poursuit une opération de chiffrement à plusieurs parties, en traitant une autre partie de données. HSession est le descripteur de la session ; PPart pointe vers la partie de données ; UlPartLen est la longueur de la partie de données ; PEncryptedPart pointe vers l'emplacement qui reçoit la partie de données chiffrées ; PulEncryptedPartLen pointe vers l'emplacement qui contient la longueur en octets de la partie de données chiffrée.

C_EncryptUpdate utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de chiffrement doit être initialisée avec C_EncryptInit. Cette fonction peut être appelée plusieurs fois de suite. Un appel à C_EncryptUpdate qui génère une erreur autre que CKR_BUFFER_TOO_SMALL met fin à l'opération de chiffrement actuelle.

plaintext et ciphertext peuvent se trouver au même endroit, ce qui signifie qu'il est possible que pPart et pEncryptedPart pointent vers le même emplacement.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_EncryptUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen,
        CK_BYTE_PTR pEncryptedPart,
        CK_ULONG_PTR pulEncryptedPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    plainText := `
    This is a very long message that needs to be encrypted by performing
    multiple EncrypytUpdate functions`
    
    // Use EncryptUpdate if you would like to breakup
    // the encrypt operation into multiple suboperations
    EncryptUpdateRequest1 := &pb.EncryptUpdateRequest {
        State: EncryptInitResponse.State,
        Plain: plainText[:20],
    }
    
    EncryptUpdateResponse, err := cryptoClient.EncryptUpdate(context.Background(), EncryptUpdateRequest1)
    
    ciphertext := EncryptUpdateResponse.Ciphered[:]
    
    EncryptUpdateRequest2 := &pb.EncryptUpdateRequest {
        State: EncryptUpdateResponse.State,
        Plain: plainText[20:],
    }
    
    EncryptUpdateResponse, err := cryptoClient.EncryptUpdate(context.Background(), EncryptUpdateRequest2)
    
    ciphertext = append(ciphertext, EncryptUpdateResponse.Ciphered...)
    
  • Fragment de code JavaScript

    client.EncryptUpdate({
      State: state,
      Plain: Buffer.from(message.substr(20))
    }, (err, data={}) => {
      cb(err, data.State, Buffer.concat([ciphertext, data.Ciphered]));
    });
    

EncryptFinal

La fonction EncryptFinal termine une opération de chiffrement à plusieurs parties.

Description Effectue une liaison à la fonction EP11 m_EncryptFinal, qui est une implémentation de la fonction PKCS #11 C_EncryptFinal.
Paramètres
    message EncryptFinalRequest {
        bytes State = 1;
    }
    message EncryptFinalResponse {
        bytes Ciphered = 2;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_EncryptFinal.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis EncryptInit, EncryptUpdate.

Paramètres
    CK_RV m_EncryptFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_EncryptFinal. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_EncryptFinal termine une opération de chiffrement à plusieurs parties. HSession est le descripteur de la session ; PLastEncryptedPart pointe vers l'emplacement qui reçoit la dernière partie de données chiffrées, le cas échéant ; PulLastEncryptedPartLen pointe vers l'emplacement qui contient la longueur de la dernière partie de données chiffrées.

C_EncryptFinal utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de chiffrement doit être initialisée avec C_EncryptInit. Un appel à C_Encrypt met toujours fin à l'opération de chiffrement active, à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour mettre en attente le texte chiffré.

Pour certains mécanismes de chiffrement à plusieurs parties, les données en texte brut d'entrée ont certaines contraintes de longueur car les données d'entrée du mécanisme doivent être constituées d'un nombre entier de blocs. Si ces contraintes ne sont pas satisfaites, C_EncryptFinal échoue avec le code retour CKR_DATA_LEN_RANGE.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_EncryptFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pLastEncryptedPart,
        CK_ULONG_PTR pulLastEncryptedPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    EncryptFinalRequest := &pb.EncryptFinalRequest {
        State: EncryptUpdateResponse.State,
    }
    
    EncryptFinalResponse, err := cryptoClient.EncryptFinal(context.Background(), EncryptFinalRequest)
    
  • Fragment de code JavaScript

    client.EncryptFinal({
      State: state
    }, (err, data={}) => {
      cb(err, Buffer.concat([ciphertext, data.Ciphered]));
    });
    

EncryptSingle

La fonction EncryptSingle traite les données en un seul passage, avec un seul appel. La fonction ne renvoie aucun état à l'hôte et ne renvoie que les données chiffrées. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11 et est une combinaison des fonctions EncryptInit et Encrypt. Elle vous permet d'effectuer une opération de chiffrement avec un appel unique au lieu d'une série d'appels.

Description Effectue une liaison à la fonction EP11 m_EncryptSingle
Paramètres
    message EncryptSingleRequest {
        bytes Key = 1;
        Mechanism Mech = 2;
        bytes Plain = 3;
    }
    message EncryptSingleResponse {
        bytes Ciphered = 4;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Variante non standard d'Encrypt. Traite les données en un seul passage, avec un seul appel. Ne renvoie aucun état à l'hôte autre que des données chiffrées.

Il s'agit de la méthode préférée de chiffrement en un seul passage pour les applications XCP-aware. La fonctionnalité est équivalente à celle fournie par EncryptInit suivie immédiatement par Encrypt, mais elle évite des allers-retours, un encapsulage et un désencapsulage.

Si le système de backend prend en charge les clés résidentes, la clé peut également être un descripteur de clé résidente.

Voir aussi : Encrypt, EncryptInit, DecryptSingle.

L'objet blob key est généré en sortie depuis GenerateKey, UnwrapKey.

Paramètres
    CK_RV m_EncryptSingle (
        const unsigned char *key, size_t keylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Encrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    // Generate 16 bytes of random data for the initialization vector
    GenerateRandomRequest := &pb.GenerateRandomRequest{
        Len: (uint64)(ep11.AES_BLOCK_SIZE),
    }
    GenerateRandomResponse, err := cryptoClient.GenerateRandom(context.Background(),  GenerateRandomRequest)
    if err != nil {
        return nil, fmt.Errorf("GenerateRandom error: %s", err)
    }
    
    iv := GenerateRandomResponse.Rnd[:ep11.AES_BLOCK_SIZE]
    fmt.Println("Generated IV")
    
    plainText := "Encrypt this message"
    EncryptSingleRequest := &pb.EncryptSingleRequest{
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Key:  GenerateKeyResponse.KeyBytes,
        Plain: plainText,
    }
    
    EncryptSingleResponse, err := cryptoClient.EncryptSingle(context.Background(), EncryptSingleRequest)
    
  • Fragment de code JavaScript

    client.EncryptSingle({
      Mech: {
        Mechanism: ep11.CKM_AES_CBC_PAD,
        ParameterB: iv
      },
      Key: aliceDerived.NewKey,
      Plain: Buffer.from(message)
    }, (err, response) => {
      callback(err, response);
    });
    

ReencryptSingle

Avec la fonction ReencryptSingle , vous pouvez déchiffrer les données avec la clé d'origine, puis chiffrer les données brutes avec une clé différente dans un seul appel dans le cloud HSM. Les types de clé utilisés pour cette opération peuvent être identiques ou différents. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11. Cet appel unique constitue une option viable lorsqu'une grande quantité de données doit être rechiffrée avec différentes clés et évite d'avoir besoin de combiner les fonctions DecryptSingle et EncryptSingle pour chaque élément de données à rechiffrer. Elle ne renvoie aucun état à l'hôte et ne renvoie que les données rechiffrées.

Description Lie à EP11 M_ReencryptSingle.
Paramètres
    message ReencryptSingleRequest {
        bytes DecKey = 1;
        bytes EncKey = 2;
        Mechanism DecMech = 3;
        Mechanism EncMech = 4;
        bytes Ciphered = 5;
    }
    message ReencryptSingleResponse {
        bytes Reciphered = 6;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Variante non standard d'Encrypt. Traite les données en un seul passage, avec un seul appel. Ne renvoie aucun état à l'hôte, mais uniquement les données rechiffrées.

Déchiffre les données avec la clé d'origine, puis chiffre les données brutes avec une clé différente dans le Cloud HSM.

Paramètres
    CK_RV m_ReencryptSingle (
        const unsigned char * dkey, size_t dkeylen,
        const unsigned char * ekey, size_t ekeylen,
        CK_MECHANISM_PTR decmech,
        CK_MECHANISM_PTR encmech,
        CK_BYTE_PTR in, CK_ULONG inlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Encrypt et C_Decrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    var msg = []byte("Data to encrypt")
    EncryptKey1Request := &pb.EncryptSingleRequest{
        Key:   GenerateKey1Response.KeyBytes,
        Mech:  &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Plain: msg,
    }
    EncryptKey1Response, err := cryptoClient.EncryptSingle(context.Background(), EncryptKey1Request)
    if err != nil {
        return nil, fmt.Errorf("Encrypt error: %s", err)
    }
    
    ReencryptSingleRequest := &pb.ReencryptSingleRequest{
        DecKey:   GenerateKey1Response.KeyBytes, // original key
        EncKey:   GenerateKey2Response.KeyBytes, // new key
        DecMech:  &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        EncMech:  &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Ciphered: RencryptKey1Response.Ciphered,
    }
    
    ReencryptSingleResponse, err := cryptoClient.ReencryptSingle(context.Background(), ReencryptSingleRequest)
    
  • Fragment de code JavaScript

    client.ReencryptSingle({
    Decmech: {
      Mechanism: mech1,
      ParameterB: iv
    },
    Encmech: {
      Mechanism: mech2,
      ParameterB: iv
    },
    In: encipherState.Ciphered,
    DKey: keyBlob1,
    Ekey: keyBlob2,
    }, (err, response) => {
    callback(err, response);
    });
    

DecryptInit

La fonction DecryptInit initialise une opération de déchiffrement. Vous devez d'abord appeler cette fonction pour effectuer un déchiffrement.

Description Effectue une liaison à la fonction EP11 m_DecryptInit, qui est une implémentation de la fonction PKCS #11 C_DecryptInit.
Paramètres
    message DecryptInitRequest {
        Mechanism Mech = 2;
        bytes Key = 3;
    }
    message DecryptInitResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description Implémentation de la fonction PKCS #11 C_DecryptInit.
Paramètres
    CK_RV m_DecryptInit (
        unsigned char * state, size_t * statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *key, size_t keylen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DecryptInit. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DecryptInit initialise une opération de déchiffrement. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme de déchiffrement ; HKey est le descripteur de la clé de déchiffrement.

L'attribut CKA_DECRYPT de la clé de déchiffrement, qui indique si la clé prend en charge le déchiffrement, doit être CK_TRUE.

Une fois que l'application a appelé C_DecryptInit, l'application peut soit appeler C_Decrypt pour déchiffrer les données dans une seule partie ; ou appeler C_DecryptUpdate zéro ou plusieurs fois, puis C_DecryptFinal, pour déchiffrer les données en plusieurs parties. L'opération de déchiffrement est active jusqu'à ce que l'application utilise un appel à C_Decrypt ou C_DecryptFinal pour obtenir l'élément final du texte en clair. Pour traiter des données supplémentaires (en une ou plusieurs parties), l'application doit à nouveau appeler C_EncryptInit.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DecryptInit)(
        K_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Generate 16 bytes of random data for the initialization vector
    GenerateRandomRequest := &pb.GenerateRandomRequest{
        Len: (uint64)(ep11.AES_BLOCK_SIZE),
    }
    GenerateRandomResponse, err := cryptoClient.GenerateRandom(context.Background(), GenerateRandomRequest)
    if err != nil {
        return nil, fmt.Errorf("GenerateRandom error: %s", err)
    }
    iv := GenerateRandomResponse.Rnd[:ep11.AES_BLOCK_SIZE]
    fmt.Println("Generated IV")
    
    DecryptInitRequest := &pb.DecryptInitRequest{
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Key:  GenerateKeyResponse.KeyBytes,
    }
    
    DecryptInitResponse, err := cryptoClient.DecryptInit(context.Background(), DecryptInitRequest)
    
  • Fragment de code JavaScript

    client.DecryptInit({
      Mech: {
        Mechanism: ep11.CKM_AES_CBC_PAD,
        ParameterB: iv
      },
      Key: key
    }, (err, data={}) => {
      cb(err, data.State);
    });
    

Decrypt

La fonction Decrypt déchiffre les données en une seule partie. Vous n'avez pas besoin d'exécuter les sous-opérations DecryptUpdate et DecryptFinal pour un chiffrement à partie unique. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter DecryptInit.

Description Effectue une liaison à la fonction EP11 m_Decrypt, qui est une implémentation de la fonction PKCS #11 C_Decrypt.
Paramètres
    message DecryptRequest {
        bytes State = 1;
        bytes Ciphered = 2;
    }
    message DecryptResponse {
       bytes Plain = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de PKCS #11 C_Decrypt. Il ne met pas à jour (état, slen).

L'objet BLOB (Binary Large Object) state, slen () doit être mappé à partir du paramètre PKCS #11 hSession. L'objet BLOB state est généré en sortie depuis DecryptInit.

Paramètres
    CK_RV m_Decrypt (const unsigned char *state, size_t slen,
        CK_BYTE_PTR cipher, CK_ULONG clen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Decrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Decrypt déchiffre les données chiffrées en une seule partie.

  • hSession est le descripteur de session.
  • pEncryptedData pointe vers les données chiffrées.
  • ulEncryptedDataLen est la longueur des données chiffrées.
  • pData pointe vers l'emplacement qui reçoit les données récupérées.
  • pulDataLen pointe vers l'emplacement qui contient la longueur des données récupérées.

C_Decrypt utilise la convention décrite à la section 5.2 de laSpécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de déchiffrement doit être initialisée avec C_DecryptInit. Un appel à C_Decrypt met toujours fin à l'opération de déchiffrement active sauf s'il renvoie CKR_BUFFER_TOO_SMALL ou s'il s'agit d'un appel réussi avec CKR_OK renvoyé pour déterminer la longueur de la mémoire tampon nécessaire pour contenir le texte en clair.

C_Decrypt ne peut pas être utilisé pour terminer une opération à plusieurs parties et doit être appelé après C_DecryptInit sans passer d'appels C_DecryptUpdate.

Le texte chiffré et le texte en clair peuvent être au même endroit, ce qui signifie qu'il est acceptable si les données pEncryptedet pData pointent vers le même emplacement.

Si les données de texte chiffré en entrée ne peuvent pas être déchiffrées car elles ont une longueur inadaptée, CKR_ENCRYPTED_DATA_INVALID ou CKR_ENCRYPTED_DATA_LEN_RANGE peut être retourné.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_Decrypt)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pEncryptedData,
        CK_ULONG ulEncryptedDataLen,
        CK_BYTE_PTR pData,
        CK_ULONG_PTR pulDataLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    DecryptRequest := &pb.DecryptRequest{
        State:    DecryptInitResponse.State,
        Ciphered: ciphertext, // encrypted data from a previous encrypt operation
    }
    
    DecryptResponse, err := cryptoClient.Decrypt(context.Background(), DecryptRequest)
    
  • Fragment de code JavaScript

    client.Decrypt({
      State: state,
      Ciphered: ciphertext
    }, (err, response) => {
      callback(err, response);
    });
    

DecryptUpdate

La fonction DecryptUpdate poursuit une opération de déchiffrement à plusieurs parties. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter DecryptInit.

Description Effectue une liaison à la fonction EP11 m_DecryptUpdate, qui est une implémentation de la fonction PKCS #11 C_DecryptUpdate.
Paramètres
    message DecryptUpdateRequest {
        bytes State = 1;
        bytes Ciphered = 2;
    }
    message DecryptUpdateResponse {
        bytes State = 1;
        bytes Plain = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DecryptUpdate.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis DecryptInit.

Paramètres
    CK_RV m_DecryptUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR ciphered, CK_ULONG cipheredlen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DecryptUpdate. Pour plus d'informations, voir le chapitre Valeurs de retourde Entreprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DecryptUpdate poursuit une opération de déchiffrement en plusieurs parties, en traitant une autre partie de données chiffrées. HSession est le descripteur de la session ; PEncryptedPart pointe vers la partie de données chiffrée ; UlEncryptedPartLen est la longueur de la partie de données chiffrées ; PPart pointe vers l'emplacement qui reçoit la partie de données récupérée ; PulPartLen pointe vers l'emplacement qui contient la longueur de la partie de données récupérée.

C_DecryptUpdate utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de déchiffrement doit être initialisée avec C_DecryptInit. Cette fonction peut être appelée plusieurs fois de suite. Un appel à C_DecryptUpdate qui génère une erreur autre que CKR_BUFFER_TOO_SMALL met fin à l'opération de déchiffrement actuelle.

Le texte chiffré et le texte en clair peuvent être au même endroit, c'est-à-dire qu'il est correct si pEncryptedPart et pPart pointent vers le même emplacement.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DecryptUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pEncryptedPart,
        CK_ULONG ulEncryptedPartLen,
        CK_BYTE_PTR pPart,
        CK_ULONG_PTR pulPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Use DecryptUpdate if you would like to breakup
    // the decrypt operation into multiple suboperations
    DecryptUpdateRequest1 := &pb.DecryptUpdateRequest{
        State:    DecryptInitResponse.State,
        Ciphered: ciphertext[:16], // encrypted data from a previous encrypt operation
    }
    
    DecryptUpdateResponse, err := cryptoClient.DecryptUpdate(context.Background(), DecryptUpdateRequest1)
    
    plaintext := DecryptUpdateResponse.Plain[:]
    
    DecryptUpdateRequest2 := &pb.DecryptUpdateRequest{
        State:    DecryptUpdateResponse.State,
        Ciphered: ciphertext[16:], // encrypted data from a previous encrypt operation
    }
    
    DecryptUpdateResponse, err := cryptoClient.DecryptUpdate(context.Background(), DecryptUpdateRequest2)
    
    plaintext = append(plaintext, DecryptUpdateResponse.Plain...)
    
  • Fragment de code JavaScript

    client.DecryptUpdate({
    State: state,
    Ciphered: ciphertext.slice(0, 16)
    }, (err, data={}) => {
    cb(err, data.State, data.Plain);
    });
    

DecryptFinal

La fonction DecryptFinal termine une opération de déchiffrement à plusieurs parties.

Description Effectue une liaison à la fonction EP11 m_DecryptFinal, qui est une implémentation de la fonction PKCS #11 C_DecryptFinal.
Paramètres
    message DecryptFinalRequest {
        bytes State = 1;
    }
    message DecryptFinalResponse {
        bytes Plain = 2;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DecryptFinal.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis DecryptInit, DecryptUpdate.

Paramètres
    CK_RV m_DecryptFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DecryptFinal. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DecryptFinal termine une opération de déchiffrement en plusieurs parties. HSession est le descripteur de la session ; pLastPart pointe vers l'emplacement qui reçoit le dernier élément de données récupéré, le cas échéant ; PulLastPartLen pointe vers l'emplacement qui contient la longueur du dernier composant de données récupéré.

C_DecryptFinal utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de déchiffrement doit être initialisée avec C_DecryptInit. Un appel à C_DecryptFinal met toujours fin à l'opération de déchiffrement active sauf s'il renvoie CKR_BUFFER_TOO_SMALL ou s'il s'agit d'un appel réussi (c'est-à-dire, un appel qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour contenir le texte en clair.

Si les données de texte chiffré en entrée ne peuvent pas être déchiffrées car elles ont une longueur inadaptée, CKR_ENCRYPTED_DATA_INVALID ou CKR_ENCRYPTED_DATA_LEN_RANGE peut être retourné.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DecryptFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pLastPart,
        CK_ULONG_PTR pulLastPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    DecryptFinalRequest := &pb.DecryptFinalRequest {
      State: DecrypUpdateResponse.State,
    }
    
    DecryptFinalResponse, err := cryptoClient.DecryptFinal(context.Background(), DecryptFinalRequest)
    
  • Fragment de code JavaScript

    client.DecryptFinal({
      State: state
    }, (err, data={}) => {
      cb(err, Buffer.concat([plaintext, data.Plain]));
    });
    

DecryptSingle

La fonction DecryptSingle traite les données en un seul passage, avec un seul appel. La fonction ne renvoie aucun état à l'hôte et ne renvoie que les données déchiffrées. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11 et est une combinaison des fonctions DecryptInit et Decrypt. Elle vous permet d'effectuer une opération de déchiffrement avec un seul appel au lieu d'une série d'appels.

Description Lie à EP11 M_DecryptSingle.
Paramètres
    message DecryptSingleRequest {
        bytes Key = 1;
        Mechanism Mech = 2;
        bytes Ciphered = 3;
    }
    message DecryptSingleResponse {
        bytes Plain = 4;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Variante non standard de Decrypt. Traite les données en un seul passage, avec un seul appel. Ne renvoie aucun état à l'hôte autre que des données déchiffrées.

Il s'agit de la méthode préférée de chiffrement en un seul passage pour les applications XCP-aware. La fonctionnalité est équivalente à celle fournie par DecryptInit suivie immédiatement par Decrypt, mais elle évite des allers-retours, un encapsulage et un désencapsulage.

Si le système de backend prend en charge les clés résidentes, la clé peut également être un descripteur de clé résidente.

Voir aussi : Decrypt, DecryptInit, EncryptSingle.

L'objet blob key est généré en sortie depuis GenerateKey, UnwrapKey.

Paramètres
    CK_RV m_DecryptSingle (
        const unsigned char *key, size_t keylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR ciphered, CK_ULONG cipheredlen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Decrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    // Generate 16 bytes of random data for the initialization vector
    GenerateRandomRequest := &pb.GenerateRandomRequest{
        Len: (uint64)(ep11.AES_BLOCK_SIZE),
    }
    GenerateRandomResponse, err := cryptoClient.GenerateRandom(context.Background(),  GenerateRandomRequest)
    if err != nil {
        return nil, fmt.Errorf("GenerateRandom error: %s", err)
    }
    iv := GenerateRandomResponse.Rnd[:ep11.AES_BLOCK_SIZE]
    fmt.Println("Generated IV")
    
    DecryptSingleRequest := &pb.DecryptSingleRequest {
        Key:      GenerateKeyResponse.KeyBytes,
        Mech:     &pb.Mechanism{Mechanism: ep11.CKM_AES_CBC_PAD, Parameter: util.SetMechParm(iv)},
        Ciphered: EncryptSingleResponse.Ciphered, // encrypted data from a previous encrypt operation
    }
    
    DecryptSingleResponse, err := cryptoClient.DecryptSingle(context.Background(), DecryptSingleRequest)
    
  • Fragment de code JavaScript

    client.DecryptSingle({
      Mech: {
        Mechanism: ep11.CKM_AES_CBC_PAD,
        ParameterB: iv
      },
      Key: bobDerived.NewKey,
      Ciphered: ciphertext
    }, (err, response) => {
      callback(err, response);
    });
    

Signature et vérification des données

GREP11 fournit un ensemble de fonctions permettant de signer des données et de vérifier des signatures ou des codes d'authentification de message (MAC). Vous devrez peut-être appeler une série de sous-fonctions pour effectuer une opération de signature. Par exemple, l'opération de signature de données à plusieurs parties se compose des sous-opérations SignInit, SignUpdateet SignFinal.

SignInit

La fonction SignInit initialise une opération de signature. Vous devez d'abord appeler cette fonction pour effectuer une opération de signature.

Description Lié à EP11 M_SignInit , qui est une implémentation de PKCS #11 C_SignInit.
Paramètres
    message SignInitRequest {
        Mechanism Mech = 2;
        bytes PrivKey = 3;
    }
    message SignInitResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description Implémentation de la fonction PKCS #11 C_SignInit.
Paramètres
    CK_RV m_SignInit (
        unsigned char * state, size_t * statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *privKey, size_t privKeylen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Decrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_SignInit initialise une opération de signature, où la signature est une annexe des données. HSession est le descripteur de la session ; pMechanism pointe vers le mécanisme de signature ; HKey est le descripteur de la clé de signature.

L'attribut CKA_SIGN de la clé de signature, qui indique si la clé prend en charge les signatures avec une annexe, doit être CK_TRUE.

Après avoir appelé la fonction C_SignInit, l'application peut appeler la fonction C_Sign pour signer les données en une seule partie ou appeler la fonction C_SignUpdate zéro ou plusieurs fois, suivi de la fonction C_SignFinal, pour signer les données en plusieurs parties. L'opération de signature est active jusqu'à ce que l'application utilise un appel à C_Sign ou C_SignFinal pour obtenir la signature. Pour traiter des données supplémentaires (en une ou plusieurs parties), l'application doit à nouveau appeler C_SignInit.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_SignInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    SignInitRequest := &pb.SignInitRequest {
        Mech:    &pb.Mechanism{Mechanism: ep11.CKM_SHA1_RSA_PKCS},
        PrivKey: GenerateKeyPairResponse.PrivKeyBytes,
    }
    
    SignInitResponse, err := cryptoClient.SignInit(context.Background(), SignInitRequest)
    
  • Fragment de code JavaScript

    client.SignInit({
      Mech: {
        Mechanism: ep11.CKM_SHA1_RSA_PKCS
      },
      PrivKey: keys.PrivKeyBytes
    }, (err, data={}) => {
      cb(err, data.State);
    });
    

Signer

La fonction Sign signe des données ne comportant qu'une seule partie. Vous n'avez pas besoin d'exécuter les sous-opérations SignUpdate et SignFinal pour une signature à partie unique. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter SignInit.

Description Effectue une liaison à la fonction EP11 m_Sign, qui est une implémentation de la fonction PKCS #11 C_Sign.
Paramètres
    message SignRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message SignResponse {
        bytes Signature = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_Sign.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de SignInit.

Paramètres
    CK_RV m_Sign (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Sign. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Sign signe les données en une seule partie, où la signature est une annexe des données. HSession est le descripteur de la session ; pData pointe vers les données ; UlDataLen est la longueur des données ; pSignature pointe vers l'emplacement qui reçoit la signature ; PulSignatureLen pointe vers l'emplacement qui contient la longueur de la signature.

C_Sign utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de signature doit être initialisée avec C_SignInit. Un appel à C_Sign met toujours fin à l'opération de signature active, à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour mettre en attente la signature.

C_Sign, qui ne peut pas être utilisé pour mettre fin à une opération à plusieurs parties, doit être appelé après C_SignInit sans intervention d'appels C_SignUpdate.

Pour la plupart des mécanismes, C_Sign est l'équivalent d'une séquence d'opérations C_SignUpdate suivies de C_SignFinal.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_Sign)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pSignature,
        CK_ULONG_PTR pulSignatureLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED

Fragments de code

  • Fragment de code Golang

    msgHash := sha256.Sum256([]byte("This data needs to be signed"))
    SignRequest := &pb.SignRequest{
        State: SignInitResponse.State,
        Data:  msgHash[:],
    }
    
    // Sign the data
    SignResponse, err := cryptoClient.Sign(context.Background(), SignRequest)
    
  • Fragment de code JavaScript

    client.Sign({
      State: state,
      Data: dataToSign
    }, (err, data={}) => {
      cb(err, data.Signature);
    });
    

SignUpdate

La fonction SignUpdate poursuit une opération de signature à plusieurs parties. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter SignInit.

Description Effectue une liaison à la fonction EP11 m_SignUpdate, qui est une implémentation de la fonction PKCS #11 C_SignUpdate.
Paramètres
    message SignUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message SignUpdateResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_SignUpdate.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de SignInit.

Paramètres
    CK_RV m_SignUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_SignUpdate. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_SignUpdate poursuit une opération de signature en plusieurs parties, en traitant une autre partie de données. HSession est le descripteur de la session, PPart pointe vers la partie de données ; UlPartLen est la longueur de la partie de données.

L'opération de signature doit être initialisée avec C_SignInit. Cette fonction peut être appelée plusieurs fois de suite. Un appel à C_SignUpdate met fin à l'opération de signature actuelle.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_SignUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    // Use SignUpdate if you would like to breakup
    // the sign operation into multiple suboperations
    SignUpdateRequest1 := &pb.SignUpdateRequest {
        State: SignInitResponse.State,
        Data:  msgHash[:16],
    }
    
    SignUpdateResponse, err := cryptoClient.SignUpdate(context.Background(), SignUpdateRequest1)
    
    SignUpdateRequest2 := &pb.SignUpdateRequest {
        State: SignUpdateResponse.State,
        Data:  msgHash[16:],
    }
    
    SignUpdateResponse, err := cryptoClient.SignUpdate(context.Background(), SignUpdateRequest2)
    
  • Fragment de code JavaScript

    client.SignUpdate({
      State: state,
      Data: digest
    }, (err, response) => {
      callback(err, response);
    });
    

SignFinal

La fonction SignFinal termine une opération de signature à plusieurs parties.

Description Effectue une liaison à la fonction EP11 m_SignFinal, qui est une implémentation de la fonction PKCS #11 C_SignFinal.
Paramètres
    message SignFinalRequest {
        bytes State = 1;
    }
    message SignFinalResponse {
        bytes Signature = 2;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_SignFinal.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de SignInit, SignUpdate.

Paramètres
    CK_RV m_SignFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_SignFinal. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Signfinal termine une opération de signature multiple, renvoyant la signature. HSession est le descripteur de la session ; pSignature pointe vers l'emplacement qui reçoit la signature ; PulSignatureLen pointe vers l'emplacement qui contient la longueur de la signature.

C_Signfinal utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération de signature doit être initialisée avec C_SignInit. Un appel à C_SignFinal met toujours fin à l'opération de signature active, à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour mettre en attente la signature.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_SignFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pSignature,
        CK_ULONG_PTR pulSignatureLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED

Fragments de code

  • Fragment de code Golang

    SignFinalRequest := &pb.SignFinalRequest {
        State: SignUpdateResponse.State,
    }
    
    SignFinalResponse, err := cryptoClient.SignFinal(context.Background(), SignFinalRequest)
    
  • Fragment de code JavaScript

    client.SignFinal({
      State: state
    }, (err, response) => {
      callback(err, response);
    });
    

SignSingle

La fonction SignSingle signe ou effectue des opérations MAC sur des données en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. La fonction ne renvoie aucun état à l'hôte et ne renvoie que le résultat. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11 et est une combinaison des fonctions SignInit et Sign. Elle vous permet d'effectuer une opération de signature avec un seul appel au lieu d'une série d'appels.

Description Lie à EP11 M_SignSingle.
Paramètres
    message SignSingleRequest {
        bytes PrivKey = 1;
        Mechanism Mech = 2;
        bytes Data = 3;
    }
    message SignSingleResponse {
        bytes Signature = 4;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Extension non standard, combinaison de SignInit et Sign. Signe ou effectue des opérations MAC sur des données, en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. Ne renvoie aucun état à l'hôte autre que le résultat.

Il s'agit de la méthode de signature préférée, sans aller-retour, chiffrement et déchiffrement supplémentaires. Fonctionnellement, la fonction SignSingle est équivalente à la fonction SignInit suivie immédiatement par Sign.

L'objet blob (key, klen) et le mécanisme pmech doivent tous deux pouvoir être passés à SignInit.

Les demandes de données multiples pour les signatures HMAC et CMAC sont prises en charge (sous-variantes 2 et 3).

Voir aussi : SignInit, Sign, VerifySingle.

Paramètres
    CK_RV m_SignSingle (
        const unsigned char *privKey, size_t privKeylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Decrypt. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    msgHash := sha256.Sum256([]byte("This data needs to be signed"))
    SignSingleRequest := &pb.SignSingleRequest {
        PrivKey: GenerateKeyPairResponse.PrivKeyBytes,
        Mech:    &pb.Mechanism{Mechanism: ep11.CKM_SHA256_RSA_PKCS},
        Data:    msgHash[:],
    }
    
    SignSingleResponse, err := cryptoClient.SignSingle(context.Background(), SignSingleRequest)
    
  • Fragment de code JavaScript

    client.SignSingle({
      Mech: {
        Mechanism: ep11.CKM_ECDSA
      },
      PrivKey: key,
      Data: digest
    }, (err, response) => {
      callback(err, response);
    });
    

VerifyInit

La fonction VerifyInit initialise une opération de vérification. Vous devez d'abord appeler cette fonction pour vérifier une signature.

Description Effectue une liaison à la fonction EP11 m_VerifyInit, qui est une implémentation de la fonction PKCS #11 C_VerifyInit.
Paramètres
    message VerifyInitRequest {
        Mechanism Mech = 2;
        bytes PubKey = 3;
    }
    message VerifyInitResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_VerifyInit. Avec un objet blob de clé (key, klen), initialise un état de session de vérification dans (state, slen). L'objet BLOB de clé peut être un objet de clé publique ou des octets de clé HMAC. Le type d'objet blob de clé doit être cohérent avec pmech.

Pour les mécanismes de clé publique, (key, klen) doit contenir des informations SPKI. Il peut s'agir d'informations SPKI CKA_UNWRAP associées à un élément MAC (tel que renvoyé précédemment par GenerateKeyPair) ou simplement des informations SPKI proprement dites (si obtenues à partir d'une source externe, telle qu'un certificat).

Si une opération HMAC est initialisée, les restrictions de session de l'objet Verify sont héritées de la clé HMAC. Comme les informations SPKI ne sont pas liés aux sessions, les états Verify de clé publique ne sont pas concernés par les sessions.

L'objet blob key,klen doit être mappé à partir du paramètre PKCS #11 hKey.

Remarque: SignInit et VerifyInit sont en interne pour HMAC et d'autres mécanismes symétric/MAC.

Paramètres
    CK_RV m_VerifyInit (
        unsigned char * state, size_t * statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *pubKey, size_t pubKeylen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_VerifyInit. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_VerifyInit initialise une opération de vérification, où la signature est une annexe des données. HSession est le descripteur de la session ; pMechanism pointe vers la structure qui spécifie le mécanisme de vérification ; HKey est le descripteur de la clé de vérification.

L'attribut CKA_VERIFY de la clé de vérification, qui indique si la clé prend en charge la vérification quand la signature est une annexe des données, doit être CK_TRUE.

Après avoir appelé C_VerifyInit, l'application peut appeler la fonction C_Verify pour vérifier une signature sur les données d'une seule partie ou appeler C_VerifyUpdate une ou plusieurs fois, suivie de C_VerifyFinal, pour vérifier une signature sur les données en plusieurs parties. L'opération de vérification est active jusqu'à ce que l'application appelle C_Verify ou C_VerifyFinal. Pour traiter des données supplémentaires (en une ou plusieurs parties), l'application doit à nouveau appeler C_VerifyInit.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_VerifyInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    VerifyInitRequest := &pb.VerifyInitRequest {
      Mech:   &pb.Mechanism{Mechanism: ep11.CKM_SHA1_RSA_PKCS},
      PubKey: GenerateKeyPairResponse.PubKeyBytes,
    }
    
    VerifyInitResponse, err := cryptoClient.VerifyInit(context.Background(), VerifyInitRequest)
    
  • Fragment de code JavaScript

    client.VerifyInit({
      Mech: {
        Mechanism: ep11.CKM_SHA1_RSA_PKCS
      },
      PubKey: keys.PubKeyBytes
    }, (err, data={}) => {
      cb(err, signature, data.State);
    });
    

Vérifier

La fonction Verify vérifie une signature sur des données ne comportant qu'une seule partie. Vous n'avez pas besoin d'exécuter les sous-opérations VerifyUpdate et VerifyFinal pour un chiffrement à partie unique. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter VerifyInit.

Description Effectue une liaison à la fonction EP11 m_Verify, qui est une implémentation de la fonction PKCS #11 C_Verify.
Paramètres
    message VerifyRequest {
        bytes State = 1;
        bytes Data = 2;
        bytes Signature = 3;
    }
    message VerifyResponse {
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_Verify.

Ne procède à aucune mise à jour (state, slen).

L'ordre relatif des données et de la signature est inversé. à VerifySingle.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de VerifyInit.

Paramètres
    CK_RV m_Verify (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Verify. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Verify vérifie une signature dans une opération à une seule pièce, où la signature est une annexe des données. HSession est le descripteur de la session ; pData pointe vers les données ; UlDataLen est la longueur des données ; pSignature pointe vers la signature ; UlSignatureLen est la longueur de la signature.

L'opération de vérification doit être initialisée avec C_VerifyInit. Un appel à C_Verify met toujours fin à l'opération de vérification active.

Un appel réussi à C_Verify doit renvoyer la valeur CKR_OK (indiquant que la signature fournie est valide) ou CKR_SIGNATURE_INVALID (indiquant que la signature fournie n'est pas valide). Si la signature n'est pas valide uniquement en raison de sa longueur, CKR_SIGNATURE_LEN_RANGE doit être renvoyé. Dans l'un ou l'autre cas, l'opération de signature active est terminée.

C_Verify, qui ne peut pas être utilisé pour mettre fin à une opération à plusieurs parties, doit être appelé après C_VerifyInit sans intervention d'appels C_VerifyUpdate.

Pour la plupart des mécanismes, C_Verify est l'équivalent d'une séquence d'opérations C_VerifyUpdate suivies de C_VerifyFinal.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_Verify)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pSignature,
        CK_ULONG ulSignatureLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, CKR_SIGNATURE_LEN_RANGE.

Fragments de code

  • Fragment de code Golang

    VerifyRequest := &pb.VerifyRequest {
        State:     VerifyInitResponse.State,
        Data:      msgHash[:],
        Signature: SignResponse.Signature,
    }
    
    VerifyResponse, err := cryptoClient.Verify(context.Background(), VerifyRequest)
    
  • Fragment de code JavaScript

    client.Verify({
      State: state,
      Data: dataToSign,
      Signature: signature
    }, (err, data={}) => {
      cb(err, signature);
    });
    

VerifyUpdate

La fonction VerifyUpdate poursuit une opération de vérification à plusieurs parties. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter VerifyInit.

Description Effectue une liaison à la fonction EP11 m_VerifyUpdate, qui est une implémentation de la fonction PKCS #11 C_VerifyUpdate.
Paramètres
    message VerifyUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message VerifyUpdateResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_VerifyUpdate.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de VerifyInit.

Paramètres
    CK_RV m_VerifyUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_VerifyUpdate. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_VerifyUpdate poursuit une opération de vérification en plusieurs parties, en traitant une autre partie de données. HSession est le descripteur de la session, pPart pointe vers la partie de données ; UlPartLen est la longueur de la partie de données.

L'opération de vérification doit être initialisée avec C_VerifyInit. Cette fonction peut être appelée plusieurs fois de suite. Un appel à C_VerifyUpdate qui entraîne une erreur met fin à l'opération de vérification en cours.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_VerifyUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    // Use VerifyUpdate if you would like to breakup
    // the verify operation into multiple suboperations
    VerifyUpdateRequest1 := &pb.VerifyUpdateRequest {
      State: VerifyInitResponse.State,
      Data:  msgHash[:16],
    }
    
    VerifyUpdateResponse, err := cryptoClient.VerifyUpdate(context.Background(), VerifyUpdateRequest1)
    
    VerifyUpdateRequest2 := &pb.VerifyUpdateRequest {
      State: VerifyUpdateResponse.State,
      Data:  msgHash[16:],
    }
    
    VerifyUpdateResponse, err := cryptoClient.VerifyUpdate(context.Background(), VerifyUpdateRequest2)
    
  • Fragment de code JavaScript

    client.VerifyUpdate({
      State: state,
      Data: digest
    }, (err, response) => {
      callback(err, response);
    });
    

VerifyFinal

La fonction VerifyFinal termine une opération de vérification à plusieurs parties.

Description Effectue une liaison à la fonction EP11 m_VerifyFinal, qui est une implémentation de la fonction PKCS #11 C_VerifyFinal.
Paramètres
    message VerifyFinalRequest {
        bytes State = 1;
        bytes Signature = 2;
    }
    message VerifyFinalResponse {
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_VerifyFinal.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie de VerifyInit, VerifyUpdate.

Paramètres
    CK_RV m_VerifyFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_VerifyFinal. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_VerifyFinal termine une opération de vérification en plusieurs parties, en vérifiant la signature. HSession est le descripteur de la session ; pSignature pointe vers la signature ; UlSignatureLen est la longueur de la signature.

L'opération de vérification doit être initialisée avec C_VerifyInit. Un appel à C_VerifyFinal met toujours fin à l'opération de chiffrement active.

Un appel réussi à C_VerifyFinal doit renvoyer la valeur CKR_OK (indiquant que la signature fournie est valide) ou CKR_SIGNATURE_INVALID (indiquant que la signature fournie n'est pas valide). Si la signature n'est pas valide uniquement en raison de sa longueur, CKR_SIGNATURE_LEN_RANGE doit être renvoyé. Dans l'un ou l'autre cas, l'opération de vérification active est terminée.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_VerifyFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pSignature,
        CK_ULONG ulSignatureLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, CKR_SIGNATURE_LEN_RANGE.

Fragments de code

  • Fragment de code Golang

    VerifyFinalRequest := &pb.VerifyFinalRequest {
        State:     VerifyUpdateResponse.State,
        Signature: SignResponse.Signature,
    }
    
    VerifyFinalResponse, err := cryptoClient.VerifyFinal(context.Background(), VerifyFinalRequest)
    
  • Fragment de code JavaScript

    client.VerifyFinal({
      State: state,
      Signature: signature
    }, (err, response) => {
      callback(err, response);
    });
    

VerifySingle

La fonction VerifySingle signe ou effectue des opérations MAC sur des données en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. La fonction ne renvoie aucun état à l'hôte et ne renvoie que le résultat de la vérification. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11 et est une combinaison des fonctions VerifyInit et Verify. Elle vous permet d'effectuer une opération de vérification avec un seul appel au lieu d'une série d'appels.

Description Lie à EP11 M_VerifySingle.
Paramètres
    message VerifySingleRequest {
        bytes PubKey = 1;
        Mechanism Mech = 2;
        bytes Data = 3;
        bytes Signature = 4;
    }
    message VerifySingleResponse {
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Extension non standard, combinaison de VerifyInit et Verify. Signe ou effectue des opérations MAC sur des données, en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire. Ne renvoie aucun état à l'hôte autre que le résultat de la vérification. Aucune requête de taille n'est disponible, car cette fonction renvoie une valeur booléenne.

Il s'agit de la méthode préférée de vérification d'une signature, sans aller-retour, chiffrement, déchiffrement supplémentaires. Fonctionnellement, la fonction VerifySingle est équivalente à la fonction VerifyInit suivie immédiatement par Verify.

L'objet blob (key, klen) et le mécanisme pmech doivent tous deux pouvoir être passés à VerifyInit.

Pour les mécanismes de clé publique, (key, klen) doit contenir des informations SPKI. Il peut s'agir d'informations SPKI associées à un élément MAC (tel que renvoyé en tant que clé publique depuis GenerateKeyPair) ou simplement des informations SPKI elles-mêmes (si obtenues à partir d'une source externe, telle qu'un certificat).

Voir aussi : VerifyInit, Verify, SignSingle.

Paramètres
    CK_RV m_VerifySingle (
        const unsigned char *pubKey, size_t pubKeylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_VerifySingle. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    VerifySingleRequest := &pb.VerifySingleRequest {
        PubKey:    GenerateKeyPairResponse.PubKeyByytes,
        Mech:      &pb.Mechanism{Mechanism: ep11.CKM_SHA256_RSA_PKCS},
        Data:      msgHash[:],
        Signature: SignSingleResponse.Signature,
    }
    
    VerifySingleResponse, err := cryptoClient.VerifySingle(context.Background(), VerifySingleRequest)
    
  • Fragment de code JavaScript

    client.VerifySingle({
      Mech: {
        Mechanism: ep11.CKM_SHA256_RSA_PKCS
      },
      PubKey: keys.PubKey,
      Data: digest,
      Signature: signature
    }, (err, response) => {
      callback(err, response);
    });
    

Protection de l'intégrité des données via des résumés de message

GREP11 fournit un ensemble de fonctions permettant de créer des résumés de message conçus pour protéger l'intégrité d'un élément de données. Vous devrez peut-être appeler une série de sous-fonctions pour effectuer une opération d'assimilation. Par exemple, l'opération d'assimilation à plusieurs parties se compose des sous-opérations DigestInit, DigestUpdateet DigestFinal.

DigestInit

La fonction DigestInit initialise une opération d'assimilation de messages. Vous devez d'abord appeler cette fonction pour effectuer une opération d'assimilation.

Description Effectue une liaison à la fonction EP11 m_DigestInit, qui est une implémentation de la fonction PKCS #11 C_DigestInit.
Paramètres
    message DigestInitRequest {
        Mechanism Mech = 2;
    }
    message DigestInitResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DigestInit.

Crée un état d'assimilation encapsulé.

Remarque : les requêtes de taille sont prises en charge, mais l'état encapsulé est toujours retourné par le système de backend, à la différence de la plupart des requêtes de taille (qui retournent une taille de sortie au lieu de la sortie effective). Les états Digest sont suffisamment petits pour ne pas générer de frais de transport notables.

Lors des requêtes de taille, l'hôte se contente de supprimer l'état retourné et signale la taille de l'objet blob (dans len). Lorsque l'objet BLOB est renvoyé, len est vérifié par rapport à la taille renvoyée.

L'objet blob state,len doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit lier l'objet blob à l'élément session.)

Paramètres
    CK_RV m_DigestInit (
        unsigned char * state, taille_t * len,
        const CK_MECHANISM_PTR mech,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DigestInit. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DigestInit initialise une opération de digestion des messages. HSession est la poignée de la session ; pMechanism pointe vers le mécanisme de digestion.

Après avoir appelé la fonction C_DigestInit, l'application peut appeler la fonction C_Digest pour assimiler les données en une seule partie ou appeler la fonction C_DigestUpdate zéro ou plusieurs fois, suivi de la fonction C_DigestFinal, pour assimiler les données en plusieurs parties. L'opération de digestion des messages est active jusqu'à ce que l'application utilise un appel à C_Digest ou C_DigestFinal pour obtenir l'empreinte du message. Pour traiter des données supplémentaires (en une ou plusieurs parties), l'application doit à nouveau appeler 1C_DigestInit1.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DigestInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Fragments de code

  • Fragment de code Golang

    DigestInitRequest := &pb.DigestInitRequest {
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_SHA256},
    }
    
    DigestInitResponse, err := cryptoClient.DigestInit(context.Background(), DigestInitRequest)
    
  • Fragment de code JavaScript

    client.DigestInit({
      Mech: {
        Mechanism: ep11.CKM_SHA256
      }
    }, (err, response) => {
      callback(err, response);
    });
    

Condensé

La fonction Digest assimile des données ne comportant qu'une seule partie. Vous n'avez pas besoin d'appeler les fonctions DigestUpdate et DigestFinal pour l'assimilation des données ne comportant qu'une partie. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter DigestInit. Lorsque vous définissez des paramètres, prenez soin de ne pas spécifier la valeur zéro pour la longueur des données d'entrée et assurez-vous que le pointeur vers l'emplacement des données d'entrée n'est pas NULL.

Description Effectue une liaison à la fonction EP11 m_Digest, qui est une implémentation de la fonction PKCS #11 C_Digest.
Paramètres
    message DigestRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message DigestResponse {
        bytes Digest = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_Digest.

Si un objet condensé a exactement 0 (zéro) octet qui lui est ajouté après sa création, dans n'importe quelle combinaison de transferts de zéro octet, il peut toujours effectuer un condensé unique, même s'il doit être rejeté par une implémentation stricte.

Ne procède à aucune mise à jour (state, slen).

Les implémentations peuvent s'exécuter DigestUpdate, DigestFinalou Digest appelle des objets digest en texte en clair dans le code hôte, en ignorant complètement les systèmes de back end HSM. Ce choix, qui peut être ou non visible par le code hôte, n'impacte pas la sécurité de l'opération (car les objets en texte en clair ne peuvent assimiler les données sensibles).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. L'objet blob state est généré en sortie depuis DigestInit.

Paramètres
    CK_RV m_Digest (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_Digest. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_Digest digère les données en une seule partie. HSession est le descripteur de la session, pData pointe vers les données ; UlDataLen est la longueur des données ; PDigest pointe vers l'emplacement qui reçoit le condensé de message ; PulDigestLen pointe vers l'emplacement qui contient la longueur de l'empreinte du message.

C_Digest utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération d'assimilation doit être initialisée avec C_DigestInit. Un appel à C_Digest met toujours fin à l'opération d'assimilation active, à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour mettre en attente l'assimilation de message.

C_Digest, qui ne peut pas être utilisé pour mettre fin à une opération à plusieurs parties, doit être appelé après C_DigestInit sans intervention d'appels C_DigestUpdate.

Les données d'entrée et la sortie de résumé peuvent être au même endroit, ce qui signifie qu'il est possible que pData et pDigest pointent vers le même emplacement.

C_Digest est l'équivalent d'une séquence d'opérations C_DigestUpdate suivies de C_DigestFinal.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_Digest)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pDigest,
        CK_ULONG_PTR pulDigestLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    digestData := []byte("Create a digest for this string")
    DigestRequest := &pb.DigestRequest {
        State: DigestInitResponse.State,
        Data:  digestData,
    }
    
    DigestResponse, err := cryptoClient.Digest(context.Background(), DigestRequest)
    
  • Fragment de code JavaScript

    client.Digest({
        State: state,
        Data: Buffer.from(digestData)
      }, (err, data={}) => {
        cb(err, data.Digest);
      });
    }
    

DigestUpdate

La fonction DigestUpdate poursuit une opération d'assimilation à plusieurs parties. Avant d'appeler cette fonction, assurez-vous d'abord d'exécuter DigestInit. Lorsque vous définissez des paramètres, prenez soin de ne pas spécifier la valeur zéro pour la longueur des données d'entrée et assurez-vous que le pointeur vers l'emplacement des données d'entrée n'est pas NULL.

Description Effectue une liaison à la fonction EP11 m_DigestUpdate, qui est une implémentation de la fonction PKCS #11 C_DigestUpdate.
Paramètres
    message DigestUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message DigestUpdateResponse {
        bytes State = 1;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DigestUpdate.

DigestUpdate est polymorphe, acceptation des deux objets de synthèse (digest) encapsulés ou effacés, mise à jour de l'état dans le même format.

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession. (La bibliothèque hôte doit mapper la session à l'état stocké.)

L'objet blob state est généré en sortie depuis DigestInit, DigestUpdate, DigestKey.

Voir aussi : DigestInit

Paramètres
    CK_RV m_DigestUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DigestUpdate. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DigestUpdate poursuit une opération de digestion de messages à plusieurs parties, en traitant une autre partie de données. HSession est le descripteur de la session, PPart pointe vers la partie de données ; UlPartLen est la longueur de la partie de données.

L'opération d'assimilation de message doit être initialisée avec C_DigestInit. Les appels vers cette fonction et C_DigestKey peuvent être entrecoupés un certain nombre de fois et dans un ordre quelconque. Un appel à C_DigestUpdate qui génère une erreur met fin à l'opération d'assimilation actuelle.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DigestUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    // Use DigestUpdate if you would like to breakup
    // the digest operation into multiple suboperations
    DigestUpdateRequest1 := &pb.DigestUpdateRequest {
        State: DigestInitResponse.State,
        Data:  digestData[:16],
    }
    
    DigestUpdateResponse, err := cryptoClient.DigestUpdate(context.Background(), DigestUpdateRequest1)
    
    DigestUpdateRequest2 := &pb.DigestUpdateRequest {
        State: DigestUpdateResponse.State,
        Data:  digestData[16:],
    }
    
    DigestUpdateResponse, err := cryptoClient.DigestUpdate(context.Background(), DigestUpdateRequest2)
    
  • Fragment de code JavaScript

    client.DigestUpdate({
      State: state,
      Data: Buffer.from(digestData.substr(0, 64))
    }, (err, data={}) => {
      cb(err, data.State);
    });
    

DigestFinal

La fonction DigestFinal termine une opération d'assimilation à plusieurs parties.

Description Effectue une liaison à la fonction EP11 m_DigestFinal, qui est une implémentation de la fonction PKCS #11 C_DigestFinal.
Paramètres
    message DigestFinalRequest {
        bytes State = 1;
    }
    message DigestFinalResponse {
        bytes Digest = 2;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Implémentation de la fonction PKCS #11 C_DigestFinal.

La fonction DigestFinal est polymorphe, en ce sens qu'elle accepte les objets digest encapsulés ou en texte en clair.

Ne procède à aucune mise à jour (state, slen).

L'objet blob state,slen doit être mappé à partir du paramètre PKCS #11 hSession.

L'objet blob state est généré en sortie depuis DigestInit, DigestUpdate, DigestKey.

Paramètres
    CK_RV m_DigestFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DigestFinal. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.
Description

C_DigestFinal termine une opération de digestion de messages à plusieurs parties, renvoyant l'empreinte du message. HSession est le descripteur de la session ; PDigest pointe vers l'emplacement qui reçoit le condensé de message ; PulDigestLen pointe vers l'emplacement qui contient la longueur de l'empreinte du message.

C_DigestFinal utilise la convention décrite à la section 5.2 de Spécification de l'interface de programmation PKCS #11 sur la production de la sortie.

L'opération d'assimilation doit être initialisée avec C_DigestInit. Un appel à C_DigestFinal met toujours fin à l'opération d'assimilation active, à moins qu'il ne renvoie CKR_BUFFER_TOO_SMALL ou qu'il s'agisse d'un appel réussi (c'est-à-dire qui renvoie CKR_OK) pour déterminer la longueur de la mémoire tampon nécessaire pour mettre en attente l'assimilation de message.

Paramètres
    CK_DEFINE_FUNCTION(CK_RV, C_DigestFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pDigest,
        CK_ULONG_PTR pulDigestLen
    );
    
Valeur de retour CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.

Fragments de code

  • Fragment de code Golang

    DigestFinalRequest := &pb.DigestFinalRequest {
        State: DigestUpdateResponse.State,
    }
    
    DigestFinalResponse, err := cryptoClient.DigestFinal(context.Background(), DigestFinalRequest)
    
  • Fragment de code JavaScript

    client.DigestFinal({
      State: state
    }, (err, response) => {
      callback(err, response);
    });
    

DigestSingle

La fonction DigestSingle assimile les données en un seul passage, avec un seul appel, sans construire d'état d'assimilation intermédiaire et sans nécessiter des allers-retours. Cette fonction est une extension IBM EP11 vers la spécification de la norme PKCS #11 et est une combinaison des fonctions DigestInit et Digest. Elle vous permet d'effectuer une opération d'assimilation avec un seul appel au lieu d'une série d'appels.

Description Lie à EP11 M_DigestSingle.
Paramètres
    message DigestSingleRequest {
        Mechanism Mech = 1;
        bytes Data = 2;
    }
    message DigestSingleResponse {
        bytes Digest = 3;
    }
    
Valeur de retour Encapsule une erreur EP11 dans le message Grep11Error.
Description

Extension non standard, combinaison de DigestInit et Digest. Assimile les données en un seul passage, avec un seul appel, sans qu'un état d'assimilation intermédiaire soit construit et que des allers-retours soient nécessaires.

Il s'agit de la méthode préférée d'assimilation de texte en clair pour les applications XCP-aware. Fonctionnellement, la fonction DigestSingle est équivalente à la fonction DigestInit suivie immédiatement par Digest.

Si une clé doit être assimilée, il est nécessaire d'utiliser DigestInit et DigestKey, puisque cette fonction ne gère pas les objets blob de clé.

Ne renvoie aucun état à l'hôte autre que le résultat digest. Il n'y a pas de paramètres non PKCS #11, car tout est utilisé directement à partir de l'appel PKCS #11.

Paramètres
    CK_RV m_DigestSingle (
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        cible target_t
    );
    
Valeur de retour Sous-ensemble des valeurs de retour C_DigestSingle. Pour plus d'informations, voir le chapitre Valeurs de retour de Enterprise PKCS #11 (EP11) Document de structure de bibliothèque.

Fragments de code

  • Fragment de code Golang

    digestData := []byte("Create a digest for this string")
    DigestSingleRequest := &pb.DigestSingleRequest {
        Mech: &pb.Mechanism{Mechanism: ep11.CKM_SHA256},
        Data: digestData,
    }
    
    DigestSingleResponse, err := cryptoClient.DigestSingle(context.Background(), DigestSingleRequest)
    
  • Fragment de code JavaScript

    client.DigestSingle({
      Mech: {
        Mechanism: ep11.CKM_SHA256
      },
      Data: Buffer.from(digestData)
    }, (err, response) => {
      callback(err, response);
    });
    

Exemples de code

L'API GREP11 prend en charge les langages de programmation avec des bibliothèquesgRPC. Deux exemples de référentiels GitHub sont fournis pour vous permettre de tester l'API GREP11 :