Merge pull request #33995 from David-Engel/patch-1

Add clarification around OLEDB 19 encryption and certificate validation settings behavior

Author: JamesJBarnett

docs/connect/oledb/features/encryption-and-certificate-validation.md

@@ -3,7 +3,7 @@ title: Encryption and certificate validation
 description: Learn about encryption and certificate validation for SQL Server connections. The OLE DB Driver for SQL Server supports encryption and certificate validation.
 author: David-Engel
 ms.author: davidengel
-ms.date: 04/20/2023
+ms.date: 05/02/2025
 ms.service: sql
 ms.subservice: connectivity
 ms.topic: "reference"
@@ -20,19 +20,19 @@ helpviewer_keywords:
 
 [!INCLUDE[Driver_OLEDB_Download](../../../includes/driver_oledb_download.md)]
 
-[!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] always encrypts network packets associated with logging in. If no certificate has been provisioned on the server when it starts up, [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] generates a self-signed certificate, which is used to encrypt login packets.
+[!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] always encrypts network packets associated with logging in. If no certificate is provisioned on the server when it starts up, [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] generates a self-signed certificate, which is used to encrypt login packets.
 
 Self-signed certificates don't guarantee security. The encrypted handshake is based on NT LAN Manager (NTLM). It's highly recommended you provision a verifiable certificate on SQL Server for secure connectivity. Transport Security Layer (TLS) can be made secure only with certificate validation.
 
 Applications may also request encryption of all network traffic by using connection string keywords or connection properties. The keywords are "Encrypt" for OLE DB when using a provider string with **`IDbInitialize::Initialize`**, or "Use Encryption for Data" for ADO and OLE DB when using an initialization string with **`IDataInitialize`**. Encryption may also be configured on the client machine in the registry using the **Force Protocol Encryption** option. For more information, see [Registry settings](./registry-settings.md#encryption-and-certificate-validation). By default, encryption of all network traffic for a connection requires a certificate being provisioned on the server. By setting your client to trust the certificate on the server, you might become vulnerable to man-in-the-middle attacks. If you deploy a verifiable certificate on the server, ensure you change the client settings about trusting the certificate to FALSE.
 
 For information about connection string keywords, see [Using connection string keywords with OLE DB driver for SQL Server](../applications/using-connection-string-keywords-with-oledb-driver-for-sql-server.md).
 
-To enable encryption to be used when a certificate hasn't been provisioned on the server, the **`Force Protocol Encryption`** and the **`Trust Server Certificate`** client [registry settings](./registry-settings.md#encryption-and-certificate-validation) can be set. In this case, encryption uses a self-signed server certificate without validation if no verifiable certificate has been provisioned on the server.
+To enable encryption to be used when a certificate isn't provisioned on the server, the **`Force Protocol Encryption`** and the **`Trust Server Certificate`** client [registry settings](./registry-settings.md#encryption-and-certificate-validation) must be set. In this case, encryption uses a self-signed server certificate without validation if no verifiable certificate is provisioned on the server.
 
 ## Encryption and certificate validation behavior
 
-Application settings never reduce the level of security set in the registry, but may strengthen it. For more information, see [Registry settings](./registry-settings.md#encryption-and-certificate-validation). For example, if **`Force Protocol Encryption`** isn't set for the client, an application may request encryption itself. To guarantee encryption even when a server certificate hasn't been provisioned, an application may request encryption and enable `TrustServerCertificate`. However, if `TrustServerCertificate` isn't enabled in the client configuration, a provisioned server certificate is still required.
+Application settings never reduce the level of security set in the registry, but may strengthen it. For more information, see [Registry settings](./registry-settings.md#encryption-and-certificate-validation). For example, if **`Force Protocol Encryption`** isn't set for the client, an application may request encryption itself. To guarantee encryption even when a server certificate isn't provisioned, an application may request encryption and enable `TrustServerCertificate`. However, if `TrustServerCertificate` isn't enabled in the client's registry configuration, a provisioned server certificate is still required.
 
 Version 19 of the OLE DB Driver for SQL Server introduces breaking changes in the encryption related APIs. For more information, see [Encryption property changes](../major-version-differences.md#encryption-property-changes).
 
@@ -42,20 +42,20 @@ The following table describes the evaluation of the encryption settings:
 
 | Force Protocol Encryption client setting | Connection string/connection attribute Encrypt/Use Encryption for Data | **Resulting encryption** |
 |--|--|--|
-| 0 | No/Optional | Optional |
-| 0 | Yes/Mandatory (default) | Mandatory |
-| 0 | Strict | Strict |
+| 0 (default) | No/Optional | Optional |
+| 0 (default) | Yes/Mandatory (default) | Mandatory |
+| 0 (default) | Strict | Strict |
 | 1 | No/Optional | Mandatory |
 | 1 | Yes/Mandatory (default) | Mandatory |
 | 1 | Strict | Strict |
 | 2 | Ignored | Strict |
 
 The following table describes the resulting encryption and validation:
 
-| Encryption | Trust Server Certificate client setting | Connection string/connection attribute Trust Server Certificate | Result |
+| Encryption | Trust Server Certificate client registry setting | Connection string/connection attribute Trust Server Certificate | Result |
 |--|--|--|--|
 | Optional | N/A | N/A | Encryption only occurs for LOGIN packets. |
-| Mandatory | 0 | Ignored | Encryption occurs only if there's a verifiable server certificate, otherwise the connection attempt fails. |
+| Mandatory | 0 (default) | Ignored | Encryption occurs only if there's a verifiable server certificate, otherwise the connection attempt fails. |
 | Mandatory | 1 | No (default) | Encryption occurs only if there's a verifiable server certificate, otherwise the connection attempt fails. |
 | Mandatory | 1 | Yes | Encryption always occurs, but may use a self-signed server certificate. |
 | Strict | N/A | N/A | Encryption occurs only if there's a verifiable server certificate, otherwise the connection attempt fails. |
@@ -71,7 +71,7 @@ The following table describes the resulting encryption and validation:
 For versions 18.x.x, to improve security, when the new **Authentication** or **Access Token** connection string keywords (or their corresponding properties) are used, the driver overrides the default encryption value by setting it to `yes`. Overriding happens at data source object initialization time. If encryption is set before initialization via any means, the value is respected and not overridden.
 
 > [!NOTE]
-> In ADO applications and in applications that obtain the `IDBInitialize` interface through `IDataInitialize::GetDataSource`, the Core Component implementing the interface explicitly sets encryption to its default value of `no`. As a result, the new authentication properties/keywords respect this setting and the encryption value **isn't** overridden. Therefore, it is **recommended** that these applications explicitly set `Use Encryption for Data=true` to override the default value.
+> In ADO applications and in applications that obtain the `IDBInitialize` interface through `IDataInitialize::GetDataSource`, the Core Component implementing the interface explicitly sets encryption to its default value of `no`. As a result, the new authentication properties/keywords respect this setting and the encryption value **isn't** overridden. Therefore, it's **recommended** that these applications explicitly set `Use Encryption for Data=true` to override the default value.
 
 To improve security, the new authentication methods respect the `TrustServerCertificate` setting (and its corresponding connection string keywords/properties) **independently of the client encryption setting**. As a result, server certificate is validated by default. The driver determines whether to validate the server certificate as follows:
 

docs/connect/oledb/major-version-differences.md

@@ -3,7 +3,7 @@ title: "MSOLEDBSQL major version differences"
 description: A description of the differences between the OLE DB Driver 19 for SQL Server and the OLE DB Driver for SQL Server
 author: David-Engel
 ms.author: davidengel
-ms.date: "02/16/2022"
+ms.date: 05/02/2025
 ms.service: sql
 ms.subservice: connectivity
 ms.topic: "reference"
@@ -17,15 +17,17 @@ helpviewer_keywords:
 
 ## Encryption property changes
 
-In the Microsoft OLE DB Driver 19 for SQL Server, there are a number of changes made to the encrypt property/connection string keyword.
+In the Microsoft OLE DB Driver 19 for SQL Server, there are changes to the `Encrypt` property/connection string keyword and certificate validation behavior.
 
-First, the driver property `SSPROP_INIT_ENCRYPT` has been changed from a `VT_BOOL` to a `VT_BSTR`. The valid values of this property are `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The valid values for the provider connection string keyword `Encrypt` have changed from `no`/`yes` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. Similarly, for the `IDataInitialize` connection string keyword `Use Encryption for Data`, the valid values have changed from `true`/`false` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The `Optional` value is synonymous with the old `no`/`false` values and the `Mandatory` value is synonymous with the old `yes`/`true` values. `Strict` is a new value added in version 19.0.0 of the OLE DB Driver for SQL Server and encrypts `PRELOGIN` packets in addition to all other communication with the server. `Strict` encryption is only supported on SQL Server endpoints that support TDS 8.0, otherwise the driver will fail to connect. The OLE DB Driver 19 for SQL Server continues to support all legacy keyword values for backwards compatibility.
+First, the driver property `SSPROP_INIT_ENCRYPT` changes from a `VT_BOOL` to a `VT_BSTR`. The valid values of this property are `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The valid values for the provider connection string keyword `Encrypt` change from `no`/`yes` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. Similarly, for the `IDataInitialize` connection string keyword `Use Encryption for Data`, the valid values change from `true`/`false` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The `Optional` value is synonymous with the old `no`/`false` values and the `Mandatory` value is synonymous with the old `yes`/`true` values. `Strict` is a new value added in version 19.0.0 of the OLE DB Driver for SQL Server and encrypts `PRELOGIN` packets in addition to all other communication with the server. `Strict` encryption is only supported on SQL Server endpoints that support TDS 8.0, otherwise the driver fails to connect. The OLE DB Driver 19 for SQL Server continues to support all legacy keyword values for backwards compatibility.
 
-Second, the default value has changed from `no`/`false` to `Mandatory`. This change means that connections are encrypted by default. Previously, the driver would encrypt connections if explicitly set by the user and/or mandated by the SQL Server when the server side property `Force Encryption` was set to `yes`. To use old default behavior, include `Encrypt=Optional;` in the provider connection string, or `Use Encryption for Data=Optional;` in the `IDataInitialize` connection string.
+Second, the default value changes from `no`/`false` to `Mandatory`. This change means that connections are encrypted by default. Previously, the driver would encrypt connections if explicitly set by the user and/or mandated by the SQL Server when the server side property `Force Encryption` was set to `yes`. To use old default behavior, include `Encrypt=Optional;` in the provider connection string, or `Use Encryption for Data=Optional;` in the `IDataInitialize` connection string.
+
+Third, the `Trust Server Certificate` option is disconnected from the `Encrypt`/`Use Encryption for Data` option. In previous versions, when `Encrypt` was `false` on the client, the `Trust Server Certificate` setting was always ignored, even if the server required encryption (the server-side `Force Encryption` setting). Starting with version 19, if either the client or the server negotiates encryption on the connection, the `Trust Server Certificate` setting is evaluated to determine whether the client validates the certificate. This behavior change causes version 19 clients that use default settings to fail to connect when the server forces encryption and uses an untrusted certificate (an insecure server configuration). Clients must change their `Trust Server Certificate` registry setting and connection option to connect to servers configured that way. For more information, see [Registry settings](features/registry-settings.md) and [Encryption and certificate validation](features/encryption-and-certificate-validation.md) 
 
 ## Driver name changes
 
-The new Microsoft OLE DB Driver 19 for SQL Server supports side by side installation with the older Microsoft OLE DB Driver for SQL Server. To be able to differentiate the drivers, the name was changed to include the major version number. To use the new driver in an application, the user must specify the new driver name. The new driver name, along with the corresponding CLSID, is specified in the updated `msoledbsql.h` header that must be included in the project. Connections through the `IDBInitialize` interface require no further changes since `MSOLEDBSQL_CLSID` will specify the CLSID of the OLE DB Driver 19 for SQL Server. Connections through the `IDataInitialize` interface must replace the value of the `Provider` keyword with `MSOLEDBSQL19` to use the Microsoft OLE DB Driver 19 for SQL Server. In graphical user interfaces such as data link properties or linked server setup in SSMS, "Microsoft OLE DB Driver 19 for SQL Server" must be selected from the list of installed providers.
+The new Microsoft OLE DB Driver 19 for SQL Server supports side by side installation with the older Microsoft OLE DB Driver for SQL Server. To be able to differentiate the drivers, the name was changed to include the major version number. To use the new driver in an application, the user must specify the new driver name. The new driver name, along with the corresponding CLSID, is specified in the updated `msoledbsql.h` header that must be included in the project. Connections through the `IDBInitialize` interface require no further changes since `MSOLEDBSQL_CLSID` specifies the CLSID of the OLE DB Driver 19 for SQL Server. Connections through the `IDataInitialize` interface must replace the value of the `Provider` keyword with `MSOLEDBSQL19` to use the Microsoft OLE DB Driver 19 for SQL Server. In graphical user interfaces such as data link properties or linked server setup in SSMS, "Microsoft OLE DB Driver 19 for SQL Server" must be selected from the list of installed providers.
 
 ## See also
 [OLE DB Driver for SQL Server](oledb-driver-for-sql-server.md)  
@@ -35,4 +37,4 @@ The new Microsoft OLE DB Driver 19 for SQL Server supports side by side installa
 [SQL Server Login Dialog Box (OLE DB)](help-topics/sql-server-login-dialog.md)  
 [Initialization and authorization properties (OLE DB driver)](ole-db-data-source-objects/initialization-and-authorization-properties.md)  
 [Registry settings](features/registry-settings.md)  
-  
+