Partager via

sp_describe_parameter_encryption (Transact-SQL)

  • Article

S’applique à : SQL Server 2016 (13.x) et versions ultérieures Azure SQL Database Azure SQL Managed Instance

Analyse l’instruction Transact-SQL spécifiée et ses paramètres pour déterminer quels paramètres correspondent aux colonnes de base de données protégées à l’aide de la fonctionnalité Always Encrypted. Retourne les métadonnées de chiffrement pour les paramètres qui correspondent aux colonnes chiffrées.

Syntaxe

sp_describe_parameter_encryption
    [ @tsql = ] N'tsql'
    [ , [ @params = ] N'params [ , ...n ]' ]
[ ; ]

Arguments

[ @tsql = ] 'tsql'

Une ou plusieurs instructions Transact-SQL. @tsql peut être nvarchar(n) ou nvarchar(max).

[ @params = ] N’params'

@params fournit une chaîne de déclaration pour les paramètres de @tsql, qui est similaire à sp_executesql. Les paramètres peuvent être nvarchar(n) ou nvarchar(max).

Chaîne qui contient les définitions de tous les paramètres incorporés dans l’SQL_batch Transact-SQL_batch. Cette chaîne doit être une constante Unicode ou une variable Unicode. Chaque définition de paramètre se compose d'un nom de paramètre et d'un type de données. n correspond à un espace réservé pour d’autres définitions de paramètres. n correspond à un espace réservé pour d’autres définitions de paramètres. Chaque paramètre spécifié dans l’instruction doit être défini dans @params. Si l’instruction Transact-SQL ou le lot de l’instruction ne contient pas de paramètres, @params n’est pas obligatoire. NULL est la valeur par défaut de ce paramètre.

Valeur retournée

0 indique la réussite. Tout autre élément indique l’échec.

Jeu de résultats

sp_describe_parameter_encryption retourne deux jeux de résultats :

  • Le jeu de résultats décrivant les clés de chiffrement configurées pour les colonnes de base de données, les paramètres de l’instruction Transact-SQL spécifiée correspondent.

  • Jeu de résultats décrivant comment les paramètres particuliers doivent être chiffrés. Ce jeu de résultats fait référence aux clés décrites dans le premier jeu de résultats.

Chaque ligne du premier jeu de résultats décrit une paire de clés : une clé de chiffrement de colonne chiffrée et sa clé principale de colonne correspondante (CMK).

Nom de la colonne Type de données Description
column_encryption_key_ordinal int ID de la ligne dans le jeu de résultats.
database_id int ID de la base de données.
column_encryption_key_id int ID de clé de chiffrement de colonne.

Remarque : cet ID indique une ligne dans l’affichage catalogue sys.column_encryption_keys .
column_encryption_key_version int Réservé pour un usage futur. Actuellement, contient 1toujours .
column_encryption_key_metadata_version binary(8) Horodatage représentant l’heure de création de la clé de chiffrement de colonne.
column_encryption_key_encrypted_value varbinary(4000) Valeur chiffrée de la clé de chiffrement de colonne.
column_master_key_store_provider_name sysname Nom du fournisseur pour le magasin de clés qui contient la clé CMK, qui a été utilisée pour produire la valeur chiffrée de la clé de chiffrement de colonne.
column_master_key_path nvarchar(4000) Chemin d’accès de clé de la clé CMK, qui a été utilisé pour produire la valeur chiffrée de la clé de chiffrement de colonne.
column_encryption_key_encryption_algorithm_name sysname Nom de l’algorithme de chiffrement utilisé pour produire la valeur de chiffrement de la clé de chiffrement de colonne.

Chaque ligne du deuxième jeu de résultats contient des métadonnées de chiffrement pour un paramètre.

Nom de la colonne Type de données Description
parameter_ordinal int ID de la ligne dans le jeu de résultats.
parameter_name sysname Nom de l’un des paramètres spécifiés dans l’argument @params .
column_encryption_algorithm tinyint Code indiquant l’algorithme de chiffrement configuré pour la colonne à laquelle correspond le paramètre. La valeur actuellement prise en charge est 2 pour AEAD_AES_256_CBC_HMAC_SHA_256.
column_encryption_type tinyint Code indiquant le type de chiffrement configuré pour la colonne, le paramètre correspond. Les valeurs prises en charge sont :

0 - texte en clair (la colonne n’est pas chiffrée)
1 - chiffrement déterministe
2 - chiffrement aléatoire.
column_encryption_key_ordinal int Code de la ligne dans le premier jeu de résultats. La ligne référencée décrit la clé de chiffrement de colonne configurée pour la colonne, le paramètre correspond.
column_encryption_normalization_rule_version tinyint Numéro de version de l’algorithme de normalisation de type.

Notes

Pilote client SQL Server, prenant en charge Always Encrypted, appelle sp_describe_parameter_encryption automatiquement pour récupérer les métadonnées de chiffrement pour les requêtes paramétrables émises par l’application. Ensuite, le pilote utilise les métadonnées de chiffrement pour chiffrer les valeurs des paramètres qui correspondent aux colonnes de base de données protégées par Always Encrypted. Il remplace les valeurs de paramètre en texte clair envoyées par l’application, par les valeurs de paramètre chiffrées, avant d’envoyer la requête au moteur de base de données.

autorisations

Exiger les autorisations VIEW ANY COLUMN ENCRYPTION KEY DEFINITION et VIEW ANY COLUMN MASTER KEY DEFINITION dans la base de données.

Exemples

L’exemple suivant tronque la valeur pour ENCRYPTED_VALUE, à des fins d’affichage.

CREATE COLUMN MASTER KEY [CMK1]
WITH (
    KEY_STORE_PROVIDER_NAME = N'MSSQL_CERTIFICATE_STORE',
    KEY_PATH = N'CurrentUser/my/A66BB0F6DD70BDFF02B62D0F87E340288E6F9305'
);
GO

CREATE COLUMN ENCRYPTION KEY [CEK1]
WITH VALUES (
    COLUMN_MASTER_KEY = [CMK1],
    ALGORITHM = 'RSA_OAEP',
    ENCRYPTED_VALUE = 0x016E00000163007500720072<...> -- truncated in this example
);
GO

CREATE TABLE t1 (
    c1 INT ENCRYPTED WITH (
        COLUMN_ENCRYPTION_KEY = [CEK1],
        ENCRYPTION_TYPE = Randomized,
        ALGORITHM = 'AEAD_AES_256_CBC_HMAC_SHA_256'
        ) NULL,
);
    
EXEC sp_describe_parameter_encryption
    N'INSERT INTO t1 VALUES(@c1)',
    N'@c1 INT';

Voici le premier jeu de résultats :

Colonne Valeur
column_encryption_key_ordinal 1
database_id 5
column_encryption_key_id 1
column_encryption_key_version 1
column_encryption_key_metadata_version 0x99EDA60083A50000
column_encryption_key_encrypted_value 0x016E00000163007500720072<...>
column_master_key_store_provider_name MSSQL_CERTIFICATE_STORE
column_master_key_path CurrentUser/my/A66BB0F6DD70BDFF02B62D0F87E340288E6F9305
column_encryption_key_encryption_algorithm_name RSA_OAEP

Voici le deuxième jeu de résultats :

Colonne Valeur
parameter_ordinal 1
parameter_name @c1
column_encryption_algorithm 1
column_encryption_type 1
column_encryption_key_ordinal 1
column_encryption_normalization_rule_version 1

Contenu connexe