CryptExportKey, fonction (wincrypt.h)
Un handle à la clé à exporter est passé à la fonction et la fonction retourne un objet BLOB de clé. Cet objet BLOB de clé peut être envoyé via un transport non sécurisé ou stocké dans un emplacement de stockage non sécurisé. Cette fonction peut exporter une clé de session Schannel , une clé de session normale, une clé publique ou une paire de clés publique/privée. L’objet BLOB de clé à exporter est inutile jusqu’à ce que le destinataire prévu utilise la fonction CryptImportKey sur celui-ci pour importer la clé ou la paire de clés dans le fournisseur de services de configuration d’un destinataire.
Syntaxe
BOOL CryptExportKey(
[in] HCRYPTKEY hKey,
[in] HCRYPTKEY hExpKey,
[in] DWORD dwBlobType,
[in] DWORD dwFlags,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen
);
Paramètres
[in] hKey
Handle de la clé à exporter.
[in] hExpKey
Handle vers une clé de chiffrement de l’utilisateur de destination. Les données de clé dans l’objet BLOB de clé exporté sont chiffrées à l’aide de cette clé. Cela garantit que seul l’utilisateur de destination est en mesure d’utiliser l’objet BLOB de clé. HExpKey et hKey doivent provenir du même fournisseur de solutions Cloud.
Le plus souvent, il s’agit de la clé publique d’échange de clé de l’utilisateur de destination. Toutefois, certains protocoles de certains fournisseurs de solutions cloud nécessitent qu’une clé de session appartenant à l’utilisateur de destination soit utilisée à cet effet.
Si le type de clé BLOB spécifié par dwBlobType est PUBLICKEYBLOB, ce paramètre n’est pas utilisé et doit être défini sur zéro.
Si le type de clé BLOB spécifié par dwBlobType est PRIVATEKEYBLOB, il s’agit généralement d’un handle pour une clé de session qui doit être utilisée pour chiffrer la clé BLOB. Certains fournisseurs de services cloud autorisent ce paramètre à être égal à zéro, auquel cas l’application doit chiffrer manuellement l’objet BLOB de clé privée afin de le protéger.
Pour déterminer la façon dont les fournisseurs de services de chiffrement Microsoft répondent à ce paramètre, consultez les sections BLOB de clé privée des fournisseurs de services de chiffrement Microsoft.
[in] dwBlobType
Spécifie le type d’objet BLOB de clé à exporter dans pbData. Il doit s’agir de l’une des constantes suivantes, comme indiqué dans Stockage de clés de chiffrement et Exchange.
| Valeur | Signification |
|---|---|
|
Permet de stocker les clés de session dans un fournisseur CSP Schannel ou tout autre format spécifique au fournisseur. OPAQUEKEYBLOBs ne sont pas transférables et doivent être utilisés dans le fournisseur de solutions Cloud qui a généré l’objet BLOB. |
|
Utilisé pour transporter des paires de clés publiques/privées. |
|
Utilisé pour transporter des clés publiques. |
|
Utilisé pour le transport des clés de session. |
|
PLAINTEXTKEYBLOB utilisé pour exporter toute clé prise en charge par le fournisseur de solutions Cloud en cours d’utilisation. |
|
Permet d’exporter et d’importer une clé symétrique encapsulée avec une autre clé symétrique. La clé encapsulée réelle est au format spécifié dans la norme IETF RFC 3217 . |
[in] dwFlags
Spécifie des options supplémentaires pour la fonction. Ce paramètre peut être égal à zéro ou à une combinaison d’une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Cet indicateur entraîne l’exportation de la version 3 d’un type BLOB par cette fonction. |
|
Cet indicateur détruit la clé d’origine dans OPAQUEKEYBLOB. Cet indicateur est disponible uniquement dans les fournisseurs de services cloud Schannel. |
|
Cet indicateur entraîne la création de la mise en forme PKCS #1 version 2 avec le chiffrement et le déchiffrement RSA lors de l’exportation de SIMPLESBLOBs. |
|
Les huit premiers octets du remplissage du bloc de chiffrement RSA doivent être définis sur 0x03 plutôt que sur des données aléatoires. Cela empêche les attaques par restauration de version et est abordé dans la spécification SSL3. Cet indicateur est disponible uniquement pour les fournisseurs de services cloud Schannel. |
|
Cet indicateur n’est pas utilisé. |
[out] pbData
Pointeur vers une mémoire tampon qui reçoit les données BLOB clés . Le format de cet objet BLOB varie en fonction du type d’objet BLOB demandé dans le paramètre dwBlobType . Pour connaître le format de PRIVATEKEYBLOBs, PUBLICKEYBLOBs et SIMPLEBLOBs, consultez OBJETS BLOB de clés de fournisseur de base.
Si ce paramètre a la valeur NULL, la taille de mémoire tampon requise est placée dans la valeur pointée par le paramètre pdwDataLen . Pour plus d’informations, consultez Récupération de données de longueur inconnue.
[in, out] pdwDataLen
Pointeur vers une valeur DWORD qui, lors de l’entrée, contient la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pbData . Lorsque la fonction retourne, cette valeur contient le nombre d’octets stockés dans la mémoire tampon.
Valeur retournée
Si la fonction réussit, la fonction retourne une valeur différente de zéro (TRUE).
Si la fonction échoue, elle retourne zéro (FALSE). 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é. Le tableau suivant présente certains des codes d’erreur possibles.
| Code de retour | Description |
|---|---|
|
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. |
|
Si la mémoire tampon spécifiée par le paramètre pbData n’est pas assez grande pour contenir les données retournées, la fonction définit le code ERROR_MORE_DATA et stocke la taille de mémoire tampon requise, en octets, dans la variable pointée par pdwDataLen. |
|
Soit l’algorithme qui fonctionne avec la clé publique à exporter n’est pas pris en charge par ce fournisseur de solutions Cloud, soit une tentative d’exportation d’une clé de session qui a été chiffrée avec autre chose qu’une de vos clés publiques. |
|
Le paramètre dwFlags est différent de zéro. |
|
L’une ou les deux clés spécifiées par hKey et hExpKey ne sont pas valides. |
|
Vous n’avez pas l’autorisation d’exporter la clé. Autrement dit, lorsque la clé hKey a été créée, l’indicateur CRYPT_EXPORTABLE n’a pas été spécifié. |
|
Le type d’objet BLOB de clé spécifié par dwBlobType est PUBLICKEYBLOB, mais hExpKey ne contient pas de handle de clé publique. |
|
Le paramètre dwBlobType spécifie un type d’objet BLOB inconnu. |
|
Le contexte CSP spécifié lors de la création de la clé hKey est introuvable. |
|
Une clé de session est en cours d’exportation et le paramètre hExpKey ne spécifie pas de clé publique. |
Remarques
Pour toutes les permutations de clé DES qui utilisent un PLAINTEXTKEYBLOB, seule la taille de clé complète, y compris le bit de parité, peut être exporté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 exporter une clé de chiffrement ou une paire de clés de manière plus sécurisée. Cet exemple suppose qu’un contexte de chiffrement a été acquis et qu’une clé publique est disponible pour l’exportation. Pour obtenir un exemple qui inclut le contexte complet pour l’utilisation de cette fonction, consultez Exemple de programme C : signature d’un hachage et vérification de la signature de hachage. Pour un autre exemple qui utilise cette fonction, consultez Exemple de programme C : exportation d’une clé de session.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL GetExportedKey(
HCRYPTKEY hKey,
DWORD dwBlobType,
LPBYTE *ppbKeyBlob,
LPDWORD pdwBlobLen)
{
DWORD dwBlobLength;
*ppbKeyBlob = NULL;
*pdwBlobLen = 0;
// Export the public key. Here the public key is exported to a
// PUBLICKEYBLOB. This BLOB can be written to a file and
// sent to another user.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
NULL,
&dwBlobLength))
{
printf("Size of the BLOB for the public key determined. \n");
}
else
{
printf("Error computing BLOB length.\n");
return FALSE;
}
// Allocate memory for the pbKeyBlob.
if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength))
{
printf("Memory has been allocated for the BLOB. \n");
}
else
{
printf("Out of memory. \n");
return FALSE;
}
// Do the actual exporting into the key BLOB.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
*ppbKeyBlob,
&dwBlobLength))
{
printf("Contents have been written to the BLOB. \n");
*pdwBlobLen = dwBlobLength;
}
else
{
printf("Error exporting key.\n");
free(*ppbKeyBlob);
*ppbKeyBlob = NULL;
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 |