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_DATA = UL_VERSION
                   US_SUBBUILD

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

PL_OPTION_DATA =   B_FENCRYPTION

PL_OPTION_DATA =   B_INSTVALIDITY

PL_OPTION_DATA =   UL_THREADID

PL_OPTION_DATA = B_MARS

PL_OPTION_DATA = GUID_CONNID ACTIVITYID

PL_OPTION_DATA = B_FEDAUTHREQUIRED

PL_OPTION_DATA = NONCE

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.

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.

Assuming that the client is capable of encryption, the server requires the client to behave in the following manner.

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.