2.2.6.4 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 with the packet data containing a PRELOGIN structure.
This message stream is also used to wrap the SSL handshake payload if encryption is needed. In this scenario, where PRELOGIN message is transporting the SSL handshake payload, the packet data is simply the raw bytes of the SSL handshake payload.
Stream Comments
The packet header is type 0x12.
A sample PRELOGIN message is shown 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 SQL Server instance ; or just %x00 UL_THREADID = ULONG ; client application thread id ; used for debugging purposes 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 The server can use the VERSION sent by the client to the server for debugging purposes or can ignore the value. The client can use the VERSION returned from the server to determine which features SHOULD be enabled or disabled. The client SHOULD do this only if it can determine whether a feature is supported by the current version of the database. |
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. |
TERMINATOR |
0xFF |
Termination token. |
Notes
PL_OPTION_TOKEN VERSION MUST be the first token sent as part of PRELOGIN.
TERMINATOR does not include length and offset specifiers.
If encryption is agreed upon during pre-login, SSL negotiation between client and server happens immediately after the PRELOGIN packet. Then, login proceeds. For additional information, see section 3.3.5.1.
A PRELOGIN message that wraps the SSL_PAYLOAD occurs only after the initial PRELOGIN message containing the PRELOGIN_OPTION and PL_OPTION_DATA information.
Encryption
During the pre-login handshake, the client and the server negotiate the wire encryption to be used. The possible encryption option values are described in the following table.
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. |
The client sends the server the value ENCRYPT_OFF, ENCRYPT_NOT_SUP, or ENCRYPT_ON. 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.
Client |
Server ENCRYPT_OFF |
Server ENCRYPT_ON |
Server 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 |
The server requires the client to behave in the manner that is described in the following table.
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) |
ENCRYPT_NOT_SUP |
Invalid response (connection terminated) |
Invalid response (connection terminated) |
Error (connection terminated) |
No encryption |
If the client and server negotiate to enable encryption, an SSL handshake takes place immediately after the initial PRELOGIN/table response message exchange. The SSL payloads MUST be transported as data in TDS 4.2 buffers with the message type set to 0x12 in the packet header. The following is an example.
-
0x 12 01 00 4e 00 00 00 00// Buffer Header 0x 16 03 01 00 &// SSL payload
This applies to SSL traffic. Upon successful completion of the SSL handshake, the client proceeds to send the LOGIN stream to the server to initiate authentication.
Instance Name
If available, the client can 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 non-empty, the server compares it to its instance name (in the server's locale) and if there is a mismatch, the server returns an INSTOPT option containing a byte with the value of 1 in the pre-login table response message. Otherwise, the server returns an INSTOPT option containing a byte with the value of 0. The client can then use this information for verification purposes and could terminate the connection if the instance name is incorrect.