Fonction CryptImportKey (wincrypt.h)
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 PUBLICKEYSTRUC BLOB suivi de la clé chiffrée. Cette clé BLOB est créée par la fonction CryptExportKey, dans cette application ou 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 vers la clé de chiffrement qui déchiffre la clé stockée dans pbData. Cette clé doit provenir du même 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 de blob de clé importé :
- Si l’objet BLOB de clé est chiffré avec la paire de clés exchange , par exemple, une SIMPLEBLOB, ce paramètre peut être le handle de la clé d’échange de clé.
- Si la clé BLOB est chiffrée avec une clé de session, par exemple, un PRIVATEKEYBLOB chiffré, ce paramètre contient le handle de cette clé de session.
- Si l’objet BLOB de clé n’est pas chiffré, par exemple, une PUBLICKEYBLOB, ce paramètre n’est pas utilisé et doit être égal à zéro.
- Si la clé BLOB est chiffrée avec une clé de session dans une Schannel CSP, par exemple, un CHIFFRÉ OPAQUEKEYBLOB ou tout autre OPAQUEKEYBLOB spécifique au fournisseur, ce paramètre n’est pas utilisé et doit être défini sur zéro.
[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 fournisseur de solutions Cloud.
Ce paramètre peut être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
La clé importée est finalement réexportée. Si cet indicateur n’est pas utilisé, les appels à CryptExportKey avec le handle de clé échouent. |
|
Cet indicateur entraîne la vérification de la mise en forme PKCS #1 version 2 avec le chiffrement RSA et le déchiffrement lors de l’importation SIMPLEBLOBs. |
|
Une valeur sans sel |
|
Si cet indicateur est défini, le fournisseur de solutions Cloud avertit l’utilisateur via une boîte de dialogue ou une autre méthode lorsque certaines actions sont tentées à l’aide de cette clé. Le comportement précis est spécifié par le fournisseur de solutions Cloud ou le type CSP utilisé. Si le contexte du fournisseur a été acquis avec CRYPT_SILENT set, l’utilisation de cet indicateur provoque un échec et la dernière erreur est définie sur NTE_SILENT_CONTEXT. |
|
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 de retour
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écédés par « NTE » sont générés par le fournisseur de solutions Cloud en cours d’utilisation. Certains codes d’erreur possibles suivent.
| Retourner le code | Description |
|---|---|
|
Certains fournisseurs de solutions cloud définissent cette erreur si une clé privée est importée dans un conteneur tandis qu’un autre thread ou processus utilise cette clé. |
|
L’un des paramètres spécifie un handle qui n’est pas valide. |
|
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. |
|
Le blob de clé simple à importer n’est pas chiffré avec l’algorithme d’échange de clés attendu. |
|
L’algorithme qui fonctionne avec la clé publique à importer n’est pas pris en charge par ce fournisseur de solutions Cloud, ou une tentative a été effectuée pour importer une clé de session qui a été chiffrée avec quelque chose d’autre que l’une de vos clés publiques. |
|
Le paramètre dwFlags spécifié n’est pas valide. |
|
Le type BLOB de clé n’est pas pris en charge par ce fournisseur de solutions Cloud et n’est peut-être pas valide. |
|
Le paramètre hProv ne contient pas de handle de contexte valide. |
|
Le numéro de version de la clé BLOB 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é Hash-Based code d’authentification de message (HMAC), 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 PUBLICKEYSTRUC BLOB.
La fonction CryptImportKey peut être utilisée pour importer une clé en 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é en texte clair, la structure de la clé BLOB transmise dans le paramètre pbData est une PLAINTEXTKEYBLOB.
Vous pouvez utiliser le type PLAINTEXTKEYBLOB avec n’importe quel algorithme ou type de combinaison de touches prise en charge par le fournisseur de solutions Cloud en cours d’utilisation.
Pour obtenir un exemple d’importation d’une clé en texte clair, consultez Exemple de programme C : importation d’une clé en texte brut.
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, suivie des données de clé réelles.
Les tailles de clé suivantes sont prises en charge.
| Algorithme | 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és. Pour obtenir un exemple complet pour 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;
}
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | wincrypt.h |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |