2.2.6.4 PRELOGIN

  • Article

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.