SqlColumnEncryptionKeyStoreProvider.xml

<docs>
  <members name="SqlColumnEncryptionKeyStoreProvider">
    <SqlColumnEncryptionKeyStoreProvider>
      <summary>
        Base class for all key store providers. A custom provider must derive from this class and override its member functions and then register it using <see cref="M:Microsoft.Data.SqlClient.SqlConnection.RegisterColumnEncryptionKeyStoreProviders(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" />, <see cref="M:Microsoft.Data.SqlClient.SqlConnection.RegisterColumnEncryptionKeyStoreProvidersOnConnection(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.RegisterColumnEncryptionKeyStoreProvidersOnCommand(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" />. For details see, <see href="https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
      </summary>
    </SqlColumnEncryptionKeyStoreProvider>
    <ctor>
      <summary>
        Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider" />.
      </summary>
    </ctor>
    <DecryptColumnEncryptionKey>
      <param name="masterKeyPath">
        The master key path.
      </param>
      <param name="encryptionAlgorithm">
        The encryption algorithm.
      </param>
      <param name="encryptedColumnEncryptionKey">
        The encrypted column encryption key.
      </param>
      <summary>
        Decrypts the specified encrypted value of a column encryption key. The encrypted value is expected to be encrypted using the column master key with the specified key path and using the specified algorithm.
      </summary>
      <returns>
        Returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key.
      </returns>
    </DecryptColumnEncryptionKey>
    <DecryptColumnEncryptionKeyAsync>
      <param name="masterKeyPath">
        The master key path.
      </param>
      <param name="encryptionAlgorithm">
        The encryption algorithm.
      </param>
      <param name="encryptedColumnEncryptionKey">
        The encrypted column encryption key.
      </param>
      <param name="cancellationToken">
        A token to cancel the asynchronous operation.
      </param>
      <summary>
        Decrypts the specified encrypted value of a column encryption key asynchronously. The encrypted value is expected to be encrypted using the column master key with the specified key path and using the specified algorithm.
      </summary>
      <returns>
        Returns a task that returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key on completion.
      </returns>
    </DecryptColumnEncryptionKeyAsync>
    <EncryptColumnEncryptionKey>
      <param name="masterKeyPath">
        The master key path.
      </param>
      <param name="encryptionAlgorithm">
        The encryption algorithm.
      </param>
      <param name="columnEncryptionKey">
        The plaintext column encryption key.
      </param>
      <summary>
        Encrypts a column encryption key using the column master key with the specified key path and using the specified algorithm.
      </summary>
      <returns>
        Returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key.
      </returns>
    </EncryptColumnEncryptionKey>
    <EncryptColumnEncryptionKeyAsync>
      <param name="masterKeyPath">
        The master key path.
      </param>
      <param name="encryptionAlgorithm">
        The encryption algorithm.
      </param>
      <param name="columnEncryptionKey">
        The plaintext column encryption key.
      </param>
      <param name="cancellationToken">
        A token to cancel the asynchronous operation.
      </param>
      <summary>
        Encrypts a column encryption key asynchronously using the column master key with the specified key path and using the specified algorithm.
      </summary>
      <returns>
        Returns a task that returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key on completion.
      </returns>
    </EncryptColumnEncryptionKeyAsync>
    <SignColumnMasterKeyMetadata>
      <param name="masterKeyPath">
        The column master key path.
      </param>
      <param name="allowEnclaveComputations">
        <see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
      </param>
      <summary>
        When implemented in a derived class, digitally signs the column master key metadata with the column master key referenced by the <paramref name="masterKeyPath" /> parameter. The input values used to generate the signature should be the specified values of the <paramref name="masterKeyPath" /> and <paramref name="allowEnclaveComputations" /> parameters.
      </summary>
      <returns>
        Returns the signature of the column master key metadata.
      </returns>
      <remarks>
        <para>
          To ensure that the <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method doesn't break applications that rely on an old API, it throws a <see cref="T:System.NotImplementedException" /> exception by default.
        </para>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method will be used by client tools that generate Column Master Keys (CMK) for customers. <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> must be implemented by the corresponding key store providers that wish to use enclaves with <see href="https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
        </para>
      </remarks>
      <exception cref="T:System.NotImplementedException">
        In all cases.
      </exception>
    </SignColumnMasterKeyMetadata>
    <SignColumnMasterKeyMetadataAsync>
      <param name="masterKeyPath">
        The column master key path.
      </param>
      <param name="allowEnclaveComputations">
        <see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
      </param>
      <param name="cancellationToken">
        A token to cancel the asynchronous operation.
      </param>
      <summary>
        When implemented in a derived class, asynchronously digitally signs the column master key metadata with the column master key referenced by the <paramref name="masterKeyPath" /> parameter. The input values used to generate the signature should be the specified values of the <paramref name="masterKeyPath" /> and <paramref name="allowEnclaveComputations" /> parameters.
      </summary>
      <returns>
        Returns a task that returns the signature of the column master key metadata on completion.
      </returns>
      <remarks>
        <para>
          The default implementation calls the synchronous <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method, which throws a <see cref="T:System.NotImplementedException" /> by default. In this case, the returned task will be faulted with <see cref="T:System.NotImplementedException" />.
        </para>
        <para>
          Key store providers that wish to use enclaves with <see href="https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see> should override this method with a truly asynchronous implementation when the signing operation involves I/O.
        </para>
      </remarks>
    </SignColumnMasterKeyMetadataAsync>
    <VerifyColumnMasterKeyMetadata>
      <param name="masterKeyPath">
        The column master key path.
      </param>
      <param name="allowEnclaveComputations">
        Indicates whether the column master key supports enclave computations.
      </param>
      <param name="signature">
        The signature of the column master key metadata.
      </param>
      <summary>
        When implemented in a derived class, this method is expected to verify the specified signature is valid for the column master key with the specified key path and the specified enclave behavior. The default implementation throws `NotImplementedException`.
      </summary>
      <returns>
        When implemented in a derived class, the method is expected to return true if the specified signature is valid, or false if the specified signature is not valid. The default implementation throws `NotImplementedException`.
      </returns>
    </VerifyColumnMasterKeyMetadata>
    <VerifyColumnMasterKeyMetadataAsync>
      <param name="masterKeyPath">
        The column master key path.
      </param>
      <param name="allowEnclaveComputations">
        Indicates whether the column master key supports enclave computations.
      </param>
      <param name="signature">
        The signature of the column master key metadata.
      </param>
      <param name="cancellationToken">
        A token to cancel the asynchronous operation.
      </param>
      <summary>
        When implemented in a derived class, this method is expected to verify the specified signature is valid for the column master key with the specified key path and the specified enclave behavior asynchronously. The default implementation returns a faulted task with <see cref="T:System.NotImplementedException" />.
      </summary>
      <returns>
        A task that, when completed, returns <see langword="true" /> if the specified signature is valid, or <see langword="false" /> if it is not valid.
      </returns>
    </VerifyColumnMasterKeyMetadataAsync>
    <ColumnEncryptionKeyCacheTtl>
      <summary>
        Gets or sets the lifespan of the decrypted column encryption key in the cache. Once the timespan has elapsed, the decrypted column encryption key is discarded and must be revalidated.
      </summary>
      <remarks>
        <para>
          Internally, there is a cache of column encryption keys (once they are decrypted). This is useful for rapidly decrypting multiple data values. The default value is 2 hours. Setting this value to zero disables caching.
        </para>
        <para>
          The column encryption keys decrypted by custom key store providers registered on a connection or command instance will not be cached. Custom key store providers should implement their own caching mechanism. Caching implemented by custom key store providers will be disabled by the driver if the key store provider instance is registered using <see cref="M:Microsoft.Data.SqlClient.SqlConnection.RegisterColumnEncryptionKeyStoreProviders(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" />. Any caching implementation should reference the value of this property before caching a column encryption key and not cache it if the value is zero. This will avoid duplicate caching and possible user confusion when they are trying to configure key caching.
        </para>
      </remarks>
    </ColumnEncryptionKeyCacheTtl>
  </members>
</docs>