Compartilhar via


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

  • 0x01 = On

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
(connection terminated)

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.