Attachment to database or service
This message is used for:
-
Attaching to a database (
op_attach
—19
) — see also [wireprotocol-databases-attach] -
Creating a database (
op_create
—20
) — see also [wireprotocol-databases-create] -
Attaching to a service (
op_service_attach
—82
) — see also [wireprotocol-services-attach]
Client
Int32
—p_operation
-
Operation code (
op_attach
—19
,op_create
—20
, orop_service_attach
—82
) Int32
—p_atch_database
-
Unused, always use
0
String
—p_atch_file
-
Database path or alias, or service name (e.g.
service_mgr
).If
isc_dpb_utf8_filename
is present in the database parameter buffer below, the encoding is UTF-8, otherwise, the encoding is undefined.Theisc_dpb_utf8_filename
item is supported since Firebird 2.5. Buffer
—p_atch_dpb
-
Database or service parameter buffer
Server
In protocol 10 and 11:
In protocol 13 and higher:
It’s complicated.
Connection rejection
Server response rejecting the connection.This is usually sent if op_connect
only sent protocols the server can’t support.
Int32
— p_operation
Operation code (op_reject
— 4
)
If this message is received, the client should report error isc_connect_reject
(335544421
) or equivalent.
Connection handshake
Protocol 10 — 12
For protocol 10 — 12, the connection handshake is pretty simple.
-
Client → [wireprotocol-op-connect]
-
Server
-
←
op_accept
—3
— Server accepts and reports selected protocol, continue with step 3 -
←
op_reject
—4
— Server can’t fulfill the requested protocol-
Report error
isc_connect_reject
(335544421
) or equivalent -
Close connection
-
-
←
op_response
—9
— Error or other problem-
If
p_resp_status_vector
has an error, report it, otherwise report errorisc_login
(335544472
) or equivalent -
Close connection
-
-
-
Client → Attachment to database or service with
op_attach
,op_create
orop_service_attach
-
Server ←
op_response
—9
-
If
p_resp_status_vector
has no error or only a warning, connection is successful and can be used for other operations -
Otherwise, connection is unsuccessful
-
Report error
-
Close connection (client → [wireprotocol-connect-disconnect])
-
-
Protocol 13 and higher
For protocol 13 and higher, the handshake is more complex.
Note
|
This might not be the best way to document the connection handshake.We’re open to suggestions. |
-
Client → [wireprotocol-op-connect]
The
p_user_identification
should include:-
CNCT_plugin_name
with the current authentication plugin -
CNCT_plugin_list
with the authentication plugins supported by the client (including the current plugin);this list is separated by space, comma or semicolon -
CNCT_specific_data
with authentication plugin data (NOTE: this tag has a special “multipart” encoding as the data is generally longer than the 255 bytes supported for a single tag value)
-
-
Server
-
←
op_crypt_key_callback
—97
(read as protocol 15)-
Client → [wireprotocol-op-crypt-key-callback] (write as protocol 15) and continue with step 2
-
-
←
op_accept
—3
— Record selected protocol and type, continue with step 5 (attach) -
←
op_accept_data
—94
orop_cond_accept
—98
Record the selected protocol and type, and use that for sending and receiving subsequent messages.Enable wire compression if acknowledged by server.
If
p_acpt_authenticated == 1
, mark authentication completed-
If
op_accept_data
—94
, process the data, plugin and keys, and continue with step 5 (attach) -
If
op_cond_accept
—98
, continue with step 3 (pre-attach-auth), item forop_cond_accept
-
-
←
op_reject
—4
— Server can’t accept any of the protocols or protocol options-
report error
isc_connect_reject
(335544421
) or equivalent -
close connection
-
-
←
op_response
—9
— Error or other problem-
If
p_resp_status_vector
has an error, report it, otherwise report errorisc_login
(335544472
) or equivalent -
close connection (end of this flow)
-
-
-
Server — pre-attach auth
If the requested authentication plugin name (
p_acpt_plugin
/p_name
) is non-empty and different from the current authentication plugin name, switch to that authentication plugin.If the client cannot fulfill the server request for an authentication plugin or has no current authentication plugin, error
isc_login
(335544472
) or equivalent should be reported, and the connection closed (end of this flow)If coming from step 2, treat this as if
op_cond_accept
was just received.-
←
op_cond_accept
—98
: processp_acpt_data
,p_acpt_plugin
andp_acpt_keys
, and continue with step 4 -
←
op_cont_auth
—92
: processp_data
,p_name
(plugin name) andp_keys
, and continue with step 4 -
-
Client → [wireprotocol-op-crypt-key-callback] and continue with step 3 (pre-attach auth)
-
-
←
op_trusted_auth
—90
(not documented yet, probably only post-attach auth with protocol 11 and 12(?)) -
-
If
p_resp_statusvector
has an error, report it and close the connection (end of this flow) -
Otherwise, this signals pre-attach auth (or post-attach auth) completed
-
Process keys from
p_resp_data
-
If authentication was not previously completed, and wire encryption is not disabled, set up wire encryption
-
Client → [wireprotocol-op-crypt]
-
Set up wire encryption on incoming and outgoing stream
-
Server ←
op_response
—9
: ifp_resp_statusvector
has error, report it and close connection ([wireprotocol-connect-disconnect]), (end of flow)
-
-
Mark authentication completed
-
-
Continue with step 5 (attach);
or if used as post-attach auth, attach successfully completed (end of flow)
-
-
-
Client — pre-attach auth → [wireprotocol-op-cont-auth] with:
-
p_data
— authentication plugin data -
p_name
— current authentication plugin -
p_list
— list of remaining authentication plugins, including current plugin (separated by space, comma, or semicolon)This only needs to be sent once;for subsequent messages an empty buffer can be sent.
Continue with step 3 (Server — pre-attach auth)
-
-
Client — attach → Attachment to database or service with
op_attach
,op_create
orop_service_attach
If authentication was not yet complete at this point (as far as we know, only when
op_accept
—3
orop_accept_data
—94
was received in the previous step), and protocol 13 or higher was selected, the database or service parameter buffer should include the following tags:If protocol 13 or higher is used, the “wide” parameter buffer variant (
isc_dpb_version2
/isc_spb_version3
or higher) must be used given the size of the client authentication data (…_specific_auth_data
).-
isc_dpb_auth_plugin_list
/isc_spb_auth_plugin_list
— with remaining authentication plugins (separated by space, comma or semicolon) -
isc_dpb_auth_plugin_name
/isc_spb_auth_plugin_name
— current authentication plugin -
isc_dpb_specific_auth_data
/isc_spb_specific_auth_data
— client authentication data
It should not include any of these tags (if protocol 13 or higher):
-
isc_dpb_password
/isc_spb_password
-
isc_dpb_password_enc
/isc_spb_password_enc
-
isc_dpb_trusted_auth
/isc_spb_trusted_auth
-
-
Server/client — post-attach auth
This is the same as steps 3 and 4 (pre-attach auth), except
op_cond_accept
cannot occur, and its “Continue with step 5 (attach)” should be read as “Connection successful (end of flow)” (also noted there).If the pre-attach auth flow was previously entered, this will essentially be only an
op_response
—9
with either an error or acceptance (connection success).