2.2.6.5 PRELOGIN
Stream Name:
-
PRELOGIN
Stream Function:
A message sent by the client to set up context for login. The server responds to a client PRELOGIN message with a message of packet header type 0x04 and the packet data containing a PRELOGIN structure.
In TDS 7.x, this message stream is also used to wrap the SSL handshake payload, if encryption is needed. In this scenario, where the PRELOGIN message is transporting the SSL handshake payload, the packet data is simply the raw bytes of the SSL handshake payload.
Stream Comments:
Packet header type 0x12.
A sample PRELOGIN message is in section 4.1.
Stream-Specific Rules:
-
UL_VERSION = ULONG ; version of the sender US_SUBBUILD = USHORT ; sub-build number of the sender B_FENCRYPTION = BYTE B_INSTVALIDITY = *BYTE %x00 ; name of the instance ; of the database server that supports SQL ; or just %x00 UL_THREADID = ULONG ; client application thread id ; used for debugging purposes B_MARS = BYTE ; sender requests MARS support GUID_CONNID = 16BYTE ; client application trace id ; used for debugging purposes ; introduced in TDS 7.4 GUID_ActivityID = 16BYTE ; client application activity id ; used for debugging purposes ; introduced in TDS 7.4 ActivitySequence = ULONG ; client application activity sequence ; used for debugging purposes ; introduced in TDS 7.4 ACTIVITYID = GUID_ActivityID ; client application activity id token ActivitySequence ; used for debugging purposes ; introduced in TDS 7.4 B_FEDAUTHREQUIRED = BYTE ; authentication library requirement of the sender ; when using Integrated Authentication identity ; introduced in TDS 7.4 NONCE = 32BYTE ; nonce to be encrypted by using session key from ; federated authentication handshake TERMINATOR = %xFF ; signals end of PRELOGIN message PL_OPTION_DATA = *BYTE ; actual data for the option PL_OFFSET = USHORT ; big endian PL_OPTION_LENGTH = USHORT ; big endian PL_OPTION_TOKEN = BYTE ; token value representing the option PRELOGIN_OPTION = (PL_OPTION_TOKEN PL_OFFSET PL_OPTION_LENGTH) / TERMINATOR SSL_PAYLOAD = *BYTE ; SSL handshake raw payload
Stream Definition:
-
PRELOGIN = (*PRELOGIN_OPTION *PL_OPTION_DATA) / SSL_PAYLOAD
PL_OPTION_TOKEN is described in the following table.
|
PL_OPTION_TOKEN |
Value |
Description |
|---|---|---|
|
VERSION |
0x00 |
PL_OPTION_DATA = UL_VERSION US_SUBBUILD UL_VERSION is composed of major version (1 byte), minor version (1 byte), and build number (2 bytes). It is represented in network byte order (big-endian). On x86 platforms, UL_VERSION is prepared as follows: VER_SQL_BUILD = USHORT US_BUILD = SwapBytes (VER_SQL_BUILD); VER_SQL_MINOR = USHORT VER_SQL_MAJOR = USHORT UL_VERSION = US_BUILD / VER_SQL_MINOR / VER_SQL_MAJOR SwapBytes is used to swap bytes. For example, SwapBytes(0x106A)= 0x6A10. |
|
ENCRYPTION |
0x01 |
PL_OPTION_DATA = B_FENCRYPTION |
|
INSTOPT |
0x02 |
PL_OPTION_DATA = B_INSTVALIDITY |
|
THREADID |
0x03 |
PL_OPTION_DATA = UL_THREADID This value SHOULD be empty when being sent from the server to the client. |
|
MARS |
0x04 |
PL_OPTION_DATA = B_MARS
|
|
TRACEID |
0x05 |
PL_OPTION_DATA = GUID_CONNID ACTIVITYID Introduced in TDS 7.4. |
|
FEDAUTHREQUIRED<33> |
0x06 |
PL_OPTION_DATA = B_FEDAUTHREQUIRED Introduced in TDS 7.4. |
|
NONCEOPT |
0x07 |
PL_OPTION_DATA = NONCE The client MUST send this option if it expects to be able to use federated authentication with Live ID Compact Token to authenticate to the server on this connection. If the server understands the NONCEOPT option and the client sends the option, the server MUST respond with its own NONCEOPT. |
|
TERMINATOR |
0xFF |
Termination token. |
Notes
PL_OPTION_TOKEN VERSION is a required token, and it MUST be the first token sent as part of PRELOGIN. If this is not the case, the connection is closed by the server.
TERMINATOR is a required token, and it MUST be the last token of PRELOGIN_OPTION. TERMINATOR does not include length and bits specifying offset.
In TDS 7.x, if encryption is agreed upon during pre-login, SSL negotiation between client and server happens immediately after the PRELOGIN packet. Then login proceeds. For more information, see section 3.3.5.1.
In TDS 7.x, a PRELOGIN message wrapping the SSL_PAYLOAD occurs only after the initial PRELOGIN message containing the PRELOGIN_OPTION and PL_OPTION_DATA information is sent.
Encryption
Applies to only TDS 7.x
In TDS 8.0, because the TLS session is already established, the encryption value that is sent by the client is ignored.
During the Pre-Login handshake, the client and the server negotiate the wire encryption to be used. The encryption option values are as follows.
|
Setting |
Value |
Description |
|---|---|---|
|
ENCRYPT_OFF |
0x00 |
Encryption is available but off. |
|
ENCRYPT_ON |
0x01 |
Encryption is available and on. |
|
ENCRYPT_NOT_SUP |
0x02 |
Encryption is not available. |
|
ENCRYPT_REQ |
0x03 |
Encryption is required. |
|
ENCRYPT_EXT |
0x20 |
This bit is reserved.<34> |
|
ENCRYPT_CLIENT_CERT |
0X80 (ENCRYPT_OFF) or 0X81 (ENCRYPT_ON) or 0x83 (ENCRYPT_REQ) |
Certificate-based authentication is requested by the client. The client certificate SHOULD<35> be used to authenticate the user in place of username and password only in specific extensibility scenarios where a loopback connection from an external script is requested. |
The client sends the server the value ENCRYPT_OFF, ENCRYPT_NOT_SUP, or ENCRYPT_ON. The client can also request certificate-based authentication by sending the value ENCRYPT_CLIENT_CERT with ENCRYPT_OFF, ENCRYPT_ON, or ENCRYPT_REQ. The connection is terminated if the client sends ENCRYPT_CLIENT_CERT with ENCRYPT_NOT_SUP.
Depending upon whether the server has encryption available and enabled, the server responds with an ENCRYPTION value in the response according to the following table.
|
Value sent by client |
Value returned by server when server is set to ENCRYPT_OFF |
Value returned by server when server is set to ENCRYPT_ON |
Value returned by server when server is set to ENCRYPT_NOT_SUP |
|---|---|---|---|
|
ENCRYPT_OFF |
ENCRYPT_OFF |
ENCRYPT_REQ |
ENCRYPT_NOT_SUP |
|
ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_NOT_SUP (connection terminated) |
|
ENCRYPT_NOT_SUP |
ENCRYPT_NOT_SUP |
ENCRYPT_REQ (connection terminated) |
ENCRYPT_NOT_SUP |
|
ENCRYPT_REQ |
ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_NOT_SUP (connection terminated) |
|
ENCRYPT_CLIENT_CERT | ENCRYPT_OFF |
ENCRYPT_OFF |
ENCRYPT_REQ |
ENCRYPT_NOT_SUP (connection terminated) |
|
ENCRYPT_CLIENT_CERT | ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_NOT_SUP (connection terminated) |
|
ENCRYPT_CLIENT_CERT | ENCRYPT_NOT_SUP |
ENCRYPT_REQ |
ENCRYPT_REQ (connection terminated) |
ENCRYPT_REQ (connection terminated) |
|
ENCRYPT_CLIENT_CERT | ENCRYPT_REQ |
ENCRYPT_ON |
ENCRYPT_ON |
ENCRYPT_NOT_SUP (connection terminated) |
Assuming that the client is capable of encryption, the server requires the client to behave in the following manner.
|
Client |
Value returned from server is ENCRYPT_OFF |
Value returned from server is ENCRYPT_ON |
Value returned from server is ENCRYPT_REQ |
Value returned from server is ENCRYPT_NOT_SUP |
|---|---|---|---|---|
|
ENCRYPT_OFF |
Encrypt login packet only |
Encrypt entire connection |
Encrypt entire connection |
No encryption |
|
ENCRYPT_ON |
Error (connection terminated) |
Encrypt entire connection |
Encrypt entire connection |
Error (connection terminated) |
If client and server negotiate to enable encryption or if the client has requested certificate-based authentication, an SSL handshake takes place immediately after the initial PRELOGIN/table response message exchange. If ENCRYPT_CLIENT_CERT is specified, the certificate is exchanged in this handshake. The SSL payloads MUST be transported as data in TDS packets with the message type set to 0x12 in the packet header. For example:
-
0x 12 01 00 4e 00 00 00 00// Packet Header 0x 16 03 01 00 &// SSL payload
This applies to SSL traffic. The client sends the SSL handshake payloads as data in a PRELOGIN message. For TDS versions earlier than TDS 7.2, the server SHOULD send the SSL handshake payloads as data in a table response message (0x04). For TDS 7.2, TDS 7.3, and TDS 7.4, the server SHOULD send the SSL handshake payloads as data in a PRELOGIN message. Upon successful completion of the SSL handshake, the client proceeds to send the LOGIN7 stream to the server to initiate authentication.
Instance Name
If available, the client SHOULD send the server the name of the instance to which it is connecting as a NULL-terminated multi-byte character set (MBCS) string in the INSTOPT option. If the string is empty or is case-insensitively equal, by using the server's locale for comparison to either the server's instance name or "MSSQLServer", the server SHOULD<36> return an INSTOPT containing a byte with the value 0 to indicate that the client's INSTOPT matches the server's instance. Otherwise, the server SHOULD return an INSTOPT containing a byte with the value of 1. The client SHOULD use the INSTOPT value from the server's PRELOGIN response for verification purposes and SHOULD terminate the connection if the INSTOPT option has the value 1.
Authentication Requirement
When the client wants to use either SSPI or federated authentication to determine the authentication mechanism but does not necessarily have a requirement as to which library to use, the client can use the FEDAUTHREQUIRED option to negotiate whether the server has a requirement for a given authentication mechanism. If the client's PRELOGIN request message contains the FEDAUTHREQUIRED option, the client MUST specify 0x01 as the B_FEDAUTHREQUIRED value. If the server supports the FEDAUTHREQUIRED option, the server MUST respond with a FEDAUTHREQUIRED option that has either 0x00 or 0x01 as the B_FEDAUTHREQUIRED value. For the choice between SSPI and federated authentication, a value of 0x00 indicates that the server does not require federated authentication as the authentication mechanism, and a value of 0x01 indicates that the server requires federated authentication as the authentication mechanism. However, this mechanism is used only for capability negotiation when choosing between SSPI and federated authentication and does not necessarily bind the actual authentication mechanism that is used.