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.

This message stream is also used to wrap 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:

  • 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
 ACTIVITYID        =   20BYTE        ; client application activity id
                                     ; used for debugging purposes
 B_FEDAUTHREQUIRED =   BYTE          ; authentication library requirement of the sender 
                                     ; when using Integrated Authentication identity
 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 represented in network byte order (big-endian).

The server SHOULD use the VERSION sent by the client to the server. The client SHOULD use the version returned from the server to determine which features are enabled or disabled. The client SHOULD do this only if it is known that this feature is supported by that version of the database.<27>

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
  • 0x00 = Off

  • 0x01 = On

TRACEID

0x05

PL_OPTION_DATA = GUID_CONNID ACTIVITYID

FEDAUTHREQUIRED<28>

0x06

PL_OPTION_DATA = B_FEDAUTHREQUIRED

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.

  • 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.

  • A PRELOGIN message wrapping the SSL_PAYLOAD will occur 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 will negotiate the wire encryption to be used. The possible 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.

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

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, an SSL handshake takes place immediately after the initial PRELOGIN/table response message exchange. The SSL payloads MUST be transported as data in TDS buffers with the message type set to 0x12 in the packet header. For example:

 0x 12 01 00 4e 00 00 00 00// Buffer 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, 7.3, and 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 will proceed 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<29> 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.

Show: