SQL Server 用 ODBC ドライバーと共に Always Encrypted を使用するUsing Always Encrypted with the ODBC Driver for SQL Server

ダウンロードODBC Driver のダウンロードDownloadDownload ODBC Driver

適用対象Applicable to

  • ODBC Driver 13.1 for SQL ServerODBC Driver 13.1 for SQL Server
  • ODBC Driver 17 for SQL ServerODBC Driver 17 for SQL Server

概要Introduction

この記事では、Always Encrypted (データベース エンジン)ODBC Driver for SQL Server を使用して ODBC アプリケーションを開発する方法について説明します。This article provides information on how to develop ODBC applications using Always Encrypted (Database Engine) and the ODBC Driver for SQL Server.

Always Encrypted を使用すると、クライアント アプリケーションは SQL Server または Azure SQL データベースにデータまたは暗号化キーを開示することなく、機密データを暗号化することができます。Always Encrypted allows client applications to encrypt sensitive data and never reveal the data or the encryption keys to SQL Server or Azure SQL Database. ODBC Driver for SQL Server など、Always Encrypted が有効なドライバーは、クライアント アプリケーション内の機密データを透過的に暗号化および暗号化解除することで、この処理を実行します。An Always Encrypted enabled driver, such as the ODBC Driver for SQL Server, achieves this by transparently encrypting and decrypting sensitive data in the client application. ドライバーは、どのクエリ パラメーターが機密データベース列 (Always Encrypted を使用して保護される) に対応するかを自動的に決定し、SQL Server または Azure SQL データベースにデータを渡す前にこれらのパラメーターの値を暗号化します。The driver automatically determines which query parameters correspond to sensitive database columns (protected using Always Encrypted), and encrypts the values of those parameters before passing the data to SQL Server or Azure SQL Database. 同様に、ドライバーは、クエリ結果内の暗号化されたデータベース列から取得されたデータを透過的に暗号化解除します。Similarly, the driver transparently decrypts data retrieved from encrypted database columns in query results. 詳細については、「 Always Encrypted (データベース エンジン)」を参照してください。For more information, see Always Encrypted (Database Engine).

PrerequisitesPrerequisites

データベースで Always Encrypted を構成します。Configure Always Encrypted in your database. この処理には、Always Encrypted キーのプロビジョニング、および選択したデータベース列の暗号化の設定が含まれます。This involves provisioning Always Encrypted keys and setting up encryption for selected database columns. Always Encrypted が構成されたデータベースがない場合は、「 Always Encrypted の作業の開始」の手順に従います。If you do not already have a database with Always Encrypted configured, follow the directions in Getting Started with Always Encrypted. 特に、ご利用のデータベースには、列マスターキー (CMK) 用、列暗号化キー (CEK) 用、およびその CEK を使用して暗号化された 1 つまたは複数の列を含むテーブル用のメタデータ定義を含める必要があります。In particular, your database should contain the metadata definitions for a Column Master Key (CMK), a Column Encryption Key (CEK), and a table containing one or more columns encrypted using that CEK.

ODBC アプリケーションで Always Encrypted を有効にするEnabling Always Encrypted in an ODBC Application

パラメーターの暗号化と、結果セットの暗号化された列の暗号化解除を有効にするには、ColumnEncryption 接続文字列キーワードの値を [有効] に設定するのが最も簡単な方法です。The easiest way to enable both parameter encryption and resultset encrypted column decryption is by setting the value of the ColumnEncryption connection string keyword to Enabled. Always Encrypted を有効にする接続文字列の例を次に示します。The following is an example of a connection string which enables Always Encrypted:

SQLWCHAR *connString = L"Driver={ODBC Driver 13 for SQL Server};Server={myServer};Trusted_Connection=yes;ColumnEncryption=Enabled;";

Always Encrypted は、DSN 構成内で同じキーと値 (接続文字列設定が存在する場合は、それによってオーバーライドされる) を使用して有効にすることも、SQL_COPT_SS_COLUMN_ENCRYPTION 接続前属性を使用してプログラムで有効にすることもできます。Always Encrypted may also be enabled in the DSN configuration, using the same key and value (which will be overridden by the connection string setting, if present), or programmatically with the SQL_COPT_SS_COLUMN_ENCRYPTION pre-connection attribute. それを次のように設定すると、接続文字列または DSN に設定されている値はオーバーライドされます。Setting it this way overrides the value set in the connection string or DSN:

 SQLSetConnectAttr(hdbc, SQL_COPT_SS_COLUMN_ENCRYPTION, (SQLPOINTER)SQL_COLUMN_ENCRYPTION_ENABLE, 0);

接続に対して有効にすると、個々のクエリに合わせて Always Encrypted の動作を調整することができます。Once enabled for the connection, the behavior of Always Encrypted may be adjusted for individual queries. 詳細については、「Always Encrypted のパフォーマンスの影響を制御する」を参照してください。See Controlling the Performance Impact of Always Encrypted below for more information.

暗号化または暗号化解除を正常に行うには、Always Encrypted を有効にするだけでは不十分です。さらに、次のようになっていることを確認する必要があります。Note that enabling Always Encrypted is not sufficient for encryption or decryption to succeed; you also need to make sure that:

  • アプリケーションが、データベース内の Always Encrypted キーに関するメタデータへのアクセスに必要な VIEW ANY COLUMN MASTER KEY DEFINITION および VIEW ANY COLUMN ENCRYPTION KEY DEFINITION データベース権限を持っている。The application has the VIEW ANY COLUMN MASTER KEY DEFINITION and VIEW ANY COLUMN ENCRYPTION KEY DEFINITION database permissions, required to access the metadata about Always Encrypted keys in the database. 詳細については、「データベース権限」を参照してください。For details, see Database Permissions.

  • アプリケーションで、クエリ対象の暗号化された列の CEK を保護する CMK にアクセスできる。The application can access the CMK which protects the CEKs for the queried encrypted columns. このことは、CMK を格納するキーストア プロバイダーに依存します。This is dependent on the keystore provider which stores the CMK. 詳細については、「列マスター キー ストアを操作する」を参照してください。See Working with Column Master Key Stores for more information.

暗号化された列のデータを取得および変更するRetrieving and Modifying Data in Encrypted Columns

接続に対して Always Encrypted を有効にすると、標準の ODBC API (ODBC サンプルコードに関するページまたは「ODBC プログラマー リファレンス」を参照) を使用して、暗号化されたデータベース列内のデータを取得または変更することができます。Once you enable Always Encrypted on a connection, you can use standard ODBC APIs (see ODBC sample code or ODBC Programmer's Reference) to retrieve or modify data in encrypted database columns. ご利用のアプリケーションが必要なデータベース権限を備えていて、列マスター キーにアクセスできると仮定すると、ドライバーによって、暗号化された列をターゲットとするクエリ パラメータが暗号化され、暗号化された列から取得したデータの暗号化が解除されます。これらの動作は列が暗号化されていないかのようにアプリケーションに対して透過的に行われます。Assuming your application has the required database permissions and can access the column master key, the driver will encrypt any query parameters which target encrypted columns and decrypt data retrieved from encrypted columns, behaving transparently to the application as if the columns were not encrypted.

Always Encrypted が有効でない場合、暗号化された列をターゲットとするパラメーターを含むクエリは失敗します。If Always Encrypted is not enabled, queries with parameters which target encrypted columns will fail. 暗号化された列をターゲットとするパラメーターがクエリにない場合は、暗号化された列からデータを取得できます。Data can still be retrieved from encrypted columns, as long as the query has no parameters targeting encrypted columns. ただし、ドライバーによって暗号化の解除は試みられず、アプリケーションでは暗号化されたバイナリ データを (バイト配列として) 受け取ることになります。However, the driver will not attempt any decryption and the application will receive the binary encrypted data (as byte arrays).

次の表は、Always Encrypted が有効かどうかに応じたクエリの動作をまとめたものです。The table below summarizes the behavior of queries, depending on whether Always Encrypted is enabled or not:

クエリの特性Query characteristic Always Encrypted が有効になっており、アプリケーションがキーとキー メタデータにアクセスできるAlways Encrypted is enabled and application can access the keys and key metadata Always Encrypted が有効になっており、アプリケーションがキーまたはキー メタデータにアクセスできないAlways Encrypted is enabled and application cannot access the keys or key metadata Always Encrypted が無効になっているAlways Encrypted is disabled
暗号化された列をターゲットとするパラメーター。Parameters targeting encrypted columns. パラメーター値は透過的に暗号化されます。Parameter values are transparently encrypted. ErrorError ErrorError
暗号化された列をターゲットとするパラメーターを含まない、暗号化された列からのデータの取得。Retrieving data from encrypted columns, without parameters targeting encrypted columns. 暗号化された列の結果は透過的に暗号化解除されます。Results from encrypted columns are transparently decrypted. アプリケーションでは、プレーン テキスト列の値を受け取ります。The application receives plaintext column values. ErrorError 暗号化された列の結果は暗号化解除されません。Results from encrypted columns are not decrypted. アプリケーションは、暗号化された値をバイト配列として受け取ります。The application receives encrypted values as byte arrays.

次の例は、暗号化された列のデータを取得および変更する方法を示しています。The following examples illustrate retrieving and modifying data in encrypted columns. この例では、次のスキーマを持つテーブルを想定しています。The examples assume a table with the following schema. SSN 列と BirthDate 列が暗号化されていることに注意してください。Note that the SSN and BirthDate columns are encrypted.

CREATE TABLE [dbo].[Patients](
 [PatientId] [int] IDENTITY(1,1),
 [SSN] [char](11) COLLATE Latin1_General_BIN2
 ENCRYPTED WITH (ENCRYPTION_TYPE = DETERMINISTIC,
 ALGORITHM = 'AEAD_AES_256_CBC_HMAC_SHA_256',
 COLUMN_ENCRYPTION_KEY = CEK1) NOT NULL,
 [FirstName] [nvarchar](50) NULL,
 [LastName] [nvarchar](50) NULL,
 [BirthDate] [date]
 ENCRYPTED WITH (ENCRYPTION_TYPE = RANDOMIZED,
 ALGORITHM = 'AEAD_AES_256_CBC_HMAC_SHA_256',
 COLUMN_ENCRYPTION_KEY = CEK1) NOT NULL
 PRIMARY KEY CLUSTERED ([PatientId] ASC) ON [PRIMARY] )
 GO

データ挿入の例Data Insertion Example

この例では、Patients テーブルに列を挿入します。This example inserts a row into the Patients table. 次のことを考慮してください。Note the following:

  • このサンプル コードの暗号化に固有のものは何もありません。There is nothing specific to encryption in the sample code. 暗号化された列をターゲットとする SSN および日付パラメータの値が、ドライバーによって自動的に検出されて、暗号化されます。The driver automatically detects and encrypts the values of the SSN and date parameters, which target encrypted columns. これにより、アプリケーションに対して暗号化が透過的に実行されます。This makes encryption transparent to the application.

  • 暗号化された列を含め、データベース列に挿入された値は、バインドされたパラメーターとして渡されます (「SQLBindParameter 関数」を参照してください)。The values inserted into database columns, including the encrypted columns, are passed as bound parameters (see SQLBindParameter Function). 暗号化されていない列に値を送信する場合、パラメーターの使用は省略可能です (ただし、SQL インジェクションを防ぐのに役立つので、強くお勧めします) が、暗号化された列をターゲットとする値に対しては必須です。While using parameters is optional when sending values to non-encrypted columns (although it is highly recommended because it helps prevent SQL injection), it is required for values targeting encrypted columns. SSN 列または BirthDate 列に挿入された値がクエリ ステートメントに埋め込まれたリテラルとして渡された場合、ドライバーではクエリ内のリテラルの暗号化または処理が試行されないため、クエリは失敗します。If the values inserted in the SSN or BirthDate columns were passed as literals embedded in the query statement, the query would fail because the driver does not attempt to encrypt or otherwise process literals in queries. その結果、サーバーはこれらの値を、暗号化された列と互換性がないと見なして拒否します。As a result, the server would reject them as incompatible with the encrypted columns.

  • SSN 列に挿入されるパラメーターの SQL 型は SQL_CHAR (char SQL Server データ型にマップされる) に設定されます (rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 11, 0, (SQLPOINTER)SSN, 0, &cbSSN);)。The SQL type of the parameter inserted into the SSN column is set to SQL_CHAR, which maps to the char SQL Server data type (rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 11, 0, (SQLPOINTER)SSN, 0, &cbSSN);). パラメーターの型が SQL_WCHAR (nchar にマップされる) に設定された場合、クエリは失敗します。暗号化された nchar 値から、暗号化された char 値へのサーバー側変換が Always Encrypted でサポートされていないためです。If the type of the parameter was set to SQL_WCHAR, which maps to nchar, the query would fail, as Always Encrypted does not support server-side conversions from encrypted nchar values to encrypted char values. データ型のマッピングについては、「ODBC プログラマー リファレンス - 付録 D: データ型」を参照してください。See ODBC Programmer's Reference -- Appendix D: Data Types for information about the data type mappings.

    SQL_DATE_STRUCT date;
    SQLLEN cbdate;   // size of date structure  

    SQLCHAR SSN[12];
    strcpy_s((char*)SSN, _countof(SSN), "795-73-9838");

    SQLWCHAR* firstName = L"Catherine";
    SQLWCHAR* lastName = L"Abel";
    SQLINTEGER cbSSN = SQL_NTS, cbFirstName = SQL_NTS, cbLastName = SQL_NTS;

    // Initialize the date structure  
    date.day = 10;
    date.month = 9;
    date.year = 1996;

    // Size of structures   
    cbdate = sizeof(SQL_DATE_STRUCT);

    SQLRETURN rc = 0;

    string queryText = "INSERT INTO [dbo].[Patients] ([SSN], [FirstName], [LastName], [BirthDate]) VALUES (?, ?, ?, ?) ";

    rc = SQLPrepare(hstmt, (SQLCHAR *)queryText.c_str(), SQL_NTS);

    //SSN
    rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 11, 0, (SQLPOINTER)SSN, 0, &cbSSN);
    //FirstName
    rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_WCHAR, SQL_WCHAR, 50, 0, (SQLPOINTER)firstName, 0, &cbFirstName);
    //LastName
    rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_WCHAR, SQL_WCHAR, 50, 0, (SQLPOINTER)lastName, 0, &cbLastName);
    //BirthDate
    rc = SQLBindParameter(hstmt, 4, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TYPE_DATE, 10, 0, (SQLPOINTER)&date, 0, &cbdate);

    rc = SQLExecute(hstmt);

プレーンテキスト データの取得の例Plaintext Data Retrieval Example

次の例は、暗号化された値に基づいてデータをフィルター処理し、暗号化された列からプレーンテキスト データを取得する方法を示しています。The following example demonstrates filtering data based on encrypted values, and retrieving plaintext data from encrypted columns. 次のことを考慮してください。Note the following:

  • SQLBindParameter を使用して SSN 列に対してフィルター処理するために WHERE 句で使用される値は、サーバーに送信する前にドライバーが透過的に暗号化できるように、パラメーターとして渡す必要があります。The value used in the WHERE clause to filter on the SSN column needs to be passed using SQLBindParameter, so that the driver can transparently encrypt it before sending it to the server.

  • ドライバーが SSN 列と BirthDate 列から取得されたデータを透過的に暗号化解除するので、プログラムで出力される値はすべてプレーンテキストになります。All values printed by the program will be in plaintext, since the driver will transparently decrypt the data retrieved from the SSN and BirthDate columns.

注意

暗号化が決定論的である場合にのみ、クエリでは、暗号化された列に対して等価比較を実行できます。Queries can perform equality comparisons on encrypted columns only if the encryption is deterministic. 詳細については、「明確な暗号化またはランダム化された暗号化の選択」を参照してください。For more information, see Selecting Deterministic or Randomized encryption.

SQLCHAR SSN[12];
strcpy_s((char*)SSN, _countof(SSN), "795-73-9838");

SQLWCHAR* firstName = L"Catherine";
SQLWCHAR* lastName = L"Abel";
SQLINTEGER cbSSN = SQL_NTS, cbFirstName = SQL_NTS, cbLastName = SQL_NTS;

SQLRETURN rc = 0;
string empty = "";
string queryText = "SELECT [SSN], [FirstName], [LastName], [BirthDate] " + empty +
    "FROM  [dbo].[Patients]" +
    "WHERE " +
    "[SSN] = ? ";

rc = SQLPrepare(hstmt, (SQLCHAR *)queryText.c_str(), SQL_NTS);

//SSN
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 11, 0, (SQLPOINTER)SSN, 0, &cbSSN);

rc = SQLExecute(hstmt);
HandleDiagnosticRecord(hstmt, SQL_HANDLE_STMT, rc);

SQL_DATE_STRUCT dateVal;
SQLWCHAR firstNameVal[50];
SQLWCHAR lastNameVal[50];
SQLCHAR SSNVal[12];
SQLLEN cbdate;   // size of date structure  

int rowcount = 0;
while (SQL_SUCCEEDED(SQLFetch(hstmt)))
{
    rowcount++;
    SQLGetData(hstmt, 1, SQL_C_CHAR, &SSNVal, 11, &cbSSN);
    SQLGetData(hstmt, 2, SQL_C_WCHAR, &firstNameVal, 50, &cbFirstName);
    SQLGetData(hstmt, 3, SQL_C_WCHAR, &lastNameVal, 50, &cbLastName);
    SQLGetData(hstmt, 4, SQL_C_TYPE_DATE, &dateVal, 10, &cbdate);        
}

暗号化テキスト データの取得の例Ciphertext Data Retrieval Example

Always Encrypted が有効になっていない場合でも、暗号化された列をターゲットとするパラメーターがクエリになければ、クエリでは、暗号化された列からデータを取得できます。If Always Encrypted is not enabled, a query can still retrieve data from encrypted columns, as long as the query has no parameters targeting encrypted columns.

次の例は、暗号化された列から暗号化されたバイナリ データを取得する方法を示しています。The following example illustrates retrieving binary encrypted data from encrypted columns. 次のことを考慮してください。Note the following:

  • 接続文字列で Always Encrypted が有効になっていないので、クエリは、SSN と BirthDate の暗号化された値をバイト配列として返します (プログラムによって値が文字列に変換されます)。As Always Encrypted is not enabled in the connection string, the query will return encrypted values of SSN and BirthDate as byte arrays (the program converts the values to strings).
  • Always Encrypted が無効の状態で、暗号化された列からデータを取得するクエリは、暗号化された列をターゲットとするパラメーターがない場合に限り、パラメーターを含むことができます。A query retrieving data from encrypted columns with Always Encrypted disabled can have parameters, as long as none of the parameters target an encrypted column. 上記のクエリは、データベースで暗号化されない LastName によってフィルター処理を行います。The above query filters by LastName, which is not encrypted in the database. クエリが SSN または BirthDate によってフィルター処理を行った場合、クエリは失敗します。If the query filtered by SSN or BirthDate, the query would fail.
SQLCHAR SSN[12];
strcpy_s((char*)SSN, _countof(SSN), "795-73-9838");

SQLWCHAR* firstName = L"Catherine";
SQLWCHAR* lastName = L"Abel";
SQLINTEGER cbSSN = SQL_NTS, cbFirstName = SQL_NTS, cbLastName = SQL_NTS;

SQLRETURN rc = 0;
string empty = "";
string queryText = "SELECT [SSN], [FirstName], [LastName], [BirthDate] " + empty +
    "FROM  [dbo].[Patients]" +
    "WHERE " +
    "[LastName] = ?";

rc = SQLPrepare(hstmt, (SQLCHAR *)queryText.c_str(), SQL_NTS);

//LastName
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_WCHAR, SQL_WCHAR, 50, 0, (SQLPOINTER)lastName, 0, &cbLastName);

rc = SQLExecute(hstmt);
HandleDiagnosticRecord(hstmt, SQL_HANDLE_STMT, rc);

SQL_DATE_STRUCT dateVal;
SQLWCHAR firstNameVal[50];
SQLWCHAR lastNameVal[50];
SQLCHAR SSNVal[12];
SQLLEN cbdate;   // size of date structure  

int rowcount = 0;
while (SQL_SUCCEEDED(SQLFetch(hstmt)))
{
    rowcount++;
    SQLGetData(hstmt, 1, SQL_C_CHAR, &SSNVal, 11, &cbSSN);
    SQLGetData(hstmt, 2, SQL_C_WCHAR, &firstNameVal, 50, &cbFirstName);
    SQLGetData(hstmt, 3, SQL_C_WCHAR, &lastNameVal, 50, &cbLastName);
    SQLGetData(hstmt, 4, SQL_C_TYPE_DATE, &dateVal, 10, &cbdate);        
}

暗号化された列をクエリする際の一般的な問題を回避するAvoiding Common Problems when Querying Encrypted Columns

ここでは、暗号化された列を ODBC アプリケーションからクエリする際のエラーの一般的なカテゴリと、その対処方法に関するいくつかのガイドラインを示します。This section describes common categories of errors when querying encrypted columns from ODBC applications and a few guidelines on how to avoid them.

サポートされていないデータ型の変換エラーUnsupported data type conversion errors

Always Encrypted では、暗号化されたデータ型に対するいくつかの変換がサポートされています。Always Encrypted supports few conversions for encrypted data types. サポートされている型の変換の詳細な一覧については、「Always Encrypted (データベース エンジン)」を参照してください。See Always Encrypted (Database Engine) for the detailed list of supported type conversions. データ型変換のエラーを回避するには、暗号化された列をターゲットとするパラメーターで SQLBindParameter を使用する場合、必ず次の点に注意してください。To avoid data type conversion errors, make sure that you observe the following points when using SQLBindParameter with parameters targeting encrypted columns:

  • パラメーターの SQL 型については、ターゲットとする列の型とまったく同じであるか、または SQL 型から列の型への変換がサポートされている。The SQL type of the parameter is either exactly the same as the type of the targeted column, or the conversion from the SQL type to the type of the column is supported.

  • decimalnumeric の SQL Server データ型の列をターゲットとするパラメーターの有効桁数と小数点以下桁数が、ターゲット列に対して構成された有効桁数と小数点と同じである。The precision and scale of parameters targeting columns of the decimal and numeric SQL Server data types is the same as the precision and scale configured for the target column.

  • ターゲット列を変更するクエリで、datetime2datetimeoffset、または time の SQL Server データ型の列をターゲットとするパラメーターの有効桁数が、ターゲット列の有効桁数以下である。The precision of parameters targeting columns of datetime2, datetimeoffset, or time SQL Server data types is not greater than the precision for the target column, in queries that modify the target column.

暗号化された値の代わりにプレーンテキストを渡すことによるエラーErrors due to passing plaintext instead of encrypted values

暗号化された列をターゲットとする値はいずれも、サーバーに送信する前に暗号化する必要があります。Any value that targets an encrypted column needs to be encrypted before being sent to the server. 暗号化された列でプレーンテキスト値の挿入、変更、フィルター処理を行おうとすると、エラーになります。An attempt to insert, modify, or filter by a plaintext value on an encrypted column will result in an error. このようなエラーを防ぐには、次のことを確認してください。To prevent such errors, make sure that:

  • Always Encrypted が有効にされていること (特定の接続の SQL_COPT_SS_COLUMN_ENCRYPTION 接続属性、または特定のステートメントの SQL_SOPT_SS_COLUMN_ENCRYPTION ステートメント属性を設定して接続する前に DSN の接続文字列で)。Always Encrypted is enabled (in the DSN, the connection string, before connecting by setting the SQL_COPT_SS_COLUMN_ENCRYPTION connection attribute for a specific connection, or the SQL_SOPT_SS_COLUMN_ENCRYPTION statement attribute for a specific statement).

  • SQLBindParameter を使用して、暗号化された列をターゲットとするデータを送信すること。You use SQLBindParameter to send data targeting encrypted columns. 次の例は、SQLBindParameter に引数としてリテラルを渡す代わりに、暗号化された列 (SSN) でリテラル/定数によって不正なフィルター処理を行うクエリを示しています。The example below shows a query that incorrectly filters by a literal/constant on an encrypted column (SSN), instead of passing the literal as an argument to SQLBindParameter.

string queryText = "SELECT [SSN], [FirstName], [LastName], [BirthDate] FROM [dbo].[Patients] WHERE SSN='795-73-9838'";

SQLSetPos および SQLMoreResults を使用する際の注意事項Precautions when using SQLSetPos and SQLMoreResults

SQLSetPosSQLSetPos

SQLSetPos API を使用すると、SQLBindCol にバインドされ、行データが事前に取り込まれているバッファーを使用して結果セット内の行をアプリケーションで更新することができます。The SQLSetPos API allows an application to update rows in a resultset using buffers that were bound with SQLBindCol and into which row data was previously fetched. 暗号化された固定長型の非対称の埋め込み動作が原因で、これらの列のデータは、行内の他の列に対して更新が行われている間に、予期せずに変更される可能性があります。Due to the asymmetric padding behavior of encrypted fixed-length types, it is possible to unexpectedly alter the data of these columns while performing updates on other columns in the row. AE では、固定長文字の値は、バッファー サイズより小さい場合に埋め込まれます。With AE, fixed length character values will be padded if the value is smaller than the buffer size.

この動作を軽減するには、SQLBulkOperations の一環として更新されない列、およびカーソル ベースの更新に SQLSetPos を使用する場合に更新されない列を無視するために、SQL_COLUMN_IGNOREフラグを使用します。To mitigate this behavior, use the SQL_COLUMN_IGNORE flag to ignore columns that will not be updated as part of SQLBulkOperations and when using SQLSetPos for cursor based updates. アプリケーションによって直接変更されない列はすべて無視する必要があります。パフォーマンス上の理由と、実際の (DB) サイズより小さいバッファーにバインドされている列の切り捨てを回避するための両面からそのようにします。All columns that are not being directly modified by the application should be ignored, both for performance and to avoid truncation of columns that are bound to a buffer smaller than their actual (DB) size. 詳細については、SQLSetPos 関数のリファレンスを参照してください。For more information, see SQLSetPos Function reference.

SQLMoreResults と SQLDescribeColSQLMoreResults & SQLDescribeCol

アプリケーション プログラムでは、準備されたステートメント内の列のメタデータを返すために、SQLDescribeCol を呼び出す場合があります。Application programs may call SQLDescribeCol to return metadata about columns in prepared statements. Always Encrypted が有効にされているとき、SQLDescribeCol を呼び出す "前に" SQLMoreResults を呼び出すと、sp_describe_first_result_set が呼び出されるため、暗号化された列のプレーンテキスト メタデータは正しく返されません。When Always Encrypted is enabled, calling SQLMoreResults before calling SQLDescribeCol causes sp_describe_first_result_set to be called, which does not correctly return the plaintext metadata for encrypted columns. この問題を回避するには、SQLMoreResults を呼び出す "前に" 準備されたステートメント上で SQLDescribeCol を呼び出します。To avoid this issue, call SQLDescribeCol on prepared statements before calling SQLMoreResults.

Always Encrypted のパフォーマンスの影響を制御するControlling the Performance Impact of Always Encrypted

Always Encrypted はクライアント側暗号化テクノロジであるため、ほとんどのパフォーマンス オーバーヘッドは、データベースではなくクライアント側で発生します。Because Always Encrypted is a client-side encryption technology, most of the performance overhead is observed on the client side, not in the database. 暗号化および暗号化解除の操作のコストとは別に、クライアント側のパフォーマンス オーバーヘッドのその他の原因を次に示します。Apart from the cost of encryption and decryption operations, the other sources of performance overhead on the client side are:

  • クエリ パラメーターのメタデータを取得するためのデータベースへの追加のラウンド トリップ。Additional round trips to the database to retrieve metadata for query parameters.

  • 列マスター キーにアクセスするための列マスター キー ストアの呼び出し。Calls to a column master key store to access a column master key.

このセクションでは、ODBC Driver for SQL Server の組み込みのパフォーマンス最適化、および上記の 2 つの要因によるパフォーマンスへの影響を制御する方法について説明します。This section describes the built-in performance optimizations in the ODBC Driver for SQL Server and how you can control the impact of the above two factors on performance.

クエリ パラメーターのメタデータを取得するためのラウンド トリップを制御するControlling Round-trips to Retrieve Metadata for Query Parameters

既定では、接続に対して Always Encrypted が有効になっている場合、ドライバーは、各パラメーター化クエリに対して sys.sp_describe_parameter_encryption を呼び出し、クエリ ステートメント (パラメーター値を除く) を SQL Server に渡します。If Always Encrypted is enabled for a connection, the driver will, by default, call sys.sp_describe_parameter_encryption for each parameterized query, passing the query statement (without any parameter values) to SQL Server. このストアド プロシージャでは、クエリ ステートメントを分析して、パラメーターを暗号化する必要があるかどうかが判断され、必要がある場合は、ドライバーでパラメーターを暗号化できるようにするため、パラメーターごとに暗号化関連の情報が返されます。This stored procedure analyzes the query statement to find out if any parameters need to be encrypted, and if so, returns the encryption-related information for each parameter to allow the driver to encrypt them. 上記の動作により、クライアント アプリケーションに対する次のような高度な透明性が確保されます: 暗号化された列をターゲットとする値がパラメーターでドライバーに渡される限り、アプリケーション (およびアプリケーション開発者) は、暗号化された列にどのクエリがアクセスするかを認識する必要はありません。The above behavior ensures a high-level of transparency to the client application: The application (and the application developer) does not need to be aware of which queries access encrypted columns, as long as the values targeting encrypted columns are passed to the driver in parameters.

ステートメントごとの Always Encrypted 動作Per-Statement Always Encrypted Behavior

パラメーター化クエリに対して暗号化メタデータを取得することによるパフォーマンスへの影響を制御するには、接続に対して Always Encrypted 動作が有効にされている場合、個々のクエリに対する Always Encrypted 動作を変更することができます。To control the performance impact of retrieving encryption metadata for parameterized queries, you can alter the Always Encrypted behavior for individual queries if it has been enabled on the connection. これにより、暗号化された列をターゲットとするパラメーターを含むことがわかっているクエリに対してのみ sys.sp_describe_parameter_encryption が確実に呼び出されるようにすることができます。This way, you can ensure that sys.sp_describe_parameter_encryption is invoked only for queries that you know have parameters targeting encrypted columns. ただし、これにより、暗号化の透明度が損なわれることに注意してください。データベース内の別の列を暗号化する場合は、スキーマの変更に合わせてアプリケーション コードの変更が必要になる可能性があります。Note, however, that by doing so, you reduce transparency of encryption: if you encrypt additional columns in your database, you may need to change the code of your application to align it with the schema changes.

ステートメントの Always Encrypted 動作を制御するには、SQLSetStmtAttr を呼び出して、SQL_SOPT_SS_COLUMN_ENCRYPTION ステートメント属性を次のいずれかの値に設定します。To control the Always Encrypted behavior of a statement, call SQLSetStmtAttr to set the SQL_SOPT_SS_COLUMN_ENCRYPTION statement attribute to one of the following values:

[値]Value [説明]Description
SQL_CE_DISABLED (0)SQL_CE_DISABLED (0) ステートメントに対して Always Encrypted は無効にされますAlways Encrypted is disabled for the statement
SQL_CE_RESULTSETONLY (1)SQL_CE_RESULTSETONLY (1) 暗号化解除のみです。Decryption Only. 結果セットと戻り値は暗号化解除され、パラメーターは暗号化されませんResultsets and return values are decrypted, and parameters are not encrypted
SQL_CE_ENABLED (3)SQL_CE_ENABLED (3) Always Encrypted は有効にされ、パラメーターと結果の両方に使用されます。Always Encrypted is enabled and used for both parameters and results

Always Encrypted を有効にした接続から作成された新しいステートメント ハンドルは、既定では SQL_CE_ENABLED になります。New statement handles created from a connection with Always Encrypted enabled default to SQL_CE_ENABLED. Always Encrypted を無効にした接続から作成された新しいステートメント ハンドルは、既定では SQL_CE_DISABLED になります (そして、それらのハンドルに対して Always Encrypted を有効にすることはできません)。Those created from a connection with it disabled default to SQL_CE_DISABLED (and it is not possible to enable Always Encrypted on them.)

クライアント アプリケーションのクエリのほとんどが暗号化された列にアクセスする場合は、次の操作をお勧めします。If most of the queries of a client application access encrypted columns, the following is recommended:

  • ColumnEncryption 接続文字列キーワードを Enabled に設定します。Set the ColumnEncryption connection string keyword to Enabled.

  • 暗号化されたどの列にもアクセスしないステートメント上で、SQL_SOPT_SS_COLUMN_ENCRYPTION 属性を SQL_CE_DISABLED に設定します。Set the SQL_SOPT_SS_COLUMN_ENCRYPTION attribute to SQL_CE_DISABLED on statements which do not access any encrypted columns. これにより、sys.sp_describe_parameter_encryption の呼び出しと、結果セット内の値の暗号化解除の試みとが両方とも無効にされます。This will disable both calling sys.sp_describe_parameter_encryption as well as attempts to decrypt any values in the result set.

  • 暗号化を必要とするパラメーターは何も含まれていないものの、暗号化された列からデータを取得するステートメント上で、SQL_SOPT_SS_COLUMN_ENCRYPTION 属性を SQL_CE_RESULTSETONLY に設定します。Set the SQL_SOPT_SS_COLUMN_ENCRYPTION attribute to SQL_CE_RESULTSETONLY on statements which do not have any parameters requiring encryption, but retrieve data from encrypted columns. これにより、sys.sp_describe_parameter_encryption の呼び出しとパラメーターの暗号化が無効にされます。This will disable calling sys.sp_describe_parameter_encryption and parameter encryption. 暗号化された列を含む結果は、引き続き暗号化が解除されたままです。Results containing encrypted columns will continue to be decrypted.

Always Encrypted のセキュリティ設定Always Encrypted Security Settings

列の暗号化の強制Force Column Encryption

パラメーターの暗号化を強制するには、SQLSetDescField 関数を呼び出して、SQL_CA_SS_FORCE_ENCRYPT 実装パラメーター記述子 (IPD) フィールドを設定します。To enforce the encryption of a parameter, set the SQL_CA_SS_FORCE_ENCRYPT implementation parameter descriptor (IPD) field through a call to the SQLSetDescField function. 0 以外の値を使用すると、関連付けられたパラメーターに対する暗号化メタデータが返されない場合にドライバーからはエラーが返されます。A non-zero value causes the driver to return an error when no encryption metadata is returned for the associated parameter.

SQLHDESC ipd;
SQLGetStmtAttr(hStmt, SQL_ATTR_IMP_PARAM_DESC, &ipd, 0, 0);
SQLSetDescField(ipd, paramNum, SQL_CA_SS_FORCE_ENCRYPT, (SQLPOINTER)TRUE, SQL_IS_SMALLINT);   

パラメーターの暗号化が不要であることが SQL Server からドライバーに通知された場合、このパラメーターを使用するクエリは失敗します。If SQL Server informs the driver that the parameter does not need to be encrypted, queries using that parameter will fail. 攻撃を受けた SQL Server がクライアントに不正な暗号化メタデータを提供すると、データ漏えいが引き起こされる可能性がありますが、これにより、そのようなセキュリティ攻撃に対する保護を強化します。This provides additional protection against security attacks which involve a compromised SQL Server providing incorrect encryption metadata to the client, which may lead to data disclosure.

列暗号化キーのキャッシュColumn Encryption Key Caching

列暗号化キーを暗号化解除するための列マスター キー ストアの呼び出し回数を減らすために、ドライバーではプレーンテキスト CEK がメモリにキャッシュされます。To reduce the number of calls to a column master key store to decrypt column encryption keys, the driver caches the plaintext CEKs in memory. CEK キャッシュはドライバに対してグローバルであり、どの接続にも関連付けられていません。The CEK cache is global to the driver and not associated with any one connection. ECEK をデータベース メタデータから受け取った後、ドライバーでは、まず、キャッシュ内の暗号化されたキー値に対応するプレーンテキスト CEK の検索が試みられます。After receiving the ECEK from database metadata, the driver first tries to find the plaintext CEK corresponding to the encrypted key value in the cache. ドライバーでは、キャッシュ内で対応するプレーンテキスト CEK が見つからない場合にのみ、CMK を含むキー ストアが呼び出されます。The driver calls the key store containing the CMK only if it cannot find the corresponding plaintext CEK in the cache.

注意

ODBC Driver for SQL Server では、2 時間のタイムアウト後にキャッシュ内のエントリが削除されます。In the ODBC Driver for SQL Server, the entries in the cache are evicted after a two hour timeout. つまり、ECEK が指定されている場合、ドライバーはアプリケーションの有効期間中または 2 時間間隔のうち、どちらか短い方の期間中に 1 回だけキー ストアと交信します。This means that for a given ECEK, the driver contacts the key store only once during the lifetime of the application or every two hours, whichever is less.

ODBC Driver 17.1 for SQL Server 以降、CEK がキャッシュ内に保持される秒数を指定する SQL_COPT_SS_CEKCACHETTL 接続属性を使用して CEK キャッシュ タイムアウトを調整することができます。Starting with the ODBC Driver 17.1 for SQL Server, the CEK cache timeout can be adjusted using the SQL_COPT_SS_CEKCACHETTL connection attribute, which specifies the number of seconds a CEK will remain in the cache. キャッシュにはグローバルな性質があるため、この属性はドライバーに対して有効などの接続ハンドルからも調整できます。Due to the global nature of the cache, this attribute can be adjusted from any connection handle valid for the driver. キャッシュ TTL を小さくすると、既存の CEK も新しい TTL を超える場合は削除されます。When the cache TTL is decreased, existing CEKs which would exceed the new TTL are also evicted. 0 の場合、CEK はキャッシュされません。If it is 0, no CEKs are cached.

信頼されたキー パスTrusted Key Paths

ODBC Driver 17.1 for SQL Server 以降では、SQL_COPT_SS_TRUSTEDCMKPATHS 接続属性を使用すると、指定された CMK リスト (キー パスで識別された) のみを Always Encrypted 操作で使用するようにアプリケーションから要求できるようになります。Starting with the ODBC Driver 17.1 for SQL Server, the SQL_COPT_SS_TRUSTEDCMKPATHS connection attribute allows an application to require that Always Encrypted operations only use a specified list of CMKs, identified by their key paths. 既定では、この属性は NULL です。つまり、ドライバーでは任意のキー パスが受け入れられます。By default, this attribute is NULL, which means that the driver accepts any key path. この機能を使用するには、許可されたキー パスを一覧する null 区切り null 終了のワイド文字列を指すように SQL_COPT_SS_TRUSTEDCMKPATHS を設定します。To use this feature, set SQL_COPT_SS_TRUSTEDCMKPATHS to point to a null-delimited, null-terminated wide-character string which lists the allowed key path(s). この属性が指すメモリは、それが設定されている接続ハンドルを使用した暗号化操作または暗号化解除操作中に、有効な状態に維持される必要があります。その上で、サーバー メタデータによって指定された CMK パスはこのリスト内で大文字と小文字が区別されているかどうかがドライバーによって確認されます。The memory pointed to by this attribute must remain valid during encryption or decryption operations using the connection handle on which it is set --- upon which the driver will check if the CMK path as specified by the server metadata is case-insensitively in this list. CMK パスがリストにない場合、操作は失敗します。If the CMK path is not in the list, the operation fails. アプリケーションでは、この属性が指すメモリの内容を変更することで、属性を再設定することなく、その信頼された CMK リストを変更することができます。The application can change the contents of memory this attribute points at, to change its list of trusted CMKs, without setting the attribute again.

列マスター キー ストアを操作するWorking with Column Master Key Stores

データを暗号化または暗号化解除する場合、ターゲット列に対して構成された CEK がドライバーによって取得される必要があります。To encrypt or decrypt data, the driver needs to obtain a CEK that is configured for the target column. CEK は、データベース メタデータ内に暗号化された形式 (ECEK) で格納されます。CEKs are stored in encrypted form (ECEKs) in the database metadata. 各 CEK には、暗号化する際に使用された対応する CMK があります。Each CEK has a corresponding CMK that was used to encrypt it. データベース メタデータに CMK 自体は格納されません。これにはキーストアの名前と、キーストアが CMK を検索するために使用できる情報のみが含まれます。The database metadata does not store the CMK itself; it only contains the name of the keystore and information which the keystore can use to locate the CMK.

ECEK のプレーンテキスト値を取得するために、ドライバーでは、まず、CEK とそれに対応する CMK の両方についてメタデータが取得されます。次に、この情報を使用して CMK を含むキーストアと交信し、ECEK の暗号化を解除するように要求が出されます。To obtain the plaintext value of an ECEK, the driver first obtains the metadata about both the CEK and its corresponding CMK, and then it uses this information to contact the keystore containing the CMK and requests it to decrypt the ECEK. ドライバーとキーストアの通信は、キーストア プロバイダーを使用して行われます。The driver communicates with a keystore using a keystore provider.

組み込みのキーストア プロバイダーBuilt-in Keystore Providers

ODBC Driver for SQL Server には、次の組み込みのキーストア プロバイダーが付属しています。The ODBC Driver for SQL Server comes with the following built-in keystore providers:

[オブジェクト名]Name [説明]Description プロバイダー (メタデータ) 名Provider (metadata) name 可用性Availability
Azure Key VaultAzure Key Vault Azure Key Vault に CMK を格納しますStores CMKs in an Azure Key Vault AZURE_KEY_VAULT Windows、macOS、LinuxWindows, macOS, Linux
Windows 証明書ストアWindows Certificate Store Windows キーストアに CMK をローカルに保存しますStores CMKs locally in the Windows keystore MSSQL_CERTIFICATE_STORE WindowsWindows
  • ユーザー (またはデータベース管理者) は、列マスター キーのメタデータで構成されているプロバイダー名が正しいこと、および列マスター キー パスが、特定のプロバイダーに対するキー パス形式に準拠していることを確認する必要があります。You (or your DBA) need to make sure that the provider name, configured in the column master key metadata, is correct and the column master key path complies with the key path format for the given provider. CREATE COLUMN MASTER KEY (Transact-SQL) ステートメントを発行した際に有効なプロバイダー名とキー パスを自動的に生成する、SQL Server Management Studio などのツールを使用してキーを構成することをお勧めします。It is recommended that you configure the keys using tools such as SQL Server Management Studio, which automatically generates the valid provider names and key paths when issuing the CREATE COLUMN MASTER KEY (Transact-SQL) statement.

  • アプリケーションがキー ストア内のキーにアクセスできることを確認する必要があります。You need to ensure your application can access the key in the keystore. これには、キーストアに応じてキーまたはキー ストアへのアクセスをアプリケーションに許可したり、その他のキー ストア固有の構成手順を行ったりするプロセスが含まれる場合があります。This may involve granting your application access to the key and/or the keystore, depending on the keystore, or performing other keystore-specific configuration steps. たとえば、Azure Key Vault にアクセスするには、正しい資格情報をキーストアに提供する必要があります。For example, to access an Azure Key Vault, you need to provide the correct credentials to the keystore.

Azure Key Vault プロバイダーを使用するUsing the Azure Key Vault Provider

Azure Key Vault は、特にアプリケーションが Azure でホストされている場合、Always Encrypted の列マスター キーの格納と管理に便利なオプションです。Azure Key Vault is a convenient option to store and manage column master keys for Always Encrypted (especially if your applications are hosted in Azure). Linux、macOS、および Windows 向けの ODBC Driver for SQL Server には、Azure Key Vault 用の組み込みの列マスター キーストア プロバイダーが含まれています。The ODBC Driver for SQL Server on Linux, macOS, and Windows includes a built-in column master key store provider for Azure Key Vault. Always Encrypted に対して Azure Key Vault を構成する方法の詳細については、Azure Key Vault の操作手順Key Vault の概要、および Azure Key Vault での列マスター キーの作成に関するページを参照してください。See Azure Key Vault - Step by Step, Getting Started with Key Vault, and Creating Column Master Keys in Azure Key Vault for more information on configuring an Azure Key Vault for Always Encrypted.

注意

Linux および macOS 用のドライバー バージョン 17.2 以降の場合、libcurl は、このプロバイダーを使用する上で必要ですが、明示的な依存関係にはありません。ドライバーを使用した他の操作ではそれを必要としないからです。On Linux and macOS, for driver version 17.2 and later, libcurl is required to use this provider, but is not an explicit dependency since other operations with the driver do not require it. libcurl に関するエラーが発生する場合は、それがインストールされていることを確認してください。If you encounter an error regarding libcurl, ensure it is installed.

ドライバーでは、次の資格情報の種類を使用して Azure Key Vault への認証がサポートされます。The driver supports authenticating to Azure Key Vault using the following credential types:

  • ユーザー名/パスワード - この方法では、資格情報は Azure Active Directory ユーザーの名前とそのパスワードです。Username/Password - with this method, the credentials are the name of an Azure Active Directory user and its password.

  • クライアント ID /シークレット - この方法では、資格情報はアプリケーションクライアント ID とアプリケーション シークレットです。Client ID/Secret - with this method, the credentials are an application client ID and an application secret.

ドライバーが AKV に格納されている CMK を列暗号化に使用できるようにするには、次の接続文字列限定のキーワードを使用します。To allow the driver to use CMKs stored in AKV for column encryption, use the following connection-string-only keywords:

[資格情報の種類]Credential Type KeyStoreAuthentication KeyStorePrincipalId KeyStoreSecret
ユーザー名/パスワードUsername/password KeyVaultPassword ユーザー プリンシパル名User Principal Name パスワードPassword
クライアント ID/シークレットClient ID/secret KeyVaultClientSecret クライアント IDClient ID シークレットSecret

接続文字列の例Example Connection Strings

次の接続文字列は、2 種類の資格情報を使用して Azure Key Vault に対して認証する方法を示しています。The following connection strings show how to authenticate to Azure Key Vault with the two credential types:

クライアント ID/シークレット:ClientID/Secret:

DRIVER=ODBC Driver 13 for SQL Server;SERVER=myServer;Trusted_Connection=Yes;DATABASE=myDB;ColumnEncryption=Enabled;KeyStoreAuthentication=KeyVaultClientSecret;KeyStorePrincipalId=<clientId>;KeyStoreSecret=<secret>

ユーザー名/パスワード:Username/Password:

DRIVER=ODBC Driver 13 for SQL Server;SERVER=myServer;Trusted_Connection=Yes;DATABASE=myDB;ColumnEncryption=Enabled;KeyStoreAuthentication=KeyVaultPassword;KeyStorePrincipalId=<username>;KeyStoreSecret=<password>

CMK ストレージで AKV を使用する場合、ODBC アプリケーションに他の変更を加える必要はありません。No other ODBC application changes are required to use AKV for CMK storage.

Windows 証明書ストア プロバイダーの使用Using the Windows Certificate Store Provider

Windows 用の ODBC Driver for SQL Server には、MSSQL_CERTIFICATE_STORE と呼ばれる Windows 証明書ストア用の組み込みの列マスター キー ストア プロバイダーが含まれていますThe ODBC Driver for SQL Server on Windows includes a built-in column master key store provider for the Windows Certificate Store, named MSSQL_CERTIFICATE_STORE. (このプロバイダーは macOS または Linux では使用できません)。このプロバイダーを使用すると、CMK はクライアント コンピューター上にローカルに格納され、ドライバーでそれを使用するためにアプリケーションで追加の構成を行う必要はありません。(This provider is not available on macOS or Linux.) With this provider, the CMK is stored locally on the client machine and no additional configuration by the application is necessary to use it with the driver. ただし、アプリケーションには、ストア内の証明書とその秘密キーへのアクセス権が必要です。However, the application must have access to the certificate and its private key in the store. 詳しくは、「列マスター キーを作成して保存する (Always Encrypted)」をご覧ください。See Create and Store Column Master Keys (Always Encrypted) for more information.

カスタム キーストア プロバイダーの使用Using Custom Keystore Providers

ODBC Driver for SQL Server では、CEKeystoreProvider インターフェイスを使用したカスタムのサードパーティ製キーストア プロバイダーもサポートされています。The ODBC Driver for SQL Server also supports custom third-party keystore providers using the CEKeystoreProvider interface. これにより、ドライバーが暗号化された列にアクセスする場合にキーストア プロバイダーを使用できるように、アプリケーションでキーストア プロバイダーの読み込み、クエリ、および構成を行うことができます。This allows an application to load, query, and configure keystore providers so that they can be used by the driver to access encrypted columns. アプリケーションはまた、SQL Server に格納するための CEK を暗号化し、ODBC で暗号化された列にアクセスする以外のタスクを実行するために、キーストア プロバイダーと直接やりとりする場合もあります。詳細については、「カスタム キーストア プロバイダー」を参照してください。Applications may also directly interact with a keystore provider in order to encrypt CEKs for storage in SQL Server and perform tasks beyond accessing encrypted columns with ODBC; for more information, see Custom Keystore Providers.

カスタム キーストア プロバイダーとのやりとりには、2 つの接続属性が使用されます。Two connection attributes are used to interact with custom keystore providers. これらは次のとおりです。They are:

  • SQL_COPT_SS_CEKEYSTOREPROVIDER

  • SQL_COPT_SS_CEKEYSTOREDATA

前者はキーストア プロバイダーを読み込んで、読み込まれたものを列挙するために使用され、後者はアプリケーションとプロバイダー間の通信を有効するために使用されます。The former is used to load and enumerate loaded keystore providers, while the latter enables application-provider communications. アプリケーションとプロバイダー間のやりとりには SQL Server との通信が必要ないため、これらの接続属性は、接続を確立する前後にいつでも使用できます。These connection attributes may be used at any time, before or after establishing a connection, since application-provider interaction does not involve communication with SQL Server. ただし、ドライバーはまだ読み込まれていないため、接続前にこれらの属性を設定および取得すると、それらはドライバー マネージャーによって処理され、期待した結果が得られない場合があります。However, because the driver has not been loaded yet, setting and getting these attributes before connecting will cause them to be processed by the Driver Manager, and may not yield the expected results.

キーストア プロバイダーの読み込みLoading a Keystore Provider

SQL_COPT_SS_CEKEYSTOREPROVIDER 接続属性を設定すると、クライアント アプリケーションでプロバイダー ライブラリを読み込み、そこに含まれるキーストア プロバイダーを使用できるようになります。Setting the SQL_COPT_SS_CEKEYSTOREPROVIDER connection attribute enables a client application to load a provider library, making available for use the keystore providers contained therein.

SQLRETURN SQLSetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
引数Argument [説明]Description
ConnectionHandle [入力] 接続ハンドル。[Input] Connection handle. 有効な接続ハンドルである必要がありますが、1 つの接続ハンドルを介して読み込まれたプロバイダーは、同じプロセス内の他のいずれからもアクセス可能です。Must be a valid connection handle, but providers loaded via one connection handle are accessible from any other in the same process.
Attribute [入力] 設定する属性: SQL_COPT_SS_CEKEYSTOREPROVIDER 定数。[Input] Attribute to set: the SQL_COPT_SS_CEKEYSTOREPROVIDER constant.
ValuePtr [入力] プロバイダー ライブラリのファイル名を指定する null 終了文字列へのポインター。[Input] Pointer to a null-terminated character string specifying the filename of the provider library. SQLSetConnectAttrA の場合、これは ANSI (マルチバイト) 文字列です。For SQLSetConnectAttrA, this is an ANSI (multibyte) string. SQLSetConnectAttrW の場合、これは Unicode (wchar_t) 文字列です。For SQLSetConnectAttrW, this is a Unicode (wchar_t) string.
StringLength [入力] ValuePtr 文字列の長さ、または SQL_NTS。[Input] The length of the ValuePtr string, or SQL_NTS.

ドライバーは、プラットフォーム定義の動的なライブラリー読み込みメカニズム (Linux および macOS の場合は dlopen()、Windows の場合は LoadLibrary()) を使用して ValuePtr パラメーターで識別されたライブラリーの読み込みを試み、そこで定義されているプロバイダーを自身が認識しているプロバイダーのリストに追加します。The driver attempts to load the library identified by the ValuePtr parameter using the platform-defined dynamic library loading mechanism (dlopen() on Linux and macOS, LoadLibrary() on Windows), and adds any providers defined therein to the list of providers known to the driver. 次のエラーが発生することがあります。The following errors may occur:

ErrorError [説明]Description
CE203 動的なライブラリを読み込めませんでした。The dynamic library could not be loaded.
CE203 "CEKeyStoreProvider" エクスポート シンボルがライブラリ内で見つかりませんでした。The "CEKeyStoreProvider" exported symbol was not found in the library.
CE203 ライブラリ内の 1 つまたは複数のプロバイダーが既に読み込まれています。One or more providers in the library are already loaded.

SQLSetConnectAttr からは、通常、エラーまたは成功を示す値が返され、標準的な ODBC 診断メカニズムを介して発生したエラーについては追加の情報が提供されます。SQLSetConnectAttr returns the usual error or success values, and additional information is available for any errors which occurred via the standard ODBC diagnostic mechanism.

注意

アプリケーション プログラマーは、任意のカスタム プロバイダーを必要とする任意のクエリを任意の接続を介して送信する前に、そのカスタム プロバイダーを確実に読み込んでおく必要があります。The application programmer must ensure that any custom providers are loaded before any query requiring them is sent over any connection. このようにしないと、エラーが発生します。Failure to do so results in the error:

ErrorError [説明]Description
CE200 キーストア プロバイダー %1 が見つかりません。Keystore provider %1 not found. 適切なキーストア プロバイダー ライブラリが読み込まれていることを確認します。Ensure that the appropriate keystore provider library has been loaded.

注意

キーストア プロバイダーの実装者は、ご自分のカスタム プロバイダーの名前に MSSQL を使用することを避けてください。Keystore provider implementors should avoid the use of MSSQL in the name of their custom providers. この用語は Microsoft による使用のみを目的として予約されており、将来の組み込みプロバイダーと競合する可能性があります。This term is reserved exclusively for Microsoft use and may cause conflicts with future built-in providers. カスタム プロバイダーの名前にこの用語を使用すると、ODBC 警告が発生する可能性があります。Using this term in the name of a custom provider may result in an ODBC warning.

読み込まれたプロバイダーの一覧を取得するGetting the List of Loaded Providers

この接続属性を取得すると、クライアント アプリケーションが、ドライバーに現在読み込まれているキーストア プロバイダー (組み込まれているものも含まれる) を特定できるようになります。これは、接続した後でのみ実行できます。Getting this connection attribute enables a client application to determine the keystore providers currently loaded in the driver (including those built in.) This can only be performed after connecting.

SQLRETURN SQLGetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr);
引数Argument [説明]Description
ConnectionHandle [入力] 接続ハンドル。[Input] Connection handle. 有効な接続ハンドルである必要がありますが、1 つの接続ハンドルを介して読み込まれたプロバイダーは、同じプロセス内の他のいずれからもアクセス可能です。Must be a valid connection handle, but providers loaded via one connection handle are accessible from any other in the same process.
Attribute [入力] 取得する属性: SQL_COPT_SS_CEKEYSTOREPROVIDER 定数。[Input] Attribute to retrieve: the SQL_COPT_SS_CEKEYSTOREPROVIDER constant.
ValuePtr [出力] 次に読み込まれたプロバイダー名を返す先のメモリを指すポインター。[Output] A pointer to memory in which to return the next loaded provider name.
BufferLength [入力] バッファー ValuePtr バッファーの長さ。[Input] The length of the buffer ValuePtr.
StringLengthPtr [出力] (Null 終了文字を除く) バイトの合計数を返すバッファーへのポインターで返される使用可能な*ValuePtr します。[Output] A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *ValuePtr. ValuePtr が null ポインターである場合、長さは返されません。If ValuePtr is a null pointer, no length is returned. 属性値が文字列であり、返す対象のバイト数が BufferLength から null 終了文字の長さを差し引いた値より大きい場合、* ValuePtr 内のデータは、BufferLength から null 終了文字の長さを差し引いた長さに切り捨てられ、ドライバーによって null で終了されます。If the attribute value is a character string and the number of bytes available to return is greater than BufferLength minus the length of the null-termination character, the data in *ValuePtr is truncated to BufferLength minus the length of the null-termination character and is null-terminated by the driver.

リスト全体を取得できるようにするために、すべての Get 操作で、現在のプロバイダーの名前が返され、内部カウンターがインクリメントされ次へと進みます。To allow retrieving the entire list, every Get operation returns the current provider's name, and increments an internal counter to the next one. このカウンターがリストの末尾に達すると、空の文字列 ("") が返され、カウンターはリセットされます。後続の Get 操作は、リストの先頭から再び続行されます。Once this counter reaches the end of the list, an empty string ("") is returned, and the counter is reset; successive Get operations then proceed again from the beginning of the list.

キーストア プロバイダーとの通信Communicating with Keystore Providers

SQL_COPT_SS_CEKEYSTOREDATA 接続属性を使用すると、クライアント アプリケーションで、読み込まれたキーストア プロバイダーと通信して追加のパラメーターやキー生成情報を構成できるようになります。クライアント アプリケーションとプロバイダー間の通信は、この接続属性を使用した Get 要求および Set 要求に基づき、シンプルな要求 - 応答プロトコルに従って行われます。The SQL_COPT_SS_CEKEYSTOREDATA connection attribute enables a client application to communicate with loaded keystore providers for configuring additional parameters, keying material, etc. The communication between a client application and a provider follows a simple request-response protocol, based on Get and Set requests using this connection attribute. 通信はクライアント アプリケーションによってのみ開始されます。Communication is initiated only by the client application.

注意

CEKeyStoreProvider が応答する ODBC 呼び出し (SQLGet/SetConnectAttr) の性質上、ODBC インターフェイスでは接続コンテキストの解決方法でのデータの設定のみがサポートされます。Due to the nature of the ODBC calls CEKeyStoreProvider's respond to (SQLGet/SetConnectAttr), the ODBC interface only supports setting data at the resolution of the connection context.

アプリケーションは、CEKeystoreData 構造体を介し、ドライバーを通してキーストアプロバイダーと通信します。The application communicates with keystore providers through the driver via the CEKeystoreData structure:

typedef struct CEKeystoreData {
wchar_t *name;
unsigned int dataSize;
char data[];
} CEKEYSTOREDATA;
引数Argument [説明]Description
name [入力] 設定時にデータが送信される先のプロバイダーの名前。[Input] Upon Set, the name of the provider to which the data is sent. 取得時には無視されます。Ignored upon Get. null で終了するワイド文字列。Null-terminated, wide-character string.
dataSize [入力] 構造体に続くデータ配列のサイズ。[Input] The size of the data array following the structure.
data [入出力] 設定時にプロバイダーに送信されるデータ。[InOut] Upon Set, the data to be sent to the provider. これは任意のデータとなる場合があります。ドライバーでは、データの解釈は試みられません。This may be arbitrary data; the driver makes no attempt to interpret it. 取得時に、プロバイダーから読み取られたデータを受信するバッファー。Upon Get, the buffer to receive the data read from the provider.

プロバイダーへのデータの書き込みWriting data to a provider

SQL_COPT_SS_CEKEYSTOREDATA 属性を使用した SQLSetConnectAttr 呼び出しでは、指定されたキーストア プロバイダーにデータの "パケット" が書き込まれます。A SQLSetConnectAttr call using the SQL_COPT_SS_CEKEYSTOREDATA attribute writes a "packet" of data to the specified keystore provider.

SQLRETURN SQLSetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
引数Argument [説明]Description
ConnectionHandle [入力] 接続ハンドル。[Input] Connection handle. 有効な接続ハンドルである必要がありますが、1 つの接続ハンドルを介して読み込まれたプロバイダーは、同じプロセス内の他のいずれからもアクセス可能です。Must be a valid connection handle, but providers loaded via one connection handle are accessible from any other in the same process.
Attribute [入力] 設定する属性: SQL_COPT_SS_CEKEYSTOREDATA 定数。[Input] Attribute to set: the SQL_COPT_SS_CEKEYSTOREDATA constant.
ValuePtr [入力] CEKeystoreData 構造体を指すポインター。[Input] Pointer to a CEKeystoreData structure. 構造体の名前フィールドでは、データが対象とされているプロバイダーが識別されます。The name field of the structure identifies the provider for which the data is intended.
StringLength [入力] SQL_IS_POINTER 定数[Input] SQL_IS_POINTER constant

エラーに関する追加の詳細情報は、SQLGetDiacRec を介して取得できます。Additional detailed error information may be obtained via SQLGetDiacRec.

注意

プロバイダーでは必要に応じて接続ハンドルを使用して、書き込まれたデータを特定の接続に関連付けることができます。The provider can use the connection handle to associate the written data to a specific connection, if it so desires. これは、接続ごとの構成を実装する場合に役立ちます。This is useful for implementing per-connection configuration. また、データを送信するのに使用した接続に関係なく、接続コンテキストが無視され、データが同じように扱われる場合もあります。It may also ignore the connection context and treat the data identically regardless of the connection used to send the data. 詳細については、「コンテキストの関連付け」を参照してください。See Context Association for more information.

プロバイダーからのデータの読み取りReading data from a provider

SQL_COPT_SS_CEKEYSTOREDATA 属性を使用して SQLGetConnectAttr を呼び出すと、"最後に書き込まれた" プロバイダーからデータの "パケット" が読み取られます。A call to SQLGetConnectAttr using the SQL_COPT_SS_CEKEYSTOREDATA attribute reads a "packet" of data from the last-written-to provider. 何もなければ、関数シーケンス エラーが発生します。If there was none, a Function Sequence Error occurs. キーストア プロバイダーの実装者には、他の副作用を引き起こすことなく読み取り操作のためにプロバイダーを選択する方法として 0 バイトの "ダミー書き込み" をサポートすることが理にかなっている場合、それをお勧めします。Keystore provider implementers are encouraged to support "dummy writes" of 0 bytes as a way of selecting the provider for read operations without causing other side-effects, if it makes sense to do so.

SQLRETURN SQLGetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr);
引数Argument [説明]Description
ConnectionHandle [入力] 接続ハンドル。[Input] Connection handle. 有効な接続ハンドルである必要がありますが、1 つの接続ハンドルを介して読み込まれたプロバイダーは、同じプロセス内の他のいずれからもアクセス可能です。Must be a valid connection handle, but providers loaded via one connection handle are accessible from any other in the same process.
Attribute [入力] 取得する属性: SQL_COPT_SS_CEKEYSTOREDATA 定数。[Input] Attribute to retrieve: the SQL_COPT_SS_CEKEYSTOREDATA constant.
ValuePtr [出力] プロバイダーから読み取られたデータが配置される CEKeystoreData 構造体を指すポインター。[Output] A pointer to a CEKeystoreData structure in which the data read from the provider is placed.
BufferLength [入力] SQL_IS_POINTER 定数[Input] SQL_IS_POINTER constant
StringLengthPtr [出力] BufferLength を返す先のバッファーを指すポインター。[Output] A pointer to a buffer in which to return BufferLength. *ValuePtr が null ポインターである場合、長さは返されません。If *ValuePtr is a null pointer, no length is returned.

呼び出し元は、CEKEYSTOREDATA 構造体をたどるのに十分な長さのバッファーを、書き込み先のプロバイダーに確実に割り当てる必要があります。The caller must ensure that a buffer of sufficient length following the CEKEYSTOREDATA structure is allocated for the provider to write into. 戻ると、その dataSize フィールドは、プロバイダーから読み取られたデータの実際の長さで更新されます。Upon return, its dataSize field is updated with the actual length of data read from the provider. エラーに関する追加の詳細情報は、SQLGetDiacRec を介して取得できます。Additional detailed error information may be obtained via SQLGetDiacRec.

このインターフェイスでは、アプリケーションとキーストア プロバイダーの間で転送されるデータの形式に対して追加の要件は設定されていません。This interface places no additional requirements on the format of data transferred between an application and a keystore provider. 各プロバイダーでは、必要に応じて独自のプロトコル/データ フォーマットを定義できます。Each provider can define its own protocol/data format, depending on its needs.

独自のキーストア プロバイダーを実装する例については、「カスタム キーストア プロバイダー」を参照してください。For an example of implementing your own keystore provider, see Custom Keystore Providers

Always Encrypted を使用するときの ODBC ドライバーの制限事項Limitations of the ODBC driver when using Always Encrypted

非同期操作Asynchronous Operations

ODBC ドライバーでは、Always Encrypted で非同期操作の使用が許可されますが、Always Encrypted を有効にすると、操作に対してパフォーマンスの影響があります。While the ODBC driver will allow the use of asynchronous operations with Always Encrypted, there is a performance impact on the operations when Always Encrypted is enabled. ステートメントの暗号化メタデータを特定する sys.sp_describe_parameter_encryption の呼び出しはブロックされており、ドライバーはサーバーからメタデータが返されるのを待ってから SQL_STILL_EXECUTING を返します。The call to sys.sp_describe_parameter_encryption to determine encryption metadata for the statement is blocking and will cause the driver to wait for the server to return the metadata before returning SQL_STILL_EXECUTING.

SQLGetData を使用してパーツ内のデータを取得するRetrieve data in parts with SQLGetData

ODBC Driver 17 for SQL Server より前では、SQLGetData を使用してパーツ内の暗号化された文字およびバイナリの列を取得することはできません。Before ODBC Driver 17 for SQL Server, encrypted character and binary columns cannot be retrieved in parts with SQLGetData. 列のデータ全体を入れるのに十分な長さのバッファーを使用して、SQLGetData を 1 回だけ呼び出すことができます。Only one call to SQLGetData can be made, with a buffer of sufficient length to contain the entire column's data.

SQLPutData を使用してパーツ内にデータを送信するSend data in parts with SQLPutData

ODBC Driver 17.3 for SQL Server より前では、SQLPutData を使用してパーツ内に挿入または比較用のデータを送信することはできません。Before ODBC Driver 17.3 for SQL Server, data for insertion or comparison cannot be sent in parts with SQLPutData. データ全体を入れるバッファーを使用して、SQLPutData を 1 回だけ呼び出すことができます。Only one call to SQLPutData can be made, with a buffer containing the entire data. 暗号化された列に長いデータを挿入するには、次のセクションで説明する一括コピー API を入力データ ファイルと一緒に使用します。For inserting long data into encrypted columns, use the Bulk Copy API, described in the next section, with an input data file.

暗号化された money および smallmoneyEncrypted money and smallmoney

暗号化された money 列または smallmoney 列をパラメーターの対象にすることはできません。それらのデータ型にマップされる特定の ODBC データ型がなく、結果としてオペランド型の不整合エラーが発生するためです。Encrypted money or smallmoney columns cannot be targeted by parameters, since there is no specific ODBC data type which maps to those types, resulting in Operand Type Clash errors.

暗号化された列の一括コピーBulk Copy of Encrypted Columns

ODBC Driver 17 for SQL Server 以降、SQL 一括コピー関数および bcp ユーティリティーの使用は Always Encrypted でサポートされています。Use of the SQL Bulk Copy functions and the bcp utility is supported with Always Encrypted since ODBC Driver 17 for SQL Server. プレーンテキスト (挿入時に暗号化され、取得時に暗号化解除される) と暗号化テキスト (逐語的に転送される) は両方とも、一括コピー (bcp_*) API および bcp ユーティリティを使用して挿入および取得することができます。Both plaintext (encrypted on insertion and decrypted on retrieval) and ciphertext (transferred verbatim) can be inserted and retrieved using the Bulk Copy (bcp_*) APIs and the bcp utility.

  • 暗号化テキストを varbinary(max) 形式で取得するには (たとえば、別のデータベースに一括で読み込む場合)、ColumnEncryption オプションを指定せずに (またはそれを Disabled に設定して) BCP OUT 操作を実行します。To retrieve ciphertext in varbinary(max) form (e.g. for bulk loading into a different database), connect without the ColumnEncryption option (or set it to Disabled) and perform a BCP OUT operation.

  • プレーン テキストを挿入および取得し、必要に応じてドライバーに暗号化と暗号化解除を透過的に実行させるには、ColumnEncryptionEnabled に設定するだけで十分です。To insert and retrieve plaintext, and let the driver transparently perform encryption and decryption as required, setting ColumnEncryption to Enabled is sufficient. BCP API の機能は、それ以外では変更されていません。The functionality of the BCP API is otherwise unchanged.

  • 暗号化テキストを varbinary(max) 形式 (上記で取得したような) で挿入するには、BCPMODIFYENCRYPTED オプションを TRUE に設定して BCP IN 操作を実行します。To insert ciphertext in varbinary(max) form (e.g. as retrieved above), set the BCPMODIFYENCRYPTED option to TRUE and perform a BCP IN operation. 結果として得られたデータを暗号化解除できるようにするには、変換先列の CEK を、暗号化テキストを最初に取得したときの CEK と確実に同じにしてください。In order for the resulting data to be decryptable, ensure that the destination column's CEK is the same as that from which the ciphertext was originally obtained.

bcp ユーティリティーを使用する場合: ColumnEncryption 設定を制御するには、-D オプションを使用して、必要な値を含む DSN を指定します。When using the bcp utility: To control the ColumnEncryption setting, use the -D option and specify a DSN containing the desired value. 暗号テキストを挿入するには、ユーザーの ALLOW_ENCRYPTED_VALUE_MODIFICATIONS 設定を確実に有効にします。To insert ciphertext, ensure the ALLOW_ENCRYPTED_VALUE_MODIFICATIONS setting of the user is enabled.

次の表は、暗号化された列を操作するときのアクションの要約を示しています。The following table provides a summary of the actions when operating on an encrypted column:

ColumnEncryption BCP の方向BCP Direction [説明]Description
Disabled OUT (クライアントへ)OUT (to client) 暗号化テキストを取得します。Retrieves ciphertext. 観察対象のデータ型は varbinary(max) です。The observed datatype is varbinary(max).
Enabled OUT (クライアントへ)OUT (to client) プレーンテキストを取得します。Retrieves plaintext. ドライバーでは、列データが暗号化解除されます。The driver will decrypt the column data.
Disabled IN (サーバーへ)IN (to server) 暗号化テキストを挿入します。Inserts ciphertext. これは、暗号化されたデータの暗号化解除を必要とすることなく、不透明に移動することを目的としています。This is intended for opaquely moving encrypted data without requiring it to be decrypted. ALLOW_ENCRYPTED_VALUE_MODIFICATIONS オプションがユーザーに対して設定されていないか、接続ハンドルに対して BCPMODIFYENCRYPTED が設定されていない場合、操作は失敗します。The operation will fail if the ALLOW_ENCRYPTED_VALUE_MODIFICATIONS option is not set on the user, or BCPMODIFYENCRYPTED is not set on the connection handle. 詳しくは以下をご覧ください。See below for more information.
Enabled IN (サーバーへ)IN (to server) プレーン テキストを挿入します。Inserts plaintext. ドライバーで列データが暗号化されます。The driver will encrypt the column data.

BCPMODIFYENCRYPTED オプションThe BCPMODIFYENCRYPTED option

データの破損を防ぐために、サーバーでは、通常、暗号化された列に暗号化テキストを直接挿入することは許可されていません。したがって、それを試みても失敗します。ただし、暗号化されたデータ BCP API を使用して一括読み込みする場合は、BCPMODIFYENCRYPTED bcp_control オプションを TRUE に設定することで、暗号化テキストを直接挿入できるようになり、ユーザー アカウント上で ALLOW_ENCRYPTED_VALUE_MODIFICATIONS オプションを設定するより暗号化されたデータが破損する危険性が少なくなります。To prevent data corruption, the server normally does not allow inserting ciphertext directly into an encrypted column, and thus attempts to do so will fail; however, for bulk loading of encrypted data using the BCP API, setting the BCPMODIFYENCRYPTED bcp_control option to TRUE will allow ciphertext to be inserted directly, and reduces the risk of corrupting encrypted data over setting the ALLOW_ENCRYPTED_VALUE_MODIFICATIONS option on the user account. とはいえ、キーはデータと一致する必要があるため、一括挿入の後、およびさらに使用する前に、挿入されたデータの読み取り専用チェックを実行することをお勧めします。Nonetheless, the keys must match the data and it is a good idea to perform some read-only checks of the inserted data after the bulk insertion and before further use.

詳しくは、「Always Encrypted で保護された機微なデータの移行」をご覧ください。See Migrate Sensitive Data Protected by Always Encrypted for more information.

Always Encrypted API の概要Always Encrypted API Summary

接続文字列キーワードConnection String Keywords

[オブジェクト名]Name [説明]Description
ColumnEncryption 指定できる値は Enabled/Disabled です。Accepted values are Enabled/Disabled.
Enabled -- 接続の Always Encrypted 機能を有効にします。Enabled -- enables Always Encrypted functionality for the connection.
Disabled -- 接続の Always Encrypted 機能を無効にします。Disabled -- disable Always Encrypted functionality for the connection.

既定値は Disabled です。The default is Disabled.
KeyStoreAuthentication 有効な値: KeyVaultPasswordKeyVaultClientSecretValid Values: KeyVaultPassword, KeyVaultClientSecret
KeyStorePrincipalId KeyStoreAuthentication = KeyVaultPassword の場合は、この値を有効な Azure Active Directory ユーザー プリンシパル名に設定します。When KeyStoreAuthentication = KeyVaultPassword, set this value to a valid Azure Active Directory User Principal Name.
KeyStoreAuthetication = KeyVaultClientSecret の場合は、この値を有効な Azure Active Directory アプリケーション クライアント ID に設定します。When KeyStoreAuthetication = KeyVaultClientSecret set this value to a valid Azure Active Directory Application Client ID
KeyStoreSecret KeyStoreAuthentication = KeyVaultPassword の場合は、この値を対応するユーザー名のパスワードに設定します。When KeyStoreAuthentication = KeyVaultPassword set this value to the password for the corresponding user name.
KeyStoreAuthentication = KeyVaultClientSecret の場合は、この値を、有効な Azure Active Directory アプリケーション クライアント ID に関連付けられたアプリケーション シークレットに設定します。When KeyStoreAuthentication = KeyVaultClientSecret set this value to the Application Secret associated with a valid Azure Active Directory Application Client ID

接続属性Connection Attributes

[オブジェクト名]Name Type [説明]Description
SQL_COPT_SS_COLUMN_ENCRYPTION 接続前Pre-connect SQL_COLUMN_ENCRYPTION_DISABLE (0) -- Always Encrypted を無効にしますSQL_COLUMN_ENCRYPTION_DISABLE (0) -- Disable Always Encrypted
SQL_COLUMN_ENCRYPTION_ENABLE (1) -- Always Encrypted を有効にしますSQL_COLUMN_ENCRYPTION_ENABLE (1) -- Enable Always Encrypted
SQL_COPT_SS_CEKEYSTOREPROVIDER 接続後Post-connect [設定] CEKeystoreProvider の読み込みを試みます[Set] Attempt to load CEKeystoreProvider
[取得] CEKeystoreProvider 名を返します[Get] Return a CEKeystoreProvider name
SQL_COPT_SS_CEKEYSTOREDATA 接続後Post-connect [設定] CEKeystoreProvider にデータを書き込みます[Set] Write data to CEKeystoreProvider
[取得] CEKeystoreProvider からデータを読み取ります[Get] Read data from CEKeystoreProvider
SQL_COPT_SS_CEKCACHETTL 接続後Post-connect [設定] CEK キャッシュ TTL を設定します[Set] Set the CEK cache TTL
[取得] 現在の CEK キャッシュ TTL を取得します[Get] Get the current CEK cache TTL
SQL_COPT_SS_TRUSTEDCMKPATHS 接続後Post-connect [設定] 信頼された CMK パス ポインターを設定します[Set] Set the trusted CMK paths pointer
[取得] 現在の信頼された CMK パス ポインターを取得します[Get] Get the current trusted CMK paths pointer

ステートメント属性Statement Attributes

[オブジェクト名]Name [説明]Description
SQL_SOPT_SS_COLUMN_ENCRYPTION SQL_CE_DISABLED (0) -- ステートメントに対して Always Encrypted が無効にされますSQL_CE_DISABLED (0) -- Always Encrypted is disabled for the statement
SQL_CE_RESULTSETONLY (1) -- 暗号化解除のみ。SQL_CE_RESULTSETONLY (1) -- Decryption Only. 結果セットと戻り値は暗号化解除され、パラメーターは暗号化されませんResultsets and return values are decrypted, and parameters are not encrypted
SQL_CE_ENABLED (3) -- Always Encrypted は有効にされ、パラメーターと結果の両方に使用されますSQL_CE_ENABLED (3) -- Always Encrypted is enabled and used for both parameters and results

記述子フィールドDescriptor Fields

IPD フィールドIPD Field サイズ/型Size/Type 既定値Default Value [説明]Description
SQL_CA_SS_FORCE_ENCRYPT (1236)SQL_CA_SS_FORCE_ENCRYPT (1236) WORD (2 バイト)WORD (2 bytes) 00 0 (既定値) の場合: このパラメーターを暗号化するかどうかは、暗号化メタデータの可用性によって決まります。When 0 (default): decision to encrypt this parameter is determined by availability of encryption metadata.

ゼロ以外の場合: このパラメーターで暗号化メタデータが使用可能な場合、それは暗号化されます。When nonzero: if encryption metadata is available for this parameter, it is encrypted. それ以外の場合、要求は次のエラーで失敗します: [CE300] [Microsoft][ODBC Driver 13 for SQL Server]必須の暗号化がパラメーターに指定されましたが、サーバーから暗号化メタデータが提供されませんでした。Otherwise, the request fails with error [CE300] [Microsoft][ODBC Driver 13 for SQL Server]Mandatory encryption was specified for a parameter but no encryption metadata was provided by the server.

bcp_control オプションbcp_control Options

オプション名Option Name 既定値Default Value [説明]Description
BCPMODIFYENCRYPTED (21)BCPMODIFYENCRYPTED (21) FALSEFALSE TRUE の場合、varbinary (max) 値を暗号化された列に挿入できるようにします。When TRUE, allows varbinary(max) values to be inserted into an encrypted column. FALSE の場合、正しい型と暗号化メタデータが提供されていない限り、挿入を阻止します。When FALSE, prevents insertion unless correct type and encryption metadata is supplied.

参照See Also