firebird/examples/extauth/INSTALL

0. Brief description.

fbSampleExtAuth plugin is useful when you want to run 'execute statement on external'
statement connecting to databases on non-local servers but do not wish to explicitly
add login and password to your PL/SQL code. When 2 servers completely trust each other
this plugin may be used to enable access to remote database without entering login and
password in SQL code. To ensure that connection comes from trusted source shared secret
key (placed into plugin's .conf file) is used. That means that the value of a "Key"
parameter should be exacly the same for all trusting each other hosts. Pay attention -
SQL name of connected user on remote host may not match local logon, it depends also
upon mappings on remote host.

1. Before starting the build.

This authentication plugin is using TomCrypt (https://www.libtom.net/LibTomCrypt/) library.
Firebird since v.4 is actively using it. Depending upon build type tomcrypt binary may be
included or not included into your package. In a case when it's included you will find
appropriate H-files in tomcrypt.include subdir. If not that means that native OS library
is used and you should also work with it. Depending upon your OS you will may be need
to install development package for tomcrypt.

2. Building plugin.

Type 'make' in this directory. Build system supposes that it was not moved out of standard
firebird tree. In a case when you did it manually you will sooner of all have to change
Makefile appropriately. If you use firebird with different operating systems and/or hardware
you should build plugin for each used configuration.

3. Installing plugin.

Makefile has install target (make install) which may be used for current box. However
this is not full solution because plugin is supposed to be used to connect at least two
separate servers. See 'Testing' for more details.

4.Testing.

- imagine you have two hosts: host1 and host2;
- generate configuration file using fbSampleExtAuthKeygen utility on any of them (only ONCE -
on ONE host !!!);
- copy that file and plugin itself to $FIREBIRD/plugins directory on each host;
- modify firebird.cond, it should contain something like:
	AuthServer = Srp256, fbSampleExtAuth
	AuthClient = Srp256, fbSampleExtAuth
lines, certainly something else may be used instead recommended Srp256;
- if you need WIN_SSPI plugin please add it AFTER fbSampleExtAuth;
- do not forget to restart firebird after reconfiguring it;
- create minimal required mapping on host1:
	CREATE MAPPING EXT USING PLUGIN fbSampleExtAuth FROM ANY USER TO USER EXTUSER;
- run the following script on host2:
	SET TERM ^;
	EXECUTE BLOCK RETURNS(REMNAME CHAR(32)) AS BEGIN
		EXECUTE STATEMENT 'SELECT CURRENT_USER FROM RDB$DATABASE'
				ON EXTERNAL 'host1:employee' INTO :REMNAME;
		SUSPEND;
	END^
	SET TERM ;^
you should get something like this:
	REMNAME
	==============================
	EXTUSER
- explicitly specifying login and/or password in SQL statement normally deactivates
this plugin but one can use IgnoreLogin and IgnorePassword parameters to change that.