Fournisseurs de magasins de clés personnalisés

Article
06/02/2023

Vue d’ensemble

La fonctionnalité de chiffrement de colonne de SQL Server 2016 exige que les clés de chiffrement de colonne chiffrées (ECEK) stockées sur le serveur soient récupérées par le client, puis déchiffrées en clés de chiffrement de colonne (CEK) afin d’accéder aux données stockées dans des colonnes chiffrées. Les clés ECEK sont chiffrées par les clés principales de colonne (CMK), et la sécurité de la clé CMK est importante pour la sécurité du chiffrement de colonne. Ainsi, la clé CMK doit être stockée dans un emplacement sécurisé. L’objectif d’un fournisseur de magasins de clés de chiffrement de colonne consiste à fournir une interface permettant au pilote ODBC d’accéder à ces clés CMK stockées en toute sécurité. Pour les utilisateurs disposant de leur propre stockage sécurisé, l’interface personnalisée du fournisseur de magasin de clés fournit une infrastructure afin d’implémenter l’accès au stockage sécurisé des clés CMK pour le pilote ODBC, qui permet alors d’effectuer le chiffrement et le déchiffrement de la clé CEK.

Chaque fournisseur de magasin de clés contient et gère une ou plusieurs clés CMK, identifiées par des chemins de clés - chaînes d’un format défini par le fournisseur. Ce CMK, avec l’algorithme de chiffrement, également une chaîne définie par le fournisseur, permet d’effectuer le chiffrement d’une clé CEK et le déchiffrement d’une clé ECEK. L’algorithme, ainsi que la clé ECEK et le nom du fournisseur sont stockés dans les métadonnées de chiffrement de la base de données. Pour plus d’informations, consultez CREATE COLUMN MASTER KEY et CREATE COLUMN ENCRYPTION KEY. Ainsi, les deux opérations fondamentales de gestion des clés sont les suivantes :

CEK = DecryptViaCEKeystoreProvider(CEKeystoreProvider_name, Key_path, Key_algorithm, ECEK)

-and-

ECEK = EncryptViaCEKeystoreProvider(CEKeyStoreProvider_name, Key_path, Key_algorithm, CEK)

où CEKeystoreProvider_name sert à identifier le fournisseur de magasin de clés de chiffrement de colonne spécifique (CEKeystoreProvider), et les autres arguments sont utilisés par CEKeystoreProvider pour chiffrer/déchiffrer la clé (E)CEK. Le nom et le chemin de la clé sont fournis par les métadonnées CMK, tandis que l’algorithme et la valeur ECEK sont fournies par les métadonnées CEK. Plusieurs fournisseurs de magasin de clés peuvent être présents avec le ou les fournisseurs intégrés par défaut. Lors de l’exécution d’une opération qui requiert la clé CEK, le pilote utilise les métadonnées CMK pour rechercher le fournisseur de magasin de clés approprié par nom, puis exécute son opération de déchiffrement, qui peut être exprimée comme suit :

CEK = CEKeyStoreProvider_specific_decrypt(Key_path, Key_algorithm, ECEK)

Bien que le pilote n’ait pas besoin de chiffrer les clés CEK, un outil de gestion de clés peut nécessiter cette opération afin de mettre en œuvre des opérations telles que la création et la rotation CMK. Ces actions requièrent l’exécution de l’opération inverse :

ECEK = CEKeyStoreProvider_specific_encrypt(Key_path, Key_algorithm, CEK)

Interface CEKeyStoreProvider

Ce document décrit en détail l’interface CEKeyStoreProvider. Un fournisseur de magasin de clés qui implémente cette interface peut être utilisé par Microsoft ODBC Driver pour SQL Server. Les implémenteurs CEKeyStoreProvider peuvent utiliser ce guide pour développer des fournisseurs de clés personnalisés utilisables par le pilote.

Une bibliothèque de fournisseurs de magasin de clés (« bibliothèque de fournisseur ») est une bibliothèque de liens dynamiques qui peut être chargée par le pilote ODBC et qui contient un ou plusieurs fournisseurs de magasin de clés. Le symbole CEKeystoreProvider doit être exporté par une bibliothèque de fournisseur et représenter l’adresse d’un tableau de pointeurs se terminant par un caractère Null vers des structures CEKeystoreProvider, une pour chaque fournisseur de magasin de clés dans la bibliothèque.

Une structure CEKeystoreProvider définit les points d’entrée d’un fournisseur de magasin de clés unique :

typedef struct CEKeystoreProvider {
    wchar_t *Name;
    int (*Init)(CEKEYSTORECONTEXT *ctx, errFunc *onError);
    int (*Read)(CEKEYSTORECONTEXT *ctx, errFunc *onError, void *data, unsigned int *len);
    int (*Write)(CEKEYSTORECONTEXT *ctx, errFunc *onError, void *data, unsigned int len);
    int (*DecryptCEK)(  CEKEYSTORECONTEXT *ctx,
                        errFunc *onError,
                        const wchar_t *keyPath,
                        const wchar_t *alg,
                        unsigned char *ecek,
                        unsigned short ecekLen,
                        unsigned char **cekOut,
                        unsigned short *cekLen);
    int (*EncryptCEK)(  CEKEYSTORECONTEXT *ctx,
                        errFunc *onError,
                        const wchar_t *keyPath,
                        const wchar_t *alg,
                        unsigned char *cek,
                        unsigned short cekLen,
                        unsigned char **ecekOut,
                        unsigned short *ecekLen);
    void (*Free)();
} CEKEYSTOREPROVIDER;

Nom du champ	Description
`Name`	Nom du fournisseur de magasins de clés. Il ne doit pas être identique à celui d'un autre fournisseur de clés préalablement chargé par le pilote ou présent dans cette bibliothèque. Chaîne à caractères larges* se terminant par le caractère Null.
`Init`	Fonction d’initialisation. Si aucune fonction d’initialisation n’est requise, ce champ peut avoir la valeur Null.
`Read`	Fonction de lecture du fournisseur. Peut avoir la valeur Null si pas obligatoire.
`Write`	Fonction d’écriture du fournisseur. Obligatoire si Read n’a pas la valeur Null. Peut avoir la valeur Null si pas obligatoire.
`DecryptCEK`	Fonction de déchiffrement ECEK. Cette fonction est la raison d'être d'un fournisseur de clés, et ne doit pas avoir la valeur Null.
`EncryptCEK`	Fonction de chiffrement CEK. Le pilote n'appelle pas cette fonction, mais elle est fournie pour permettre un accès par programmation à la création de clés ECEK par les outils de gestion des clés. Peut avoir la valeur Null si pas obligatoire.
`Free`	Fonction d'arrêt. Peut avoir la valeur Null si pas obligatoire.

À l’exception de Free, les fonctions de cette interface comportent toutes une paire de paramètres, CTX et onError. Le premier identifie le contexte dans lequel la fonction est appelée, tandis que le second est utilisé pour signaler les erreurs. Pour plus d’informations, consultez Contextes et Gestion des erreurs ci-dessous.

int Init(CEKEYSTORECONTEXT *ctx, errFunc onError);

Nom de l’espace réservé d’une fonction d'initialisation définie par le fournisseur. Le pilote appelle cette fonction une fois, après le chargement d'un fournisseur, mais avant la première fois qu'il en a besoin pour déchiffrer des clés ECEK ou exécuter des requêtes Read()/Write(). Utilisez cette fonction pour effectuer l’initialisation requise.

Argument	Description
`ctx`	[Input] Contexte d'opération.
`onError`	[Input] Fonction de création de rapports d’erreurs.
`Return Value`	Retourne une valeur différente de zéro pour indiquer la réussite, ou zéro pour indiquer l’échec.

int Read(CEKEYSTORECONTEXT *ctx, errFunc onError, void *data, unsigned int *len);

Nom de l’espace réservé d’une fonction de communication définie par le fournisseur. Le pilote appelle cette fonction lorsque l’application demande à lire les données d’un fournisseur (précédemment écrites) en utilisant l’attribut de connexion SQL_COPT_SS_CEKEYSTOREDATA, permettant à l’application de lire des données arbitraires du fournisseur. Pour plus d’informations, consultez Communication avec les fournisseurs de magasins de clés.

Argument	Description
`ctx`	[Input] Contexte d'opération.
`onError`	[Input] Fonction de création de rapports d’erreurs.
`data`	[Output] Pointeur vers une mémoire tampon dans laquelle le fournisseur écrit des données à lire par l'application. Ce tampon correspond au champ data de la structure CEKEYSTOREDATA.
`len`	[InOut] Pointeur vers une valeur de longueur ; lors de l’entrée, cette valeur est la longueur maximale de la mémoire tampon de données, et le fournisseur ne doit pas y écrire plus de `len` octets. Lors du retour, le fournisseur doit mettre à jour la valeur `len` avec le nombre d’octets écrits.
`Return Value`	Retourne une valeur différente de zéro pour indiquer la réussite, ou zéro pour indiquer l’échec.

int Write(CEKEYSTORECONTEXT *ctx, errFunc onError, void *data, unsigned int len);

Nom de l’espace réservé d’une fonction de communication définie par le fournisseur. Le pilote appelle cette fonction lorsque l'application demande à écrire les données vers un fournisseur en utilisant l'attribut de connexion SQL_COPT_SS_CEKEYSTOREDATA, permettant à l'application d’écrire des données arbitraires vers le fournisseur. Pour plus d’informations, consultez Communication avec les fournisseurs de magasins de clés.

Argument	Description
`ctx`	[Input] Contexte d'opération.
`onError`	[Input] Fonction de création de rapports d’erreurs.
`data`	[Input] Pointeur vers une mémoire tampon contenant les données que le fournisseur doit lire. Ce tampon correspond au champ data de la structure CEKEYSTOREDATA. Le fournisseur ne doit pas lire plus de len octets à partir de cette mémoire tampon.
`len`	[Input] Nombre d’octets disponibles dans les données. Cette valeur correspond au champ dataSize de la structure CEKEYSTOREDATA.
`Return Value`	Retourne une valeur différente de zéro pour indiquer la réussite, ou zéro pour indiquer l’échec.

int (*DecryptCEK)( CEKEYSTORECONTEXT *ctx, errFunc *onError, const wchar_t *keyPath, const wchar_t *alg, unsigned char *ecek, unsigned short ecekLen, unsigned char **cekOut, unsigned short *cekLen);

Nom de l’espace réservé d’une fonction de déchiffrement ECEK définie par le fournisseur. Le pilote appelle cette fonction pour déchiffrer une clé ECEK chiffrée par une clé CMK associée à ce fournisseur dans une clé CEK.

Argument	Description
`ctx`	[Input] Contexte d'opération.
`onError`	[Input] Fonction de création de rapports d’erreurs.
`keyPath`	[Input] Valeur de l'attribut de métadonnées KEY_PATH pour la clé CMK référencée par la clé ECEK donnée. Chaîne à caractères larges* se terminant par le caractère Null. Cette valeur vise à identifier une clé CMK gérée par ce fournisseur.
`alg`	[Input] Valeur de l’attribut de métadonnées ALGORITHM pour la clé ECEK donnée. Chaîne à caractères larges* se terminant par le caractère Null. Cette valeur vise à identifier l’algorithme de chiffrement utilisé pour chiffrer la clé ECEK donnée.
`ecek`	[Input] Pointeur vers la clé ECEK à déchiffrer.
`ecekLen`	[Input] Longueur de la clé ECEK.
`cekOut`	[Output] Le fournisseur doit allouer de la mémoire pour la clé ECEK déchiffrée et écrire son adresse sur le pointeur pointé par cekOut. Il doit être possible de libérer ce bloc de mémoire à l’aide de la fonction LocalFree (Windows) ou Free (Linux/macOS). Si aucune mémoire n’a été allouée en raison d’une erreur ou d’un autre problème, le fournisseur doit définir *cekOut sur un pointeur Null.
`cekLen`	[Output] Le fournisseur doit écrire dans l’adresse pointée par cekLen la longueur de la clé ECEK déchiffrée dans laquelle il a écrit **cekOut.
`Return Value`	Retourne une valeur différente de zéro pour indiquer la réussite, ou zéro pour indiquer l’échec.

int (*EncryptCEK)( CEKEYSTORECONTEXT *ctx, errFunc *onError, const wchar_t *keyPath, const wchar_t *alg, unsigned char *cek,unsigned short cekLen, unsigned char **ecekOut, unsigned short *ecekLen);

Nom de l’espace réservé d’une fonction de chiffrement CEK définie par le fournisseur. Le pilote n'appelle pas cette fonction ni n’expose sa fonctionnalité via l’interface ODBC, mais elle est fournie pour permettre un accès par programmation à la création de clés ECEK par les outils de gestion des clés.

Argument	Description
`ctx`	[Input] Contexte d'opération.
`onError`	[Input] Fonction de création de rapports d’erreurs.
`keyPath`	[Input] Valeur de l'attribut de métadonnées KEY_PATH pour la clé CMK référencée par la clé ECEK donnée. Chaîne à caractères larges* se terminant par le caractère Null. Cette valeur vise à identifier une clé CMK gérée par ce fournisseur.
`alg`	[Input] Valeur de l’attribut de métadonnées ALGORITHM pour la clé ECEK donnée. Chaîne à caractères larges* se terminant par le caractère Null. Cette valeur vise à identifier l’algorithme de chiffrement utilisé pour chiffrer la clé ECEK donnée.
`cek`	[Input] Pointeur vers la clé CEK à chiffrer.
`cekLen`	[Input] Longueur de la clé CEK.
`ecekOut`	[Output] Le fournisseur doit allouer de la mémoire pour la clé CEK chiffrée et écrire son adresse sur le pointeur pointé par ecekOut. Il doit être possible de libérer ce bloc de mémoire à l’aide de la fonction LocalFree (Windows) ou Free (Linux/macOS). Si aucune mémoire n’a été allouée en raison d’une erreur ou d’un autre problème, le fournisseur doit définir *ecekOut sur un pointeur Null.
`ecekLen`	[Output] Le fournisseur doit écrire dans l’adresse pointée par ecekLen la longueur de la clé CEK chiffrée dans laquelle il a écrit **ecekOut.
`Return Value`	Retourne une valeur différente de zéro pour indiquer la réussite, ou zéro pour indiquer l’échec.

void (*Free)();

Nom de l’espace réservé d’une fonction d’arrêt définie par le fournisseur. Le pilote peut appeler cette fonction à l’arrêt normal du processus.

Notes

Les chaînes à caractères larges sont des caractères à 2 octets (UTF-16) en raison de la façon dont SQL Server les stocke.

Gestion des erreurs

Des erreurs pouvant se produire pendant le traitement d’un fournisseur, un mécanisme est fourni pour lui permettre de signaler des erreurs au pilote dans des détails plus spécifiques qu’une valeur booléenne de réussite/échec. La plupart des fonctions disposent d’une paire de paramètres, CTX et onError, utilisés conjointement à cet effet, en plus de la valeur de retour de réussite/échec.

Le paramètre ctx identifie le contexte dans lequel se déroule une opération du fournisseur.

Le paramètre onError pointe vers une fonction de rapport d’erreurs, avec le prototype suivant :

typedef void errFunc(CEKEYSTORECONTEXT *ctx, const wchar_t *msg, ...);

Argument	Description
`ctx`	[Input] Contexte du signalement de l’erreur.
`msg`	[Input] Message d'erreur à signaler. Chaîne à caractères larges se terminant par le caractère Null. Pour autoriser les informations paramétrables, cette chaîne peut contenir des séquences de mise en forme d’insertion acceptées par la fonction FormatMessage. La fonctionnalité étendue peut être spécifiée par ce paramètre, comme décrit ci-dessous.
...	[Input] Paramètres variadiques supplémentaires pour ajuster les spécificateurs de format dans le message, le cas échéant.

Pour signaler qu’une erreur s’est produite, le fournisseur appelle onError, en spécifiant le paramètre de contexte passé dans la fonction de fournisseur par le pilote ainsi qu’un message d’erreur avec des paramètres supplémentaires facultatifs à mettre en forme. Le fournisseur peut appeler cette fonction plusieurs fois pour envoyer consécutivement plusieurs messages d’erreur dans un appel de fonction de fournisseur. Par exemple :

    if (!doSomething(...))
    {
        onError(ctx, L"An error occurred in doSomething.");
        onError(ctx, L"Additional error message with more details.");
        return 0;
    }

Le paramètre msg représente généralement une chaîne de caractères larges, mais d’autres extensions sont disponibles :

En utilisant l’une des valeurs prédéfinies spéciales avec la macro IDS_MSG, vous pouvez utiliser des messages d’erreur génériques déjà existants et sous une forme localisée dans le pilote. Par exemple, si un fournisseur ne parvient pas à allouer de la mémoire, le message IDS_S1_001 « Échec de l'allocation de mémoire » peut être utilisé :

onError(ctx, IDS_MSG(IDS_S1_001));

Pour que l’erreur soit reconnue par le pilote, la fonction du fournisseur doit retourner un échec. En cas d’échec dans le contexte d’une opération ODBC, les erreurs publiées deviennent accessibles sur la connexion ou le descripteur d’instruction par le biais du mécanisme de diagnostic ODBC standard (SQLError, SQLGetDiagRecet SQLGetDiagField).

Association de contextes

La structure CEKEYSTORECONTEXT, en plus de fournir le contexte pour le rappel d’erreur, permet également de déterminer le contexte ODBC dans lequel une opération de fournisseur est exécutée. Ce contexte permet à un fournisseur d’associer des données à chacun de ces contextes, par exemple pour implémenter une configuration par connexion. À cet effet, la structure contient trois pointeurs opaques correspondant à l’environnement, à la connexion et au contexte d’instruction :

typedef struct CEKeystoreContext
{
void *envCtx;
void *dbcCtx;
void *stmtCtx;
} CEKEYSTORECONTEXT;

Champ	Description
`envCtx`	Contexte de l’environnement.
`dbcCtx`	Contexte de la connexion.
`stmtCtx`	Contexte de l’instruction.

Chacun de ces contextes représente une valeur opaque qui, bien qu’elle ne corresponde pas au descripteur ODBC correspondant, peut être utilisée comme identificateur unique pour le descripteur : si le descripteur X est associé à la valeur de contexte Y, aucun autre environnement, descripteur d’instruction ni connexion qui existe simultanément avec X n’aura une valeur de contexte Y, et aucune autre valeur de contexte ne sera associée au descripteur X. Si l’opération du fournisseur en cours d’exécution ne dispose pas d’un contexte de descripteur particulier (par exemple les appels SQLSetConnectAttr pour charger et configurer des fournisseurs, dans lesquels il n’y a aucun descripteur d’instruction), la valeur de contexte correspondante dans la structure est Null.

Exemple