firebird/firebird-mirror
firebird/firebird-mirror
8
0
Fork 1
mirror of https://github.com/FirebirdSQL/firebird.git synced 2025-01-22 16:03:03 +01:00
Code Issues

Frontported documentation

Browse Source
This commit is contained in:
Alexander Peshkov 2016-04-07 19:45:09 +03:00
parent 21fb5d8ef2
commit 128cd96c77
3 changed files with 2315 additions and 492 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
doc/README.interfaces.html
View File

@ -1,202 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE></TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice 4.1.1 (Unix)">
<META NAME="AUTHOR" CONTENT="alex ">
<META NAME="CREATED" CONTENT="20130531;10003100">
<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
<META NAME="CHANGED" CONTENT="20141113;13173600">
<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
<STYLE TYPE="text/css">
<!--
@page { size: 8.5in 11in; margin: 0.79in }
P { margin-bottom: 0.08in }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Interfaces and objects
oriented API.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Why did we decide to add a
new API in Firebird 3? There was not single reason for it. May be the
first one is limited to 16 bit size of very many integers (for
example - message size, SQL operator length, portion of BLOB data) in
existing API. This probably was enough when that API was introduced &ndash;
but puts a lot of artificial limits today. The trivial way is to add
new functions that support 32 bit variables. But this solution does
not look beautiful because we obviously need to support old API too,
i.e. have 2 sets of functions with same functionality but different
integer sizes. To make such functions differ in 'plain C' API they
should have different names, i.e. a lot of isc_some_thing() calls
will have to have isc32_some_thing() (or fb32_some_thing()) pair.
Such solution was used to support 64 bit performance counters but not
because it's good and clear, we just could not suggest better one at
that moment with at the same time great need in 64 bit counters.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>The second reason is not
so clear from the first look but it's also important. It comes from
old times when Firebird's predecessor did not support SQL &ndash;
another language was used to manage databases (you may get an idea
what it was reading QLI's help). Data was delivered between client
and server using messages with format defined at request compilation
time by BLR (binary language representation) of that request. But SQL
operator does not contain description of message format and therefore
decision was taken &ndash; surround each message with short BLR
sequence (hard to call that program) describing it's format. For a
reason they had decided to follow that rule too exactly &ndash; it
was possible to send modified BLR for each fetch of data from server,
i.e. formatting BLR was sent not only at SQL compile time. The reason
for such strange at the first glance solution was presence of one
more layer on top of that messages based API - familiar to you SQLDA
(XSQLDA). Rather obvious that manually accompanying each SQL
statement with BLR is not efficient programming style, therefore
SQLDA was invented. But it encapsulates in same object both location
of data and there format making it formally possible to change
between fetch calls not only location but format too causing need in
BLR in each message-based fetch call. And to finish with this &ndash;
changing data format between fetches was broken at network layer in
pre-Firebird times. </FONT>
</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>So what we have with calls
processing data &ndash; hard to extend (adding something to it is far
non-trivial task) and not very clear to use SQLDA, multilayer API
moving data from layer top layer and wasting time for it and &hellip;
big desire to fix that nonsense.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>There are a lot of other
reasons to change API like enhancing status vector or optimizing
dynamic library loading, but even mentioned two are enough to move to
the new one. BTW, in README.providers you will find the information
how interfaces help to use messages API easily and comfortably.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>When making any change in
software it's always desired to avoid loose of performance. And it
was performance issues that caused the choice of interfaces not
compatible with COM. To describe them I need to say a few words about
providers architecture of Firebird. The central part of it is YValve,
which is aimed on dispatching API call to correct provider, including
old providers that potentially have older interfaces than current
one. That means that to make sure that provider really has some new
API method we must (when using COM) call IUnknown method for each
fetch call. Taken together with the fact that new API calls are
sometimes added to optimize performance COM-based solution looks bad
for future Firebird versions.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Unlike COM, Firebird
interfaces support multiple versions. Version of Firebird interface
is defined in a rather native manner &ndash; it's a total number of
virtual functions in interface. And version of interface may be
upgraded! That does not mean that one gets full new functionality:
certainly that's impossible. But after upgrade virtual table is
expanded with function defined by the caller of interface upgrade,
and that function can perform minimum reasonable action &ndash; for
example in a case of providers return an error. This may seem a very
poor kind of upgrade, but at first - this is exactly what will be
done without upgrade after working with IUnknown and next &ndash;
after checking error code one can try to use other methods to do what
he wants. Certainly, not only error return may be done. Imagine that
we added something like phone number to an interface, listing users
from security database. When upgrading old interface it's OK to add a
function returning empty string as a phone number to get reasonable
behavior of old plugin.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>As an additional reason to
use non-COM interfaces it's good to notice that use of reference
counted interfaces in all cases is often an extra overhead. Some
interfaces have by definition unlimited lifetime (like IMaster &ndash;
main interfaces calling which functions one gets access to all the
rest of Firebird API), others &ndash; API strictly defined by
lifetime of parent interface, and for not multi-threaded things like
IStatus it's better to have simpler way to destroy it, i.e. dispose()
function.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT COLOR="#ff0000"><FONT SIZE=4>Careful!</FONT></FONT>
<FONT SIZE=4>An ability to upgrade interface version places one
important limit on implementation of interfaces: it should not
contain virtual functions (including virtual destructor) except those
defined in interface definition. This is because interface upgrade
process modifies table of virtual functions, and for successful
upgrade, number of functions in interface implementation should
exactly match one in its definition. Pointer to functions, missing in
interface definition but added in its implementation, may be
</FONT><FONT COLOR="#ff0000"><FONT SIZE=4>overwritten</FONT></FONT>
<FONT SIZE=4>with a pointer to function used to upgrade interface.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Discussing in details all
functions present in all interfaces is out of this document's scope.
Here I describe only hierarchy of them in general. The base of it is
IVersioned &ndash; interface that enables version upgrade. A lot of
interfaces, that do not require additional lifetime control, are
based directly on IVersioned. A sample is already mentioned IMaster
and a number of callback interfaces which lifetime must match the
lifetime of the object from which they may be used for callback.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Two interfaces, dealing
with lifetime control &ndash; IDisposable and IRefCounted. The last
one is used specially active to create other interfaces &ndash;
IPlugin is reference counted and a lot of other interfaces, used by
plugins, are reference counted too including interfaces that describe
database attachment, transaction and SQL statement.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Each plugin has one and
only one main interface IPlugin which <SPAN LANG="en">is responsible
for basic plugin's functionality (a lot of plugins have only that
interface, but this is not a requirement). </SPAN></FONT>
</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>To finish with
general interfaces hierarchy is IProvider, a kind of 'main' plugin in
Firebird API. IProvider is derived from IPlugin and implemented by
any provider (i.e. if you want to write your own provider you must
implement IProvider) and also implemented by YValve. It's
implementation from YValve which is returned to the user when
getDispatcher() function from master interface is called. IProvider
contains functions making it possible to create an attachment to
database (attach and create) or attach to services manager.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Questions and answers.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. We access new
API using IMaster. But how to get access to IMaster itself?</FONT></P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>A. This is done
using the only one new API function fb_get_master_interface(). It's
exported by fbclient library.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. It's said in
this document that COM-based interfaces are not used in order not to
work with IUnknown methods and that this is done due to performance
issues. But instead you have to upgrade interfaces. Why is it faster
than using IUnknown?</FONT></P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Upgrading
interface certainly requires some job to do. In a case when version
matches caller's requirements it's not too big &ndash; just check it,
when real upgrade is needed more CPU cycles will be spent. The main
difference with COM approach is that upgrade performed for interface
only once, after it's creation, but IUnknown methods must be called
each time we are going to call an interface with unknown version (or
that version should be stored separately and later checked). For once
upgraded Firebird interface there is absolutely no waste of time when
performing calls to it during all it's lifetime.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
</BODY>
</HTML>

183
doc/README.plugins.html
View File

@ -1,12 +1,13 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE></TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice 4.1.1 (Unix)">
<META NAME="GENERATOR" CONTENT="OpenOffice 4.1.2 (Unix)">
<META NAME="CREATED" CONTENT="20130417;16154700">
<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
<META NAME="CHANGED" CONTENT="20141113;13254700">
<META NAME="CHANGED" CONTENT="20160407;19330500">
<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
<STYLE TYPE="text/css">
<!--
@page { margin: 0.79in }
@ -29,15 +30,15 @@ parts of Firebird are implemented as plugins. </FONT>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>First of all a few words
about the term &ldquo;plugin&rdquo;. Unfortunately, it's often used
to define related but different things. Plugin is used to name:</FONT></P>
about the term “plugin”. Unfortunately, it's often used to define
related but different things. Plugin is used to name:</FONT></P>
<UL>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>dynamic library,
containing code to be loaded as plugin (often called plugin module)
and stored in $FIREBIRD/plugins directory;</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>code implementing
plugin &ndash; slightly different from the library cause single
dynamic library may contain code for more than one plugin;</FONT></P>
plugin – slightly different from the library cause single dynamic
library may contain code for more than one plugin;</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin's factory - an
object created by that code (pure virtual C++ class), creating
plugin instances on Firebird request;</FONT></P>
@ -45,21 +46,21 @@ to define related but different things. Plugin is used to name:</FONT></P>
created by factory.</FONT></P>
</UL>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>In most cases it's clear
from context what &ldquo;plugin&rdquo; do we talk about. If not it
will be clarified explicitly.</FONT></P>
from context what “plugin” do we talk about. If not it will be
clarified explicitly.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird plugin
architecture supports creation of any plugin type for any purpose &ndash;
architecture supports creation of any plugin type for any purpose –
but first of all this requires changes in Firebird code. Plugin can't
be added at any desired point &ldquo;magically&rdquo;. To be able to
have plugin (for example) encrypting database on the disk, Firebird
code should be prepared for it &ndash; must have a point from which
plugin is called. I.e. each version has a fixed set of plugins which
are supported. To add one more type, first of all Firebird code
should be modified. What DOES our plugin architecture &ndash; it
helps to make both adding new types of plugins and writing plugin
code simple and as universal between plugins as possible.</FONT></P>
be added at any desired point “magically”. To be able to have
plugin (for example) encrypting database on the disk, Firebird code
should be prepared for it – must have a point from which plugin is
called. I.e. each version has a fixed set of plugins which are
supported. To add one more type, first of all Firebird code should be
modified. What DOES our plugin architecture – it helps to make both
adding new types of plugins and writing plugin code simple and as
universal between plugins as possible.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird 3 has a following
@ -81,42 +82,41 @@ set of plugin types:</FONT></P>
plugin KeyHolder, which is used to help maintaining secret key(s)
for DbCrypt;</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>and probably the most
important kind &ndash; Provider. Firebird 3 supports providers as a
kind of plugins, which has nothing outstanding compared with others.
See README.Providers for more information about providers. </FONT>
important kind – Provider. Firebird 3 supports providers as a kind
of plugins, which has nothing outstanding compared with others. See
README.Providers for more information about providers. </FONT>
</P>
</UL>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Plugins are using a set of
special Firebird interfaces (see README.interfaces about interfaces
in Firebird). All plugin-specific interfaces are reference counted,
i.e. have explicitly controlled lifetime. Interfaces are declared in
Interfaces.h include file. There is a simple example of writing
plugin module &ndash; DbCrypt_example. It does not perform any actual
encryption &ndash; just a sample of how to write plugin. Complete
instruction of how to write plugins is out of this document's scope.
Here is provided a short list of plugin features:</FONT></P>
special Firebird interfaces (see Using_OO_API for details). All
plugin-specific interfaces are reference counted, i.e. have
explicitly controlled lifetime. Interfaces are declared in
Interfaces.h include file. There is an example of writing plugin
module – DbCrypt_example. It does not perform any actual encryption
– just a sample of how to write plugin. Complete instruction of how
to write plugins is out of this document's scope. Here is provided a
short list of plugin features:</FONT></P>
<UL>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin may be written
using any language, supporting function pointers in a
structure/record (or at least arrays of function pointers);</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>currently interfaces
description is available only for C++ language, at release time
plain-C and delphi/fpc descriptions will be present (you will need
to write your interfaces declarations generator for your language if
you need something else);</FONT></P>
description is available only for C++ and Pascal(Delphi), you will
need to write your interfaces declarations generator for your
language if you need something else;</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>like with UDFs you
are free to add any reasonable code to your plugin, but pay
attention to word &ldquo;reasonable&rdquo; - asking a question from
plugin at server's console is hardly good idea;</FONT></P>
attention to word “reasonable” - asking a question from plugin
at server's console is hardly good idea;</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>it's OK to use
Firebird API calls in your plugin if needed (for example, default
authentication server and user manager are using Firebird database
to store accounts);</FONT></P>
<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>additionally Firebird
provides a set of interfaces, helping you to configure your plugins
(certainly, you are not forced to use them &ndash; plugin is generic
(certainly, you are not forced to use them – plugin is generic
code, which may use any way of providing configuration information,
but with standard tools you get common for the rest of Firebird
configuration style and sooner of all save you efforts).</FONT></P>
@ -124,13 +124,12 @@ Here is provided a short list of plugin features:</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Configuring plugins has 2
parts &ndash; first, engine should be instructed what plugins it
should load, and next plugins themselves sometimes need some
configuration. What plugins to be loaded is defined in main
configuration file &ndash; firebird.conf for each type of plugin.
Like any other value in firebird.conf the have defaults:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthServer = Srp,
Win_Sspi</I></FONT></P>
parts – first, engine should be instructed what plugins it should
load, and next plugins themselves sometimes need some configuration.
What plugins to be loaded is defined in main configuration file –
firebird.conf for each type of plugin. Like any other value in
firebird.conf the have defaults:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthServer = Srp</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthClient = Srp,
Win_Sspi, Legacy_Auth</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>UserManager = Srp</I></FONT></P>
@ -140,7 +139,7 @@ Remote,Engine12,Loopback</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin = Arc4</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>This provides normal
operation in server, client and embedded cases. If you want to add
other plugins, you must mention them in firebird.conf &ndash; except
other plugins, you must mention them in firebird.conf – except
other this is security measure to avoid loading unknown code. But
what does for example fbtrace mean here? Is it a name of dynamic
library to load? In trivial case yes, but exact answer is more
@ -150,27 +149,27 @@ complicated.</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>As it was already
mentioned, single plugin module may implement more than single
plugin. Moreover, single plugin may have at the same time more than
one configuration &ndash; and for each configuration separate
plugin's factory is created. Each of this 3 objects (module &ndash;
implementation &ndash; factory) has it's own name. Name of a module
is a file name of dynamic library. Plugin implementation's name is
one given to it by plugin developer and hard-coded inside module.
Factory's name by default equals to plugin implementation's name (and
it's factory name which is actually used in firebird.conf). Certainly
in typical trivial case, module contains one plugin, and that plugin
works with only one configuration, and all 3 names are equal, and no
more configuration is needed &ndash; for example libEngine12.so or
Engine12.dll contains implementation of provider Engine12, and
nothing else except record </FONT>
one configuration – and for each configuration separate plugin's
factory is created. Each of this 3 objects (module – implementation
– factory) has it's own name. Name of a module is a file name of
dynamic library. Plugin implementation's name is one given to it by
plugin developer and hard-coded inside module. Factory's name by
default equals to plugin implementation's name (and it's factory name
which is actually used in firebird.conf). Certainly in typical case,
module contains one plugin, and that plugin works with only one
configuration, and all 3 names are equal, and no more configuration
is needed – for example libEngine12.so or Engine12.dll contains
implementation of provider Engine12, and nothing else except record </FONT>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Providers = Engine12</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>in firebird.conf is needed
to load it. But if you have something complex &ndash; file will help
you to have such plugin factories which you really want.</FONT></P>
to load it. But if you have something complex – configuration file
plugins.conf will help you to have such plugin factories which you
really want.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>File plugins.conf has 2
types of records &ndash; config and plugin. Plugin record is a set of
types of records – config and plugin. Plugin record is a set of
rules for plugin's loading and activating. Plugin record has the
following format:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = PlugName ##
@ -191,10 +190,10 @@ registered with name RegName and passes it configuration from config
record ConfName or config file ConfFile (config record is used if
both are given). Each parameter in this record may be missing, in
that case the default PlugName is used. The only exception is
ConfigFile &ndash; by default, file with same name as module's
dynamic library but .conf extension is used. ConfigFile is expected
to have format Key=Value (like other Firebird configuration files),
same format is used for plugin record:</FONT></P>
ConfigFile – by default, file with same name as module's dynamic
library but .conf extension is used. ConfigFile is expected to have
format Key=Value (like other Firebird configuration files), same
format is used for plugin record:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Config = ConfName</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Key1 = Value1</I></FONT></P>
@ -205,29 +204,29 @@ same format is used for plugin record:</FONT></P>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Let's have a sample.
Suppose some clients of your server trust wire encryption from one
vendor and others &ndash; from another one (and have different
licenses for appropriate client parts), but each vendor calls his
plugin BestCrypt. Certainly, first of all you have to rename
libraries to something like WC1 and WC2 &ndash; one can't have 2
files with same name in one directory. But after it, modules stop to
load automatically &ndash; they are not named BestCrypt any more. To
fix it, plugins.conf should contain something like this:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = WC1</I></FONT></P>
vendor and others – from another one (and have different licenses
for appropriate client parts), but each vendor calls his plugin
BestCrypt. Certainly, first of all you have to rename libraries to
something like Crypt1 and Crypt2 – one can't have 2 files with same
name in one directory. But after it, modules stop to load
automatically – they are not named BestCrypt any more. To fix it,
plugins.conf should contain something like this:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = Crypt1</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
BestCrypt</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = WC2</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = Crypt2</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
BestCrypt</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Module names will be
automatically set to WC1 and WC2 and found. Certainly you may add
some configuration info for plugins if needed. Also don't forget to
modify firebird.conf:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin = WC1,
WC2</I></FONT></P>
automatically set to Crypt1 and Crypt2 and found. Certainly you may
add some configuration info for plugins if needed. Also don't forget
to modify firebird.conf:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin =
Crypt1, Crypt2</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>After it server will
automatically select appropriate plugin to talk to client.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
@ -256,16 +255,16 @@ plugins is used.</FONT></P>
and Arc4 plugins mean?</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Srp implements Secure
Remote Passwords protocol which is default way of authenticating
users in Firebird 3. It has efficient password&rsquo;s length equal
to 20 bytes, resistant to most of attacks (including man in the
middle) and does not require exchanging any keys between client and
server to work. Arc4 means Alleged RC4 - an implementation of RC4
cypher. The advantage of SRP is that it can generate unique
cryptographically strong key on both client and server and it's
impossible to guess it capturing data transferred over the wire
during password validation by SRP. That key is used after SRP
handshake by Arc4, which makes wire encryption secure without need to
exchange any keys between client and server explicitly.</FONT></P>
users in Firebird 3. It has efficient password’s length equal to 20
bytes, resistant to most of attacks (including man in the middle) and
does not require exchanging any keys between client and server to
work. Arc4 means Alleged RC4 - an implementation of RC4 cypher. The
advantage of SRP is that it can generate unique cryptographically
strong key on both client and server and it's impossible to guess it
capturing data transferred over the wire during password validation
by SRP. That key is used after SRP handshake by Arc4, which makes
wire encryption secure without need to exchange any keys between
client and server explicitly.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. And what do Win_Sspi
@ -273,11 +272,11 @@ and Legacy_Auth mean?</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Windows SSPI was used
since FB 2.1 for windows trusted authentication. Legacy_Auth is
compatibility plugin. It's enabled by default on client to let it
connect to pre-FB3 servers. (Yes &ndash; it still transfers almost
plain passwords over the wire. Compatibility...) On server it works
with security database from FB 2.5, and should be avoided except
cases when you understand well what are you doing. To use Legacy_Auth
on server you should set lower level of network traffic encryption in
connect to pre-FB3 servers. (Yes – it still transfers almost plain
passwords over the wire. Compatibility...) On server it works with
security database from FB 2.5, and should be avoided except cases
when you understand well what are you doing. To use Legacy_Auth on
server you should set lower level of network traffic encryption in
firebird.conf:</FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCrypt = Enabled</I></FONT></P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>or in the worst case:</FONT></P>

2422
doc/Using_OO_API.html
View File

File diff suppressed because it is too large Load Diff