CryptImportKey, fonction (wincrypt.h)

Article
08/27/2023

Important Cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser les API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.

La fonction CryptImportKey transfère une clé de chiffrement d’un objet BLOB de clé vers un fournisseur de services de chiffrement (CSP). Cette fonction peut être utilisée pour importer une clé de session Schannel, une clé de session normale, une clé publique ou une paire de clés publique/privée. Pour tous les éléments sauf la clé publique, la clé ou la paire de clés est chiffrée.

Syntaxe

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Paramètres

[in] hProv

Handle d’un fournisseur de solutions Cloud obtenu avec la fonction CryptAcquireContext .

[in] pbData

Tableau BYTE qui contient un en-tête BLOB PUBLICKEYSTRUC suivi de la clé chiffrée. Cette clé BLOB est créée par la fonction CryptExportKey , soit dans cette application, soit par une autre application éventuellement exécutée sur un autre ordinateur.

[in] dwDataLen

Contient la longueur, en octets, de l’objet BLOB de clé.

[in] hPubKey

Handle de la clé de chiffrement qui déchiffre la clé stockée dans pbData. Cette clé doit provenir du fournisseur de solutions Cloud auquel hProv fait référence. La signification de ce paramètre diffère selon le type csp et le type d’objet BLOB de clé importé :

Si l’objet BLOB de clé est chiffré avec la paire de clés d’échange de clé, par exemple simpleBLOB, ce paramètre peut être le handle de la clé d’échange de clé.
Si l’objet BLOB de clé est chiffré avec une clé de session, par exemple une clé PRIVATEKEYBLOB chiffrée, ce paramètre contient le handle de cette clé de session.
Si l’objet BLOB de clé n’est pas chiffré, par exemple, un OBJET PUBLICKEYBLOB, ce paramètre n’est pas utilisé et doit être égal à zéro.
Si l’objet BLOB de clé est chiffré avec une clé de session dans un csp Schannel , par exemple, un OPAQUEKEYBLOB chiffré ou tout autre OPAQUEKEYBLOB spécifique au fournisseur, ce paramètre n’est pas utilisé et doit être défini sur zéro.

Note Certains fournisseurs de services cloud peuvent modifier ce paramètre à la suite de l’opération. Les applications qui utilisent par la suite cette clé à d’autres fins doivent appeler la fonction CryptDuplicateKey pour créer un handle de clé en double. Lorsque l’application a terminé d’utiliser le handle, relâchez-le en appelant la fonction CryptDestroyKey .

[in] dwFlags

Actuellement utilisé uniquement lorsqu’une paire de clés publique/privée sous la forme d’un PRIVATEKEYBLOB est importée dans le csp.

Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
CRYPT_EXPORTABLE	La clé importée doit éventuellement être réexportée. Si cet indicateur n’est pas utilisé, les appels à CryptExportKey avec le handle de clé échouent.
CRYPT_OAEP	Cet indicateur entraîne la vérification de la mise en forme PKCS #1 version 2 avec le chiffrement et le déchiffrement RSA lors de l’importation de SIMPLESBLOB.
CRYPT_NO_SALT	Une valeur sans sel est allouée pour une clé symétrique 40 bits. Pour plus d’informations, consultez Salt Value Functionality.
CRYPT_USER_PROTECTED	Si cet indicateur est défini, le fournisseur de solutions Cloud avertit l’utilisateur par le biais d’une boîte de dialogue ou d’une autre méthode lorsque certaines actions sont tentées à l’aide de cette clé. Le comportement précis est spécifié par le csp ou le type csp utilisé. Si le contexte du fournisseur a été acquis avec CRYPT_SILENT défini, l’utilisation de cet indicateur entraîne un échec et la dernière erreur est définie sur NTE_SILENT_CONTEXT.
CRYPT_IPSEC_HMAC_KEY	Permet l’importation d’une clé RC2 supérieure à 16 octets. Si cet indicateur n’est pas défini, les appels à la fonction CryptImportKey avec des clés RC2 supérieures à 16 octets échouent et un appel à GetLastError retourne NTE_BAD_DATA.

[out] phKey

Pointeur vers une valeur HCRYPTKEY qui reçoit le handle de la clé importée. Lorsque vous avez terminé d’utiliser la clé, relâchez le handle en appelant la fonction CryptDestroyKey .

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur préfacés par « NTE » sont générés par le fournisseur de solutions Cloud particulier utilisé. Certains codes d’erreur possibles suivent.

Code de retour	Description
ERROR_BUSY	Certains fournisseurs de services cloud définissent cette erreur si une clé privée est importée dans un conteneur alors qu’un autre thread ou processus utilise cette clé.
ERROR_INVALID_HANDLE	L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER	L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_ALGID	L’objet BLOB de clé simple à importer n’est pas chiffré avec l’algorithme d’échange de clés attendu.
NTE_BAD_DATA	Soit l’algorithme qui fonctionne avec la clé publique à importer n’est pas pris en charge par ce fournisseur de solutions Cloud, soit une tentative d’importation d’une clé de session qui a été chiffrée avec autre chose qu’une de vos clés publiques.
NTE_BAD_FLAGS	Le paramètre dwFlags spécifié n’est pas valide.
NTE_BAD_TYPE	Le type d’objet blob de clé n’est pas pris en charge par ce fournisseur de solutions Cloud et n’est peut-être pas valide.
NTE_BAD_UID	Le paramètre hProv ne contient pas de handle de contexte valide.
NTE_BAD_VER	Le numéro de version de l’objet BLOB de clé ne correspond pas à la version csp. Cela indique généralement que le fournisseur de solutions Cloud doit être mis à niveau.

Remarques

Lors de l’importation d’une clé HMAC ( Hash-Based Message Authentication Code ), l’appelant doit identifier la clé importée en tant que type PLAINTEXTKEYBLOB et définir l’identificateur d’algorithme approprié dans le champ aiKeyAlg de l’en-tête BLOB PUBLICKEYSTRUC .

La fonction CryptImportKey peut être utilisée pour importer une clé de texte clair pour les algorithmes symétriques ; Toutefois, nous vous recommandons d’utiliser la fonction CryptGenKey à la place pour faciliter l’utilisation. Lorsque vous importez une clé de texte clair, la structure de l’objet BLOB de clé qui est passé dans le paramètre pbData est une PLAINTEXTKEYBLOB.

Vous pouvez utiliser le type PLAINTEXTKEYBLOB avec n’importe quel algorithme ou type de combinaison de clés pris en charge par le fournisseur de solutions Cloud en cours d’utilisation.

Pour obtenir un exemple d’importation d’une clé de texte clair, consultez Exemple de programme C : importation d’une clé de texte clair.

L’exemple suivant montre comment définir les champs d’en-tête.

keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the 
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;

La longueur de la clé est spécifiée dans keyBlob.keyLength, qui est suivi des données de clé réelles.

Note Les algorithmes HMAC n’ont pas leurs propres identificateurs d’algorithme ; utilisez CALG_RC2 à la place. CRYPT_IPSEC_HMAC_KEY autorise l’importation de clés RC2 de plus de 16 octets.

Pour toutes les permutations de clé DATA Encryption Standard (DES) qui utilisent PLAINTEXTKEYBLOB, seule la taille de clé complète, y compris le bit de parité, peut être importée.

Les tailles de clé suivantes sont prises en charge.

Algorithm	Taille de clé prise en charge
CALG_DES	64 bits
CALG_3DES_112	128 bits
CALG_3DES	192 bits

Exemples

L’exemple suivant montre comment importer une clé à partir d’un objet BLOB de clé. Pour obtenir un exemple complet de cette fonction, consultez Exemple de programme C : signature d’un hachage et vérification de la signature de hachage. Pour obtenir du code supplémentaire qui utilise cette fonction, consultez Exemple de programme C : Déchiffrement d’un fichier.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
    HCRYPTKEY hPubKey;

    //---------------------------------------------------------------
    // This code assumes that a cryptographic provider (hProv) 
    // has been acquired and that a key BLOB (pbKeyBlob) that is 
    // dwBlobLen bytes long has been acquired. 

    //---------------------------------------------------------------
    // Get the public key of the user who created the digital 
    // signature and import it into the CSP by using CryptImportKey. 
    // The key to be imported is in the buffer pbKeyBlob that is  
    // dwBlobLen bytes long. This function returns a handle to the 
    // public key in hPubKey.

    if(CryptImportKey(
        hProv,
        pbKeyBlob,
        dwBlobLen,
        0,
        0,
        &hPubKey))
    {
        printf("The key has been imported.\n");
    }
    else
    {
        printf("Public key import failed.\n");
        return FALSE;
    }

    //---------------------------------------------------------------
    // Insert code that uses the imported public key here.
    //---------------------------------------------------------------

    //---------------------------------------------------------------
    // When you have finished using the key, you must release it.
    if(CryptDestroyKey(hPubKey))
    {
        printf("The public key has been released.");
    }
    else
    {
        printf("The public key has not been released.");
        return FALSE;
    }

    return TRUE;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll

Voir aussi

CryptAcquireContext

CryptDestroyKey

CryptExportKey

Fonctions De génération de clés et Exchange