GNUPG-1-9-BRANCH gnupg/doc (ChangeLog tools.texi)

[cvs user wk]

    Date: Wednesday, April 27, 2005 @ 15:39:17
  Author: wk
    Path: /cvs/gnupg/gnupg/doc
     Tag: GNUPG-1-9-BRANCH

Modified: ChangeLog tools.texi

(symcryptrun): Added.


------------+
 ChangeLog  |    2 +
 tools.texi |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)


Index: gnupg/doc/ChangeLog
diff -u gnupg/doc/ChangeLog:1.39.2.28 gnupg/doc/ChangeLog:1.39.2.29
--- gnupg/doc/ChangeLog:1.39.2.28	Wed Apr 27 14:09:21 2005
+++ gnupg/doc/ChangeLog	Wed Apr 27 15:39:16 2005
@@ -1,5 +1,7 @@
 2005-04-27  Werner Koch  <wk at g10code.com>
 
+	* tools.texi (symcryptrun): Added.
+
 	* scdaemon.texi: Removed OpenSC specific options.
 
 2005-04-20  Werner Koch  <wk at g10code.com>
Index: gnupg/doc/tools.texi
diff -u gnupg/doc/tools.texi:1.1.2.8 gnupg/doc/tools.texi:1.1.2.9
--- gnupg/doc/tools.texi:1.1.2.8	Thu Feb 24 18:36:11 2005
+++ gnupg/doc/tools.texi	Wed Apr 27 15:39:16 2005
@@ -14,6 +14,7 @@
 * gpgsm-gencert.sh::      Generate an X.509 certificate request.
 * gpg-preset-passphrase:: Put a passphrase into the cache.
 * gpg-connect-agent::     Communicate with a running agent.
+* symcryptrun::           Call a simple symmetric encryption tool.
 @end menu
 
 @c
@@ -721,9 +722,102 @@
 (on W32 systems) by means on the Registry entry
 @var{HKCU\Software\GNU\GnuPG:HomeDir}.
 
+ at end table
+
+ at c
+ at c   SYMCRYPTRUN
+ at c
+ at node symcryptrun
+ at section Call a simple symmetric encryption tool.
+
+Sometimes simple encryption tools are already in use for a long time and
+there might be a desire to integrate them into the GnuPG framework.  The
+protocols and encryption methods might be non-standard or not even
+properly documented, so that a full-fledged encryption tool with an
+interface like gpg is not doable.  @command{symcryptrun} provides a
+solution: It operates by calling the external encryption/decryption
+module and provides a passphrase for a key using the standard
+ at command{pinentry} based mechanism through @command{gpg-agent}.
+
+Note, that @command{symcryptrun} is only available if GnuPG has been
+configured with @samp{--enable-symcryptrun} at build time.
+
+ at menu
+* Invoking symcryptrun::   List of all commands and options.
+ at end menu
+
+
+ at node Invoking symcryptrun
+ at subsection List of all commands and options.
+
+ at noindent
+ at command{symcryptrun} is invoked this way:
+
+ at example
+symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
+   [--decrypt | --encrypt] [inputfile]
+ at end example
+
+For encryption, the plain text must be provided on STDIN or as the
+argument @var{inputfile}, and the ciphertext will be output to STDOUT.
+For decryption vice versa.
+
+ at var{CLASS} describes the calling conventions of the external tool.
+Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
+the full filename of that external tool.
+ 
+For the class @samp{confucius} the option @option{--keyfile} is
+required; @var{keyfile} is the name of a file containing the secret key,
+which may be protected by a passphrase.  For detailed calling
+conventions, see the source code.
+ 
+ at noindent
+Note, that @command{gpg-agent} must be running before starting
+ at command{symcryptrun}.
+
+ at noindent
+The following additional options may be used:
+
+ at table @gnupgtabopt
+ at item -v
+ at itemx --verbose
+ at opindex verbose
+Output additional information while running.  
+
+ at item -q
+ at item --quiet
+ at opindex q
+ at opindex quiet
+Try to be as quiet as possible.
+
+ at item --homedir @var{dir}
+ at opindex homedir
+Set the name of the home directory to @var{dir}. If his option is not
+used, the home directory defaults to @file{~/.gnupg}.  It is only
+recognized when given on the command line.  It also overrides any home
+directory stated through the environment variable @env{GNUPGHOME} or
+(on W32 systems) by means on the Registry entry
+ at var{HKCU\Software\GNU\GnuPG:HomeDir}.
+
+ at item --log-file @var{file}
+ at opindex log-file
+Append all logging output to @var{file}.  Default is to write logging
+informaton to STDERR.
 
 @end table
 
+ at noindent
+The possible exit status codes of @command{symcryptrun} are:
 
+ at table @code
+ at item 0 
+        Success.
+ at item 1 
+        Some error occured.
+ at item 2 
+        No valid passphrase was provided.
+ at item 3 
+        The operation was canceled by the user.
 
+ at end table