صفحهٔ اصلی گشت‌و‌گذار راهنما
ورود
FirebirdDB
/
firebird
mirrorاز https://github.com/FirebirdSQL/firebird.git
2
0
انشعاب 0
پرونده‌ها مشکلات 0 ویکی
شاخه: work/libcds_win_arm64
شاخه‌ها تگ‌ها
firebird
/
doc
/
README.plugins.html

README.plugins.html 15 KB
لینک دائمی تاريخچه خام

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287 
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
    2. 

  2. <HTML>
    3. 

  3. <HEAD>
    4. 

  4. 	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
    5. 

  5. 	<TITLE></TITLE>
    6. 

  6. 	<META NAME="GENERATOR" CONTENT="OpenOffice 4.1.2  (Unix)">
    7. 

  7. 	<META NAME="CREATED" CONTENT="20130417;16154700">
    8. 

  8. 	<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
    9. 

  9. 	<META NAME="CHANGED" CONTENT="20160407;19330500">
    10. 

  10. 	<META NAME="CHANGEDBY" CONTENT="Alex Peshkoff">
    11. 

  11. 	<STYLE TYPE="text/css">
    12. 

  12. 	<!--
    13. 

  13. 		@page { margin: 0.79in }
    14. 

  14. 		P { margin-bottom: 0.08in }
    15. 

  15. 	-->
    16. 

  16. 	</STYLE>
    17. 

  17. </HEAD>
    18. 

  18. <BODY LANG="en-US" DIR="LTR">
    19. 

  19. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird plugins.</FONT></P>
    20. 

  20. <P STYLE="margin-bottom: 0in"><BR>
    21. 

  21. </P>
    22. 

  22. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Since version 3, Firebird
    23. 

  23. supports plugins architecture. This means that for a number of
    24. 

  24. predefined points in Firebird code, user can write his own fragment
    25. 

  25. of code which will be executed when needed. Plugin is not necessarily
    26. 

  26. always written by user - Firebird already has a number of plugins
    27. 

  27. which are its native part. Moreover, as you will see later, some core
    28. 

  28. parts of Firebird are implemented as plugins. </FONT>
    29. 

  29. </P>
    30. 

  30. <P STYLE="margin-bottom: 0in"><BR>
    31. 

  31. </P>
    32. 

  32. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>First of all a few words
    33. 

  33. about the term “plugin”. Unfortunately, it's often used to define
    34. 

  34. related but different things. Plugin is used to name:</FONT></P>
    35. 

  35. <UL>
    36. 

  36. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>dynamic library,
    37. 

  37. 	containing code to be loaded as plugin (often called plugin module)
    38. 

  38. 	and stored in $FIREBIRD/plugins directory;</FONT></P>
    39. 

  39. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>code implementing
    40. 

  40. 	plugin – slightly different from the library cause single dynamic
    41. 

  41. 	library may contain code for more than one plugin;</FONT></P>
    42. 

  42. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin's factory - an
    43. 

  43. 	object created by that code (pure virtual C++ class), creating
    44. 

  44. 	plugin instances on Firebird request;</FONT></P>
    45. 

  45. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>instance of plugin,
    46. 

  46. 	created by factory.</FONT></P>
    47. 

  47. </UL>
    48. 

  48. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>In most cases it's clear
    49. 

  49. from context what “plugin” do we talk about. If not it will be
    50. 

  50. clarified explicitly.</FONT></P>
    51. 

  51. <P STYLE="margin-bottom: 0in"><BR>
    52. 

  52. </P>
    53. 

  53. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird plugin
    54. 

  54. architecture supports creation of any plugin type for any purpose –
    55. 

  55. but first of all this requires changes in Firebird code. Plugin can't
    56. 

  56. be added at any desired point “magically”. To be able to have
    57. 

  57. plugin (for example) encrypting database on the disk, Firebird code
    58. 

  58. should be prepared for it – must have a point from which plugin is
    59. 

  59. called. I.e. each version has a fixed set of plugins which are
    60. 

  60. supported. To add one more type, first of all Firebird code should be
    61. 

  61. modified. What DOES our plugin architecture – it helps to make both
    62. 

  62. adding new types of plugins and writing plugin code simple and as
    63. 

  63. universal between plugins as possible.</FONT></P>
    64. 

  64. <P STYLE="margin-bottom: 0in"><BR>
    65. 

  65. </P>
    66. 

  66. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird 3 has a following
    67. 

  67. set of plugin types:</FONT></P>
    68. 

  68. <UL>
    69. 

  69. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>user authentication
    70. 

  70. 	related: AuthServer (validates user's credentials on server when use
    71. 

  71. 	logins), AuthClient (prepares credentials to be passed over the
    72. 

  72. 	wire) and AuthUserManagement (maintains a list of users on a server
    73. 

  73. 	in a form, known to AuthServer);</FONT></P>
    74. 

  74. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>ExternalEngine
    75. 

  75. 	controls use of various engines, see README.external_routines;</FONT></P>
    76. 

  76. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>Trace plugin is known
    77. 

  77. 	from Firebird 2.5, but a way how it interacts with engine was
    78. 

  78. 	changed to match new generic rules; </FONT>
    79. 

  79. 	</P>
    80. 

  80. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>encrypting plugins
    81. 

  81. 	are for network (WireCrypt) and disk (DbCrypt), there is also helper
    82. 

  82. 	plugin KeyHolder, which is used to help maintaining secret key(s)
    83. 

  83. 	for DbCrypt;</FONT></P>
    84. 

  84. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>and probably the most
    85. 

  85. 	important kind – Provider. Firebird 3 supports providers as a kind
    86. 

  86. 	of plugins, which has nothing outstanding compared with others. See
    87. 

  87. 	README.Providers for more information about providers. </FONT>
    88. 

  88. 	</P>
    89. 

  89. </UL>
    90. 

  90. <P STYLE="margin-bottom: 0in"><BR>
    91. 

  91. </P>
    92. 

  92. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Plugins are using a set of
    93. 

  93. special Firebird interfaces (see Using_OO_API for details). All
    94. 

  94. plugin-specific interfaces are reference counted, i.e. have
    95. 

  95. explicitly controlled lifetime. Interfaces are declared in
    96. 

  96. Interfaces.h include file. There is an example of writing plugin
    97. 

  97. module – fbSampleDbCrypt. It does not perform any actual encryption
    98. 

  98. – just a sample of how to write plugin. Complete instruction of how
    99. 

  99. to write plugins is out of this document's scope. Here is provided a
    100. 

  100. short list of plugin features:</FONT></P>
    101. 

  101. <UL>
    102. 

  102. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin may be written
    103. 

  103. 	using any language, supporting function pointers in a
    104. 

  104. 	structure/record (or at least arrays of function pointers);</FONT></P>
    105. 

  105. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>currently interfaces
    106. 

  106. 	description is available only for C++ and Pascal(Delphi), you will
    107. 

  107. 	need to write your interfaces declarations generator for your
    108. 

  108. 	language if you need something else;</FONT></P>
    109. 

  109. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>like with UDFs you
    110. 

  110. 	are free to add any reasonable code to your plugin, but pay
    111. 

  111. 	attention to word “reasonable” - asking a question from plugin
    112. 

  112. 	at server's console is hardly good idea;</FONT></P>
    113. 

  113. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>it's OK to use
    114. 

  114. 	Firebird API calls in your plugin if needed (for example, default
    115. 

  115. 	authentication server and user manager are using Firebird database
    116. 

  116. 	to store accounts);</FONT></P>
    117. 

  117. 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>additionally Firebird
    118. 

  118. 	provides a set of interfaces, helping you to configure your plugins
    119. 

  119. 	(certainly, you are not forced to use them – plugin is generic
    120. 

  120. 	code, which may use any way of providing configuration information,
    121. 

  121. 	but with standard tools you get common for the rest of Firebird
    122. 

  122. 	configuration style and sooner of all save you efforts).</FONT></P>
    123. 

  123. </UL>
    124. 

  124. <P STYLE="margin-bottom: 0in"><BR>
    125. 

  125. </P>
    126. 

  126. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Configuring plugins has 2
    127. 

  127. parts – first, engine should be instructed what plugins it should
    128. 

  128. load, and next plugins themselves sometimes need some configuration.
    129. 

  129. What plugins to be loaded is defined in main configuration file –
    130. 

  130. firebird.conf for each type of plugin. Like any other value in
    131. 

  131. firebird.conf the have defaults:</FONT></P>
    132. 

  132. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthServer = Srp</I></FONT></P>
    133. 

  133. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthClient = Srp,
    134. 

  134. Win_Sspi, Legacy_Auth</I></FONT></P>
    135. 

  135. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>UserManager = Srp</I></FONT></P>
    136. 

  136. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>TracePlugin = fbtrace</I></FONT></P>
    137. 

  137. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Providers =
    138. 

  138. Remote,Engine14,Loopback</I></FONT></P>
    139. 

  139. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin = Arc4</I></FONT></P>
    140. 

  140. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>This provides normal
    141. 

  141. operation in server, client and embedded cases. If you want to add
    142. 

  142. other plugins, you must mention them in firebird.conf – except
    143. 

  143. other this is security measure to avoid loading unknown code. But
    144. 

  144. what does for example fbtrace mean here? Is it a name of dynamic
    145. 

  145. library to load? In trivial case yes, but exact answer is more
    146. 

  146. complicated.</FONT></P>
    147. 

  147. <P STYLE="margin-bottom: 0in"><BR>
    148. 

  148. </P>
    149. 

  149. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>As it was already
    150. 

  150. mentioned, single plugin module may implement more than single
    151. 

  151. plugin. Moreover, single plugin may have at the same time more than
    152. 

  152. one configuration – and for each configuration separate plugin's
    153. 

  153. factory is created. Each of this 3 objects (module – implementation
    154. 

  154. – factory) has it's own name. Name of a module is a file name of
    155. 

  155. dynamic library. Plugin implementation's name is one given to it by
    156. 

  156. plugin developer and hard-coded inside module. Factory's name by
    157. 

  157. default equals to plugin implementation's name (and it's factory name
    158. 

  158. which is actually used in firebird.conf). Certainly in typical case,
    159. 

  159. module contains one plugin, and that plugin works with only one
    160. 

  160. configuration, and all 3 names are equal, and no more configuration
    161. 

  161. is needed – for example libEngine14.so or Engine14.dll contains
    162. 

  162. implementation of provider Engine14, and nothing else except record </FONT>
    163. 

  163. </P>
    164. 

  164. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Providers = Engine14</FONT></P>
    165. 

  165. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>in firebird.conf is needed
    166. 

  166. to load it. But if you have something complex – configuration file
    167. 

  167. plugins.conf will help you to have such plugin factories which you
    168. 

  168. really want.</FONT></P>
    169. 

  169. <P STYLE="margin-bottom: 0in"><BR>
    170. 

  170. </P>
    171. 

  171. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>File plugins.conf has 2
    172. 

  172. types of records – config and plugin. Plugin record is a set of
    173. 

  173. rules for plugin's loading and activating. Plugin record has the
    174. 

  174. following format:</FONT></P>
    175. 

  175. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = PlugName ##
    176. 

  176. this is name to be referenced in firebird.conf</I></FONT></P>
    177. 

  177. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
    178. 

  178. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Module = LibName ##
    179. 

  179. name of dynamic library</I></FONT></P>
    180. 

  180. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName = RegName
    181. 

  181. ## name given to plugin by it's developer</I></FONT></P>
    182. 

  182. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Config = ConfName ##
    183. 

  183. name of config record to be used</I></FONT></P>
    184. 

  184. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>ConfigFile = ConfFile
    185. 

  185. ## name of a file, containing plugin's configuration</I></FONT></P>
    186. 

  186. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
    187. 

  187. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>i.e. when plugin PlugName
    188. 

  188. is needed Firebird loads library LibName, finds in it plugin
    189. 

  189. registered with name RegName and passes it configuration from config
    190. 

  190. record ConfName or config file ConfFile (config record is used if
    191. 

  191. both are given). Each parameter in this record may be missing, in
    192. 

  192. that case the default PlugName is used. The only exception is
    193. 

  193. ConfigFile – by default, file with same name as module's dynamic
    194. 

  194. library but .conf extension is used. ConfigFile is expected to have
    195. 

  195. format Key=Value (like other Firebird configuration files), same
    196. 

  196. format is used for plugin record:</FONT></P>
    197. 

  197. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Config = ConfName</I></FONT></P>
    198. 

  198. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
    199. 

  199. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Key1 = Value1</I></FONT></P>
    200. 

  200. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Key2 = Value2</I></FONT></P>
    201. 

  201. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>...</I></FONT></P>
    202. 

  202. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
    203. 

  203. <P STYLE="margin-bottom: 0in"><BR>
    204. 

  204. </P>
    205. 

  205. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Let's have a sample.
    206. 

  206. Suppose some clients of your server trust wire encryption from one
    207. 

  207. vendor and others – from another one (and have different licenses
    208. 

  208. for appropriate client parts), but each vendor calls his plugin
    209. 

  209. BestCrypt. Certainly, first of all you have to rename libraries to
    210. 

  210. something like Crypt1 and Crypt2 – one can't have 2 files with same
    211. 

  211. name in one directory. But after it, modules stop to load
    212. 

  212. automatically – they are not named BestCrypt any more. To fix it,
    213. 

  213. plugins.conf should contain something like this:</FONT></P>
    214. 

  214. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = Crypt1</I></FONT></P>
    215. 

  215. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
    216. 

  216. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
    217. 

  217. BestCrypt</I></FONT></P>
    218. 

  218. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
    219. 

  219. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = Crypt2</I></FONT></P>
    220. 

  220. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
    221. 

  221. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
    222. 

  222. BestCrypt</I></FONT></P>
    223. 

  223. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
    224. 

  224. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Module names will be
    225. 

  225. automatically set to Crypt1 and Crypt2 and found. Certainly you may
    226. 

  226. add some configuration info for plugins if needed. Also don't forget
    227. 

  227. to modify firebird.conf:</FONT></P>
    228. 

  228. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin =
    229. 

  229. Crypt1, Crypt2</I></FONT></P>
    230. 

  230. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>After it server will
    231. 

  231. automatically select appropriate plugin to talk to client.</FONT></P>
    232. 

  232. <P STYLE="margin-bottom: 0in"><BR>
    233. 

  233. </P>
    234. 

  234. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Another sample may be
    235. 

  235. found in distributed with Firebird plugins.conf. One of standard
    236. 

  236. plugins, UDR, is written to use non-default configuration. Therefore
    237. 

  237. module name and one configuration parameter are given explicitly.</FONT></P>
    238. 

  238. <P STYLE="margin-bottom: 0in"><BR>
    239. 

  239. </P>
    240. 

  240. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Questions and answers.</FONT></P>
    241. 

  241. <P STYLE="margin-bottom: 0in"><BR>
    242. 

  242. </P>
    243. 

  243. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. There are plugins named
    244. 

  244. Remote, Loopback, Arc4 in default configuration, but no libraries
    245. 

  245. with such names. How do they work?</FONT></P>
    246. 

  246. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. That are so-called
    247. 

  247. 'built-in' plugins. They are built into fbclient library, and
    248. 

  248. therefore are always present. Arrival of such plugins is due to old
    249. 

  249. ability to distribute windows Firebird client as single dll. It was
    250. 

  250. decided to keep such feature at least for a case when standard set of
    251. 

  251. plugins is used.</FONT></P>
    252. 

  252. <P STYLE="margin-bottom: 0in"><BR>
    253. 

  253. </P>
    254. 

  254. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. What do names of Srp
    255. 

  255. and Arc4 plugins mean?</FONT></P>
    256. 

  256. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Srp implements Secure
    257. 

  257. Remote Passwords protocol which is default way of authenticating
    258. 

  258. users in Firebird 3. It has efficient password’s length equal to 20
    259. 

  259. bytes, resistant to most of attacks (including man in the middle) and
    260. 

  260. does not require exchanging any keys between client and server to
    261. 

  261. work. Arc4 means Alleged RC4 - an implementation of RC4 cypher. The
    262. 

  262. advantage of SRP is that it can generate unique cryptographically
    263. 

  263. strong key on both client and server and it's impossible to guess it
    264. 

  264. capturing data transferred over the wire during password validation
    265. 

  265. by SRP. That key is used after SRP handshake by Arc4, which makes
    266. 

  266. wire encryption secure without need to exchange any keys between
    267. 

  267. client and server explicitly.</FONT></P>
    268. 

  268. <P STYLE="margin-bottom: 0in"><BR>
    269. 

  269. </P>
    270. 

  270. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. And what do Win_Sspi
    271. 

  271. and Legacy_Auth mean?</FONT></P>
    272. 

  272. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Windows SSPI was used
    273. 

  273. since FB 2.1 for windows trusted authentication. Legacy_Auth is
    274. 

  274. compatibility plugin. It's enabled by default on client to let it
    275. 

  275. connect to pre-FB3 servers. (Yes – it still transfers almost plain
    276. 

  276. passwords over the wire. Compatibility...) On server it works with
    277. 

  277. security database from FB 2.5, and should be avoided except cases
    278. 

  278. when you understand well what are you doing. To use Legacy_Auth on
    279. 

  279. server you should set lower level of network traffic encryption in
    280. 

  280. firebird.conf:</FONT></P>
    281. 

  281. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCrypt = Enabled</I></FONT></P>
    282. 

  282. <P STYLE="margin-bottom: 0in"><FONT SIZE=4>or in the worst case:</FONT></P>
    283. 

  283. <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCrypt = Disabled</I></FONT></P>
    284. 

  284. <P STYLE="margin-bottom: 0in"><BR>
    285. 

  285. </P>
    286. 

  286. </BODY>
    287. 

  287. </HTML>
    288.