Partager via


CryptExportKey, fonction (wincrypt.h)

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 CryptExportKey exporte une clé de chiffrement ou une paire de clés à partir d’un fournisseur de services de chiffrement (CSP) de manière sécurisée.

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.

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] 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
OPAQUEKEYBLOB
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.
PRIVATEKEYBLOB
Utilisé pour transporter des paires de clés publiques/privées.
PUBLICKEYBLOB
Utilisé pour transporter des clés publiques.
SIMPLEBLOB
Utilisé pour le transport des clés de session.
PLAINTEXTKEYBLOB
PLAINTEXTKEYBLOB utilisé pour exporter toute clé prise en charge par le fournisseur de solutions Cloud en cours d’utilisation.
SYMMETRICWRAPKEYBLOB
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
CRYPT_BLOB_VER3
0x00000080
Cet indicateur entraîne l’exportation de la version 3 d’un type BLOB par cette fonction.
CRYPT_DESTROYKEY
0x00000004
Cet indicateur détruit la clé d’origine dans OPAQUEKEYBLOB. Cet indicateur est disponible uniquement dans les fournisseurs de services cloud Schannel.
CRYPT_OAEP
0x00000040
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.
CRYPT_SSL2_FALLBACK
0x00000002
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.
CRYPT_Y_ONLY
0x00000001
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.

Note Lors du traitement des données retournées dans la mémoire tampon, les applications doivent utiliser la taille réelle des données retournées. La taille réelle peut être légèrement inférieure à la taille de la mémoire tampon spécifiée lors de l’entrée. Lors de l’entrée, les tailles de mémoire tampon sont généralement spécifiées suffisamment grandes pour garantir que les données de sortie les plus volumineuses possibles tiennent dans la mémoire tampon. En sortie, la variable pointée par ce paramètre est mise à jour pour refléter la taille réelle des données copiées dans la mémoire tampon.
 
Pour récupérer la taille requise de la mémoire tampon pbData , passez null pour pbData. La taille de mémoire tampon requise est placée dans la valeur pointée par ce paramètre.

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
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.
ERROR_MORE_DATA
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.
NTE_BAD_DATA
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.
NTE_BAD_FLAGS
Le paramètre dwFlags est différent de zéro.
NTE_BAD_KEY
L’une ou les deux clés spécifiées par hKey et hExpKey ne sont pas valides.
NTE_BAD_KEY_STATE
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é.
NTE_BAD_PUBLIC_KEY
Le type d’objet BLOB de clé spécifié par dwBlobType est PUBLICKEYBLOB, mais hExpKey ne contient pas de handle de clé publique.
NTE_BAD_TYPE
Le paramètre dwBlobType spécifie un type d’objet BLOB inconnu.
NTE_BAD_UID
Le contexte CSP spécifié lors de la création de la clé hKey est introuvable.
NTE_NO_KEY
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

Voir aussi

CryptImportKey

Génération de clés et fonctions Exchange