Postfix (mostly comments & documentation) for core-5472

doc/Using_OO_API.html

@@ -5,8 +5,10 @@
 	<title></title>
 	<meta name="generator" content="LibreOffice 5.2.3.3 (Linux)"/>
 	<meta name="author" content="alex "/>
-	<meta name="created" content="2013-05-31T00:00:00.010003100"/>
-	<meta name="changed" content="2017-01-31T17:08:57.272616325"/>
+	<meta name="created" content="00:00:00"/>
+	<meta name="changed" content="2017-02-02T17:00:07.121995034"/>
+	<meta name="created" content="2013-05-31T00:00:00.010003100">
+	<meta name="changed" content="2017-01-31T17:08:57.272616325">
 	<meta name="CHANGEDBY" content="Alex Peshkoff">
 	<meta name="CHANGEDBY" content="Alex Peshkoff">
 	<meta name="CHANGEDBY" content="Alex Peshkoff">
@@ -3161,8 +3163,7 @@ <h1><font size="4" style="font-size: 14pt">Database encryption
 when network access to the server is used. All this job should be
 done in plugin (and application working with it) i.e. database block
 encryption algorithm by itself may happen to be easiest part of db
-crypt plugin, </font><font size="4" style="font-size: 14pt">specially
-when some standard library is used for it.</font></p>
+crypt plugin, specially when some standard library is used for it.</font></p>
 <p style="margin-bottom: 0in"><br/>
 
 </p>
@@ -3180,6 +3181,19 @@ <h1><font size="4" style="font-size: 14pt">Database encryption
 </ol>
 <p style="margin-bottom: 0in"><br/>
 
+</p>
+<p style="margin-bottom: 0in"><a name="DbCryptInfo"></a><font size="4" style="font-size: 14pt">DbCryptInfo
+interface is passed to DbCryptPlugin by engine. Plugin may save this
+interface and use when needed to obtain additional informatio about
+database.</font></p>
+<ol>
+	<li/>
+<p style="margin-bottom: 0in"><font size="4" style="font-size: 14pt">const
+	char* getDatabaseFullPath(StatusType* status) – returns full
+	(including path) name of primary database file.</font></p>
+</ol>
+<p style="margin-bottom: 0in"><br/>
+
 </p>
 <p style="margin-bottom: 0in"><a name="DbCryptPlugin"></a><font size="4" style="font-size: 14pt">DbCryptPlugin
 interface is main interface of database crypt plugin.</font></p>
@@ -3202,6 +3216,10 @@ <h1><font size="4" style="font-size: 14pt">Database encryption
 <p style="margin-bottom: 0in"><font size="4" style="font-size: 14pt">void
 	decrypt(StatusType* status, unsigned length, const void* from, void*
 	to) – decrypts data after reading block from database file.</font></p>
+	<li/>
+<p style="margin-bottom: 0in"><font size="4" style="font-size: 14pt">void
+	setInfo(StatusType* status, IDbCryptInfo* info) – in this method
+	crypt plugin typically saves informational interface for future use.</font></p>
 </ol>
 <p style="margin-bottom: 0in"><br/>
 
@@ -3251,11 +3269,11 @@ <h1><font size="4" style="font-size: 14pt">Key holder for database
 	letting it to work with database.</font></p>
 	<li/>
 <p style="margin-bottom: 0in"><font size="4" style="font-size: 14pt">ICryptKeyCallback*
-	chainHandle(StatusType* status) – support of a chain of key holders. In
-	some cases key has to pass through more than single key holder
-	before it reaches db crypt plugin. This is needed (for example) to
-	support execute statement in encrypted database. This is just a
-	sample – chains are also used in some other cases. Callback
+	chainHandle(StatusType* status) – support of a chain of key
+	holders. In some cases key has to pass through more than single key
+	holder before it reaches db crypt plugin. This is needed (for
+	example) to support execute statement in encrypted database. This is
+	just a sample – chains are also used in some other cases. Callback
 	interface, returned by this method, may differ from one returned by
 	keyHandle() function (see above). Typically is should be able to
 	duplicate one-to-one keys, received by KeyHolderPlugin when

examples/dbcrypt/CryptApplication.cpp

@@ -81,6 +81,12 @@ class App
 	}
 
 	enum Action {NONE, ENC, DEC, EX_LCL, EX_RMT};
+	// Switches/actions have the following meanings:
+	// ENC(-e) - encrypt database
+	// DEC(-d) - decrypt database
+	// EX_LCL(-l) - execute some predefined select command (demonstrates that database can respond to select request)
+	// EX_RMT(-r) - execute select using execute statement in remote datasource (demonstrates that dbcrypt key is
+	//				passed to target database when using execute statement)
 
 	void execute(const char* dbName, const Action a)
 	{

examples/dbcrypt/ReadMe.txt

@@ -1,2 +1,39 @@
-All files in this directory are trivial samples.
-They do not perform any real data encryption and should not be used in production!
+**************************************************************************************
+*				All files in this directory are trivial samples.					 *
+* They do not perform any real data encryption and should not be used in production! *
+**************************************************************************************
+
+Brief description of the sample.
+
+Sample contains 3 components - DbCrypt plugin, KeyHolder plugin and application, which can pass
+crypt key to server. Plugins do not perform any real encryption (XOR with single byte hardly can
+be treated as encryption though makes database useless without crypt plugin), key is sent between
+components in plain form - they just demonstrate what calls in plugins should be done and what
+methods should be implemented in order for plugin to start to work.
+
+Depending upon settings in configuration file plugins may use different ways to manage encryption
+key. DbCrypt's configuration file may contain following parameters:
+Auto - boolean value, when FALSE plugin queries KeyHolder plugin for key value (this is default),
+	when TRUE get key value from "Value" configuration parameter.
+Value - integer value (lower byte is actually used), used in "Auto" mode as key value (default 90).
+
+CryptKeyHolder's configuration file may contain following parameters:
+Auto - boolean value, when FALSE plugin queries client application for key value (this is default),
+	when TRUE get key value from configuration file by name or use default (90) for unnamed key.
+Key{Name} - integer value, a key with name "Name" (i.e. when one issues "ALTER DATABASE ENCRYPT ...
+	KEY Doggy" configuration parameter KeyDoggy should be present).
+OnlyOwnKey - boolean value, enables/disables use of a key from another key holder in SuperServer.
+	Default value is TRUE (i.e. only key, owned by this KeyHolder, can be used by related
+	attachment).
+
+Crypt application has a few parameters making it possible to demonstrate different operations.
+-e - Encrypt database (use gstat to monitor crypt progress).
+-d - Decrypt database.
+-l - Locally execute SELECT statement returning name of currently attached user.
+-r - Execute same statement using remote datasource 'localhost:employee'. To make it work
+	 user "test" with password "test" should be created in employee database. If employee was
+	 encrypted in advance this demonstrates passing database crypt key through the chain of
+	 key holders.
+
+cryptDb.pas is a minimum (XOR using fixed key hardcoded in plugin body) sample of database crypt
+plugin written on Pascal. Was tested with both FreePascal and Delphi.

src/jrd/extds/IscDS.cpp

@@ -126,16 +126,24 @@ void IscConnection::attach(thread_db* tdbb, const PathName& dbName, const MetaNa
 		EngineCallbackGuard guard(tdbb, *this, FB_FUNCTION);
 
 		ICryptKeyCallback* cb = tdbb->getAttachment()->att_crypt_callback;
-		m_iscProvider.fb_database_crypt_callback(&status, cb);
-		if (status->getState() & IStatus::STATE_ERRORS) {
-			raise(&status, tdbb, "crypt_callback");
-		}
+		try
+		{
+			m_iscProvider.fb_database_crypt_callback(&status, cb);
+			if (status->getState() & IStatus::STATE_ERRORS) {
+				raise(&status, tdbb, "crypt_callback");
+			}
 
-		m_iscProvider.isc_attach_database(&status, m_dbName.length(), m_dbName.c_str(),
-			&m_handle, newDpb.getBufferLength(),
-			reinterpret_cast<const char*>(newDpb.getBuffer()));
-		if (status->getState() & IStatus::STATE_ERRORS) {
-			raise(&status, tdbb, "attach");
+			m_iscProvider.isc_attach_database(&status, m_dbName.length(), m_dbName.c_str(),
+				&m_handle, newDpb.getBufferLength(),
+				reinterpret_cast<const char*>(newDpb.getBuffer()));
+			if (status->getState() & IStatus::STATE_ERRORS) {
+				raise(&status, tdbb, "attach");
+			}
+		}
+		catch(const Exception&)
+		{
+			m_iscProvider.fb_database_crypt_callback(&status, NULL);
+			throw;
 		}
 
 		m_iscProvider.fb_database_crypt_callback(&status, NULL);