Exit or disconnect command (aux connection)
Note
|
As far as we’re aware, this is only sent on the aux connection.It is similar to the disconnect request from client to server for the main connection. |
Instructs the client to close the aux connection.
Int32
—p_operation
-
Operation code (
op_exit
—2
orop_disconnect
—6
)
After receiving this message, the client should close the aux connection.It’s generally only sent just before the main connection is closed.
Common requests
A few requests in the protocol have a common message format, where the operation code differs, and — possibly — the set of allowed values of other fields.
We describe the request format here, and describe the allowed values in the section for a specific request.
Generic information request
Client
Int32
—p_operation
-
Operation code (value depends on the actual operation)
Int32
—p_info_object
-
Object handle (e.g. statement, transaction, etc.)
Int32
—p_info_incarnation
-
Incarnation of object (
0
)TODO: Usage and meaning?
Buffer
—p_info_items
-
Requested information items
A list of requested information items (each byte is an information item), so-called
SingleTpb
items.Some operations may have items that do have values (e.g.isc_info_sql_sqlda_start
of [wireprotocol-statements-information]).Most values are specific to the operation.The list should end with
isc_info_end
—1
[1]. Int32
—p_info_buffer_length
-
Length of buffer available for receiving response
In protocol 10, this is a signed Int16, encoded as Int32.
In protocol 11 and higher, this is an unsigned Int32.For compatibility reasons, values greater than or equal to 4,294,901,760 (i.e. 0xFFFF_0000 or greater) are masked with 0xFFFF, so only the low 16 bits are used.
A too small value may lead to receiving a truncated buffer (last item is
isc_info_truncated
—2
instead ofisc_info_end
—1
), which necessitates requesting information again with a larger size.Some operations may have additional mechanisms to handle truncation, likeThe buffer in the response is sized to the actual length of the response (upto the declared available length), so specifying a larger than necessary size does not inflate the response on the wire.However, specifying an unnecessarily large size can lead to inefficiencies for the server.
Server
[wireprotocol-responses-generic] — on success, p_resp_data
holds the requested information.
A truncated response is considered a success, and can only be determined by parsing p_resp_data
.
Important
|
Information about how to parse the information buffer sent by the Firebird server can be found in the InterBase 6.0 documentation set |
Establishing connection
This chapter describes how to connect to a database or service.Other operations on a database or service, or information specific to connecting to a database or service are documented in [wireprotocol-databases] and [wireprotocol-services].
Attaching to a database or service
In protocol 10 and 11, attachment to a database or service is done in two steps, first identification (connect) to the server, then attach to — or creation of — a database, or attach to a service.In protocol 13, this was changed to a more complex state machine to handle multiple authentication plugins, wire protocol encryption, and database encryption key callback.
In deviation of the normal description in this documentation, and previous versions of this documentation, we will first cover the individual messages, and then explain the order and logic of message exchange.
Identification (connect)
Requests connection to the server and specifies which protocol versions the client can use.
Int32
—p_operation
-
Operation code (
op_connect
—1
) Int32
—p_cnct_operation
-
Unused, always use
0
Some implementations use
op_attach
—19
/op_service_attach
—82
for historic(?) reasons. Int32
—p_cnct_cversion
-
Connect version:
CONNECT_VERSION2
—2
user identification encoding is undefined (Firebird 1.0 — Firebird 2.5)
CONNECT_VERSION3
—3
user identification is UTF-8 encoded (since Firebird 3.0 and higher, but backwards compatible as the version wasn’t checked before Firebird 3.0)
Int32
—p_cnct_client
-
Architecture type (e.g.
arch_generic
—1
). String
—p_cnct_file
-
Database path or alias
The encoding of this is undefined, which can lead to problems with non-ASCII paths if the server and client use a different encoding.
For a service connection, this value can be the service name (
service_mgr
or empty), or the “expected database” name (same value asisc_spb_expected_db
). Int32
—p_cnct_count
-
Count of protocol versions understood (e.g.
1
). Buffer
—p_cnct_user_id
-
User identification
TODO: Needs further description
Important
|
The next block of data declares the protocol(s) that the client supports.It should be sent as many times as protocols are supported (and specified in If a client sends more than 10 (Firebird 5.0 and older) or 11 (Firebird 6.0) protocols, the surplus are ignored. |
Int32
—p_cnct_version
-
Protocol version (e.g.
PROTOCOL_VERSION10
—10
).Protocol versions greater than `10` need to be OR'ed with `0x8000` for differentiation from newer InterBase protocol versions. For example, `PROTOCOL_VERSION11` is `0x8000 | 11` or `32779` (`0x800B`)
Int32
—p_cnct_architecture
-
Architecture type (e.g.
arch_generic
—1
)It is possible to use a different architecture value, but then connection is only possible with a server of the same architecture.In addition, it changes how responses and/or data needs to be parsed or encoded (the authors don’t know the exact details).In short, use
arch_generic
. Int32
—p_cnct_min_type
-
Minimum type (e.g.
ptype_batch_send
—3
)Connection type (ptype
) valuesptype_page
—1
Page server protocol (never supported in Firebird)
ptype_rpc
—2
Simple remote procedure call (not supported since Firebird 3.0)
ptype_batch_send
—3
Batch sends, no asynchrony
ptype_out_of_band
—4
Batch sends w/ out of band notification (semantics not documented in this manual)
ptype_lazy_send
—5
Deferred packets delivery
Int32
—p_cnct_max_type
-
Maximum type (e.g.
ptype_lazy_send
—5
)If the client wants to set up wire compression, this
ptype
-code must be OR’ed withpflag_compress
(0x100
).See also Knownp_acpt_type
flags below. Int32
—p_cnct_weight
-
Preference weight (e.g.
2
).Higher values have higher preference.For equal weights, the last supported occurrence will be selected.
Simple accept
Specifies the protocol selected by the server.This response is — as far as we know — not sent if the server accepts protocol 13 or higher;then the extended Accept with data or conditional accept is sent instead.
Int32
—p_operation
-
Operation code
If operation equals op_accept
— 3
:
Int32
—p_acpt_version
-
Protocol version accepted by server
Int32
—p_acpt_architecture
-
Architecture for protocol
Int32
—p_acpt_type
-
Accepted type and additional flags.Obtain the type by masking with
0xFF
(p_acpt_type & 0xFF
).Knownp_acpt_type
flagspflag_compress
—0x100
Turn on compression
From client to server, it signals a request to use wire compression.
From server to client, it is an acknowledgement, and wire compression must be enabled after reading this entire response, but before reading or writing any other messages.pflag_win_sspi_nego
—0x200
Win_SSPI supports Negotiate security package
Only sent from server to client.
Failure response: [wireprotocol-responses-generic]
Accept with data or conditional accept
Introduced in protocol 13.
The op_accept_data
— 94
and op_cond_accept
— 98
responses start with the same fields as Simple accept, followed by additional fields for authentication and encryption purposes.
Int32
—p_operation
-
Operation code
If operation equals op_accept_data
— 94
or op_cond_accept
— 98
:
Int32
—p_acpt_version
-
Protocol version number accepted by server
Int32
—p_acpt_architecture
-
Architecture for protocol
Int32
—p_acpt_type
-
Accepted type and additional flags.
See also
p_acpt_type
inop_accept
message Buffer
—p_acpt_data
-
Authentication plugin data
String
—p_acpt_plugin
-
Authentication plugin to continue with
Int32
—p_acpt_authenticated
-
Authentication complete in a single step (
0
— false,1
— true)This will generally only be
1
ifLegacy_Auth
was tried first, though third-party authentication plugins might also authenticate in a single step. Buffer
—p_acpt_keys
-
“Keys” known by the server (used for configuring authentication and wire encryption)
Continue authentication
Introduced in protocol 13(?).
This message is used both by client and server to exchange authentication information.
Int32
—p_operation
-
Operation code (
op_cont_auth
—92
) Buffer
—p_data
-
Authentication data
String
—p_name
-
Name of the current authentication plugin
String
—p_list
-
On first authentication from client to server: list of (remaining) plugins known to the client, including the current plugin;
on subsequent authentication from client to server, or from server: emptyThe list of plugin names can be separated by space, tab, comma or semicolon.
Buffer
—p_keys
-
From client to server: empty;
from server to client: “keys” known by the server (used for configuring authentication and wire encryption)
Trusted authentication
Introduced in protocol 11.
Int32
—p_operation
-
Operation code (
op_trusted_auth
—90
) Buffer
—p_trau_data
-
Trusted authentication data
Database encryption key callback
Introduced in protocol 13.
Used to exchange information between the client and server parts of a database encryption plugin for the encryption key.The server sends this message, and the client responds with the same message type.Specifics of the message exchange depends on database encryption plugin.It is possible that multiple message of this type are exchanged.
In protocol 13, this message can only occur after authentication and — optionally — establishing wire protocol encryption.In protocol 15 and higher, it can also occur immediately after op_connect
, if the database is its own security database and is encrypted.
If this message is received before op_accept
/op_accept_data
/op_cond_accept
(so no protocol version has been confirmed yet), you need to assume protocol 15 behaviour for this message and the client response.
Int32
—p_operation
-
Operation code (
op_crypt_key_callback
—97
) Buffer
—p_cc_data
-
Crypt callback data
Additions in protocol 14
Int32
—p_cc_reply
-
Maximum expected reply size (16-bit signed integer encoded as 32-bit int)
Judging by the code in Firebird for protocol 14 and higher, this value may be negative, and should then be considered equivalent to
1
.From client to server, the reply size should be
0
.
Enable wire encryption
Introduced in protocol 13.
Enables wire encryption by telling the server the selected plugin and key type.
Client
Int32
—p_operation
-
Operation code (
op_crypt
—96
)
String
— p_plugin
Selected wire encryption plugin
String
— p_key
Selected key type
After sending this message, the client must set up wire encryption both for sending and receiving data.Subsequent messages — including the server response to this message — must be sent or received with encryption enabled.