2.2.7.11 FEATUREEXTACK

Article
04/10/2023

Token Stream Name:

 FEATUREEXTACK

Token Stream Function:

Introduced in TDS 7.4, FEATUREEXTACK is used to send an optional acknowledge message to the client for features that are defined in FeatureExt. The token stream is sent only along with the LOGINACK in a Login Response message.

Token Stream Comments:

The token value is 0xAE.

Token Stream-Specific Rules:

 TokenType            =   BYTE
  
 FeatureId            =   BYTE
 FeatureAckDataLen    =   DWORD
 FeatureAckData       =   *BYTE
  
 TERMINATOR           =   %xFF       ; signal of end of feature ack data
  
 FeatureAckOpt        =   (FeatureId
                          FeatureAckDataLen
                          FeatureAckData)
                          /
                          TERMINATOR

Token Stream Definition:

 FEATUREEXTACK    =   TokenType
                      1*FeatureAckOpt

Token Stream Parameter Details

Parameter	Description
TokenType	FEATUREEXTACK_TOKEN
FeatureId	The unique identifier number of a feature. Each feature MUST use the same ID number here as in FeatureExt. If the client did not send a request for a specific feature but the FeatureId is returned, the client MUST consider it as a TDS Protocol error and MUST terminate the connection. Each feature defines its own logic if it wants to use FeatureAckOpt to send information back to the client during the login response. The features available to use by a FeatureId are defined in the following table.
FeatureAckDataLen	The length of FeatureAckData, in bytes.
FeatureAckData	The acknowledge data of a specific feature. Each feature SHOULD define its own data format in the FEATUREEXTACK token if it is selected to acknowledge the feature.

The following table describes the FeatureExtAck feature option and description.

FeatureId	FeatureExtData Description
%0x00	Reserved.
%0x01 (SESSIONRECOVERY) (introduced in TDS 7.4)	Session Recovery feature. Content is defined as follows: InitSessionStateData = SessionStateDataSet FeatureAckData = InitSessionStateData SessionStateDataSet is described in section 2.2.7.21. The length of SessionStateDataSet is specified by the corresponding FeatureAckDataLen. On a recovery connection, the client sends a login request with SessionRecoveryDataToBe. The server MUST set the session state as requested by the client. If the server cannot do so, the server MUST fail the login request and terminate the connection.
%0x02 (FEDAUTH)<51>	Whenever a login response stream is sent for a TDS connection whose login request includes a FEDAUTH FeatureExt, the server login response message stream MUST include a FEATUREEXTACK token, and the FEATUREEXTACK token stream MUST include the FEDAUTH FeatureId. The format is described below based on the bFedAuthLibrary that is used in FEDAUTH FeatureExt. When the bFedAuthLibrary is Live ID Compact Token, the format is as follows: Nonce = 32BYTE Signature = 32BYTE FeatureAckData = Nonce Signature Nonce: The client-specified nonce in PRELOGIN. Signature: The HMAC-SHA-256 [RFC6234] of the client-specified nonce, using the session key retrieved from the federated authentication context as the shared secret. When the bFedAuthLibrary is Security Token, the format is as follows: Nonce = 32BYTE FeatureAckData = [Nonce] Nonce: The client-specified nonce in PRELOGIN. This field MUST be present if the client’s PRELOGIN message included a NONCE field. Otherwise, this field MUST NOT be present.
%0x04 (COLUMNENCRYPTION) (introduced in TDS 7.4)	The presence of the COLUMNENCRYPTION FeatureExt SHOULD <52> indicate that the client is capable of performing cryptographic operations on data. The feature data is described as follows: Length = BYTE COLUMNENCRYPTION_VERSION = BYTE FeatureData = COLUMNENCRYPTION_VERSION [Length EnclaveType] COLUMNENCRYPTION_VERSION: This field defines the cryptographic protocol version that the client understands. The values of this field are as follows: 1 = The client supports column encryption without enclave computations. 2 = The client SHOULD <53> support column encryption when encrypted data require enclave computations. 3 = The client SHOULD <54> support column encryption when encrypted data require enclave computations with the additional ability to cache column encryption keys that are to be sent to the enclave and the ability to retry queries when the keys sent by the client do not match what is needed for the query to run. EnclaveType: This field is a string that SHOULD <55> be populated by the server and used by the client to identify the type of enclave that the server is configured to use. During login for the initial connection, the client can request COLUMNENCRYPTION with Length as 1 and COLUMNENCRYPTION_VERSION as either 1 or 2. When the client requests COLUMNENCRYPTION_VERSION as 2, the server MUST return COLUMNENCRYPTION_VERSION as 2 together with the value of EnclaveType, if the server contains an enclave that is configured for use. If EnclaveType is not returned and the column encryption version is returned as 2, the client driver MUST raise an error.
%0x05 (GLOBALTRANSACTIONS)<56>	Whenever a login response stream is sent for a TDS connection whose login request includes a GLOBALTRANSACTIONS FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token by including the GLOBALTRANSACTIONS FeatureId in the FEATUREEXTACK token stream. The corresponding FeatureAckData MUST then include a flag that indicates whether the server supports Global Transactions. The FeatureAckData format is as follows: IsEnabled = BYTE FeatureAckData = IsEnabled IsEnabled: Specifies whether the server supports Global Transactions. The values of this field are as follows: 0 = The server does not support Global Transactions. 1 = The server supports Global Transactions.
%0x08 (AZURESQLSUPPORT) (introduced in TDS 7.4)	The presence of the AZURESQLSUPPORT FeatureExt indicates whether failover partner login with read-only intent to Azure SQL Database MAY <57> be supported. For information about failover partner, see [MSDOCS-DBMirror]. Whenever a login response stream is sent for a TDS connection whose login request includes an AZURESQLSUPPORT FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token by setting the corresponding feature switch in Azure SQL Database. If it is included, the FEATUREEXTACK token stream MUST include the AZURESQLSUPPORT FeatureId. FeatureAckData = BYTE BYTE: The Bit 0 flag specifies whether failover partner login with read-only intent is supported. The values of this BYTE are as follows: 0 = The server does not support the AZURESQLSUPPORT feature extension. 1 = The server supports the AZURESQLSUPPORT feature extension.
%0x09 (DATACLASSIFICATION) (introduced in TDS 7.4)	Whenever a login response stream is sent for a TDS connection whose login request includes a DATACLASSIFICATION FeatureExt token, the server login response message stream SHOULD <58> be capable of optionally containing a FEATUREEXTACK token by including the DATACLASSIFICATION FeatureId in the FEATUREEXTACK token stream. The corresponding FeatureAckData MUST then include the following information that indicates whether the server supports data classification and to what extent. The FeatureAckData format is as follows: DATACLASSIFICATION_VERSION = BYTE IsEnabled = BYTE VersionSpecificData = *2147483647BYTE ; The actual length ; of data is ; FeatureAckDataLen - 2 FeatureAckData = DATACLASSIFICATION_VERSION IsEnabled VersionSpecificData DATACLASSIFICATION_VERSION: This field specifies the version number of the data classification information that is to be used for this connection. This value MUST be 1 or 2, as specified for DATACLASSIFICATION_VERSION in section 2.2.6.4. IsEnabled: This field specifies whether the server supports data classification. The values of this field are as follows: 0 = The server does not support data classification. 1 = The server supports data classification. VersionSpecificData: This field specifies which version of data classification information is returned. The values of this field are as follows: When the value of the DATACLASSIFICATION_VERSION field is 1 or 2, the response in the feature extension acknowledgement contains no version-specific data.
%0x0A (UTF8_SUPPORT) (introduced in TDS 7.4)	The presence of the UTF8_SUPPORT FeatureExtAck token in the response message stream indicates whether the server’s ability to receive and send UTF-8 encoded data SHOULD <59> be supported. Whenever a login response stream is sent for a TDS connection whose login request includes a UTF8_SUPPORT FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token. If that token is included, the FEATUREEXTACK token MUST include the UTF8_SUPPORT FeatureId and the appropriate feature acknowledgement data. The FeatureAckData format is as follows: FeatureAckData = BYTE BYTE: The Bit 0 value specifies whether the server can receive and send UTF-8 encoded data. The values of this BYTE are as follows: 0 = The server does not support the UFT8_SUPPORT feature extension. 1 = The server supports the UTF8_SUPPORT feature extension.
%0x0B (AZURESQLDNSCACHING) (introduced in TDS 7.4)	Whenever a login response stream is sent for a TDS connection that has a login request that includes an AZURESQLDNSCACHING FeatureExt token, the server login response message can optionally include this FeatureExtAck token. The contents of the token are as follows: IsSupported = BYTE FeatureAckData = IsSupported IsSupported: The Bit 0 specifies whether the server supports client DNS caching. The values of this BIT are as follows: 0 = The server does not support client DNS caching. 1 = The server supports client DNS caching. A server response with IsSupported set to 1 indicates to the client that it is safe to cache the entry. When the server responds with IsSupported set to 0, the client SHOULD NOT <60> cache the entry.
%xFF (TERMINATOR)	This option signals the end of the FeatureExtAck feature and MUST be the feature's last option.

FeatureId

FeatureExtData Description

%0x00

Reserved.

%0x01

(SESSIONRECOVERY)

(introduced in TDS 7.4)

Session Recovery feature. Content is defined as follows:

 InitSessionStateData     =   SessionStateDataSet
 FeatureAckData           =   InitSessionStateData

SessionStateDataSet is described in section 2.2.7.21. The length of SessionStateDataSet is specified by the corresponding FeatureAckDataLen.

On a recovery connection, the client sends a login request with SessionRecoveryDataToBe. The server MUST set the session state as requested by the client. If the server cannot do so, the server MUST fail the login request and terminate the connection.

%0x02

(FEDAUTH)<51>

Whenever a login response stream is sent for a TDS connection whose login request includes a FEDAUTH FeatureExt, the server login response message stream MUST include a FEATUREEXTACK token, and the FEATUREEXTACK token stream MUST include the FEDAUTH FeatureId. The format is described below based on the bFedAuthLibrary that is used in FEDAUTH FeatureExt.

When the bFedAuthLibrary is Live ID Compact Token, the format is as follows:

 Nonce                 = 32BYTE
 Signature             = 32BYTE
  
 FeatureAckData        = Nonce
                         Signature

Nonce: The client-specified nonce in PRELOGIN.

Signature: The HMAC-SHA-256 [RFC6234] of the client-specified nonce, using the session key retrieved from the federated authentication context as the shared secret.

When the bFedAuthLibrary is Security Token, the format is as follows:

 Nonce                 = 32BYTE
  
 FeatureAckData        = [Nonce]

Nonce: The client-specified nonce in PRELOGIN. This field MUST be present if the client’s PRELOGIN message included a NONCE field. Otherwise, this field MUST NOT be present.

%0x04

(COLUMNENCRYPTION)

(introduced in TDS 7.4)

The presence of the COLUMNENCRYPTION FeatureExt SHOULD <52> indicate that the client is capable of performing cryptographic operations on data. The feature data is described as follows:

 Length                          = BYTE
 COLUMNENCRYPTION_VERSION        = BYTE
  
 FeatureData                     = COLUMNENCRYPTION_VERSION
                                   [Length EnclaveType]

COLUMNENCRYPTION_VERSION: This field defines the cryptographic protocol version that the client understands. The values of this field are as follows:

1 = The client supports column encryption without enclave computations.
2 = The client SHOULD <53> support column encryption when encrypted data require enclave computations.
3 = The client SHOULD <54> support column encryption when encrypted data require enclave computations with the additional ability to cache column encryption keys that are to be sent to the enclave and the ability to retry queries when the keys sent by the client do not match what is needed for the query to run.

EnclaveType: This field is a string that SHOULD <55> be populated by the server and used by the client to identify the type of enclave that the server is configured to use. During login for the initial connection, the client can request COLUMNENCRYPTION with Length as 1 and COLUMNENCRYPTION_VERSION as either 1 or 2. When the client requests COLUMNENCRYPTION_VERSION as 2, the server MUST return COLUMNENCRYPTION_VERSION as 2 together with the value of EnclaveType, if the server contains an enclave that is configured for use. If EnclaveType is not returned and the column encryption version is returned as 2, the client driver MUST raise an error.

%0x05

(GLOBALTRANSACTIONS)<56>

Whenever a login response stream is sent for a TDS connection whose login request includes a GLOBALTRANSACTIONS FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token by including the GLOBALTRANSACTIONS FeatureId in the FEATUREEXTACK token stream. The corresponding FeatureAckData MUST then include a flag that indicates whether the server supports Global Transactions. The FeatureAckData format is as follows:

 IsEnabled             = BYTE
  
 FeatureAckData        = IsEnabled

IsEnabled: Specifies whether the server supports Global Transactions. The values of this field are as follows:

0 = The server does not support Global Transactions.
1 = The server supports Global Transactions.

%0x08

(AZURESQLSUPPORT)

(introduced in TDS 7.4)

The presence of the AZURESQLSUPPORT FeatureExt indicates whether failover partner login with read-only intent to Azure SQL Database MAY <57> be supported. For information about failover partner, see [MSDOCS-DBMirror].

Whenever a login response stream is sent for a TDS connection whose login request includes an AZURESQLSUPPORT FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token by setting the corresponding feature switch in Azure SQL Database. If it is included, the FEATUREEXTACK token stream MUST include the AZURESQLSUPPORT FeatureId.

 FeatureAckData        = BYTE

BYTE: The Bit 0 flag specifies whether failover partner login with read-only intent is supported. The values of this BYTE are as follows:

0 = The server does not support the AZURESQLSUPPORT feature extension.
1 = The server supports the AZURESQLSUPPORT feature extension.

%0x09

(DATACLASSIFICATION)

(introduced in TDS 7.4)

Whenever a login response stream is sent for a TDS connection whose login request includes a DATACLASSIFICATION FeatureExt token, the server login response message stream SHOULD <58> be capable of optionally containing a FEATUREEXTACK token by including the DATACLASSIFICATION FeatureId in the FEATUREEXTACK token stream. The corresponding FeatureAckData MUST then include the following information that indicates whether the server supports data classification and to what extent. The FeatureAckData format is as follows:

 DATACLASSIFICATION_VERSION   = BYTE 
 IsEnabled                    = BYTE
 VersionSpecificData   = *2147483647BYTE ; The actual length
                                         ; of data is 
                                         ; FeatureAckDataLen - 2
  
 FeatureAckData               = DATACLASSIFICATION_VERSION
                                IsEnabled
                                VersionSpecificData

DATACLASSIFICATION_VERSION: This field specifies the version number of the data classification information that is to be used for this connection. This value MUST be 1 or 2, as specified for DATACLASSIFICATION_VERSION in section 2.2.6.4.

IsEnabled: This field specifies whether the server supports data classification. The values of this field are as follows:

0 = The server does not support data classification.
1 = The server supports data classification.

VersionSpecificData: This field specifies which version of data classification information is returned. The values of this field are as follows:

When the value of the DATACLASSIFICATION_VERSION field is 1 or 2, the response in the feature extension acknowledgement contains no version-specific data.

%0x0A

(UTF8_SUPPORT)

(introduced in TDS 7.4)

The presence of the UTF8_SUPPORT FeatureExtAck token in the response message stream indicates whether the server’s ability to receive and send UTF-8 encoded data SHOULD <59> be supported.

Whenever a login response stream is sent for a TDS connection whose login request includes a UTF8_SUPPORT FeatureExt token, the server login response message stream can optionally include a FEATUREEXTACK token. If that token is included, the FEATUREEXTACK token MUST include the UTF8_SUPPORT FeatureId and the appropriate feature acknowledgement data. The FeatureAckData format is as follows:

 FeatureAckData               = BYTE

BYTE: The Bit 0 value specifies whether the server can receive and send UTF-8 encoded data. The values of this BYTE are as follows:

0 = The server does not support the UFT8_SUPPORT feature extension.
1 = The server supports the UTF8_SUPPORT feature extension.

%0x0B

(AZURESQLDNSCACHING)

(introduced in TDS 7.4)

Whenever a login response stream is sent for a TDS connection that has a login request that includes an AZURESQLDNSCACHING FeatureExt token, the server login response message can optionally include this FeatureExtAck token. The contents of the token are as follows:

 IsSupported                  = BYTE
 FeatureAckData               = IsSupported

IsSupported: The Bit 0 specifies whether the server supports client DNS caching. The values of this BIT are as follows:

0 = The server does not support client DNS caching.
1 = The server supports client DNS caching.

A server response with IsSupported set to 1 indicates to the client that it is safe to cache the entry. When the server responds with IsSupported set to 0, the client SHOULD NOT <60> cache the entry.

%xFF

(TERMINATOR)

This option signals the end of the FeatureExtAck feature and MUST be the feature's last option.

2.2.7.11 FEATUREEXTACK

Additional resources