doc/shigofumi.xml

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2
   3 <!DOCTYPE reference PUBLIC "-//OASIS/DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5
   6 <reference lang="en">
   7
   8   <referenceinfo>
   9     <author>
  10       <personname>
  11         <firstname>Petr</firstname>
  12         <surname>Písař</surname>
  13       </personname>
  14       <personblurb>
  15         <simpara>He's written Shigofumi and libisds.</simpara>
  16       </personblurb>
  17     </author>
  18     <productname>Shigofumi</productname>
  19   </referenceinfo>
  20
  21   <title>Manual for Shigofumi</title>
  22
  23
  24   <refentry id="shigofumi.1">
  25     <refmeta>
  26       <refentrytitle>shigofumi</refentrytitle>
  27       <manvolnum>1</manvolnum>
  28     </refmeta>
  29
  30     <refnamediv>
  31       <refname>shigofumi</refname>
  32       <refpurpose>ISDS client</refpurpose>
  33     </refnamediv>
  34
  35     <refsynopsisdiv>
  36       <cmdsynopsis>
  37         <command>shigofumi</command>
  38         <arg choice="opt"><option>-c</option> <replaceable>FILE</replaceable></arg>
  39       </cmdsynopsis>
  40
  41       <cmdsynopsis>
  42         <command>shigofumi</command>
  43         <arg choice="plain"><option>-e</option>
  44           <replaceable>COMMANDS</replaceable></arg>
  45       </cmdsynopsis>
  46
  47       <cmdsynopsis>
  48         <command>shigofumi</command>
  49         <arg choice="plain"><option>-V</option></arg>
  50       </cmdsynopsis>
  51     </refsynopsisdiv>
  52
  53     <refsection>
  54       <title>Description</title>
  55
  56       <para>Shigofumi is an <abbrev>ISDS</abbrev> client based on libisds
  57         library.  The client can access <abbrev>ISDS</abbrev>, processes local
  58         message and delivery details, and submit file to authorized
  59         conversion.</para>
  60
  61       <para>Shigofumi is command line oriented program. Once you start it, use
  62         <command>help</command> to get list of embedded commands. Use
  63         <command>help <replaceable>COMMAND</replaceable></command> to get
  64         details about selected <replaceable>COMMAND</replaceable>. Be ware
  65         that command listing changes contextually. User can use casual
  66         readline shortcuts for line editing (like tab completing).</para>
  67
  68       <para>While transmitting data over Internet, a progress-bar is updated.
  69         User can cancel current network operation by emitting SIGINT signal
  70         (<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
  71         usually).</para>
  72     </refsection>
  73
  74     <refsection>
  75       <title>Options</title>
  76
  77       <variablelist>
  78         <varlistentry>
  79           <term><option>-c <replaceable>FILE</replaceable></option></term>
  80           <listitem>
  81             <simpara>Use configuration <replaceable>FILE</replaceable> instead
  82             of default one.</simpara>
  83           </listitem>
  84         </varlistentry>
  85
  86         <varlistentry>
  87           <term><option>-e <replaceable>COMMANDS</replaceable></option></term>
  88           <listitem>
  89             <simpara>Run shigofumi in batch mode: execute each command and
  90               terminate then.</simpara>
  91
  92             <simpara>Commands are delimited by new line (<literal>\n</literal>
  93               or <literal>\r</literal>). If any command fails, other commands
  94               will not be processed and shigofumi will quit immediately with
  95               non-zero exit code. If all commands succeed, shigofumi will return
  96               zero code.</simpara>
  97           </listitem>
  98         </varlistentry>
  99
 100         <varlistentry>
 101           <term><option>-V</option></term>
 102           <listitem>
 103             <simpara>Show program version and linked libraries details and
 104               exit.</simpara>
 105           </listitem>
 106         </varlistentry>
 107       </variablelist>
 108     </refsection>
 109
 110     <refsection>
 111       <title><abbrev>ISDS</abbrev></title>
 112
 113       <para><abbrev>ISDS</abbrev> (<phrase lang="cs">Informační systém
 114           datových schránek</phrase> / Data Box Information System)
 115         is defined by <ulink url="http://portal.gov.cz/zakon/300/2008">Czech <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
 116         and implied documents.</para>
 117
 118       <para>The system is designed to deliver messages between public
 119         authorities (government, courts <abbrev>etc.</abbrev>) and other
 120         entities (corporations, persons, other government or municipality
 121         offices) in reliable and traceable way.</para>
 122
 123       <para>Shigofumi implements following <abbrev>ISDS</abbrev> operations:
 124         <simplelist type="inline"><member>Log in by name and password</member>
 125           <member>Incoming and outgoing message listing</member>
 126           <member>Accepting commercial message</member>
 127           <member>Retrieving incoming and outgoing message</member>
 128           <member>Explicit marking a message as read</member>
 129           <member>Verifying message hash</member>
 130           <member>Getting message hash stored in ISDS</member>
 131           <member>Retrieving delivery details</member>
 132           <member>Sending a message to one or more recipients</member>
 133           <member>Searching a box by any criteria</member>
 134           <member>Getting a box status</member>
 135           <member>Changing user password</member>
 136           <member>Getting user password expiration time</member>
 137           <member>Getting details about user's box</member>
 138           <member>Listing box users</member>
 139       </simplelist>.</para>
 140
 141       <para>In addition, Shigofumi can save a message and delivery details
 142         into local file and load it later again. Program can save each
 143         document into local file (except XML documents).</para>
 144     </refsection>
 145
 146     <refsection>
 147       <title>Authorized conversion</title>
 148
 149       <para>Czech government offers a document conversion from digital to analogue
 150         form and vice versa preserving legal impacts. This is done at Czech POINT
 151         meeting place (in government, municipality or post office usually). Visit <ulink
 152         url="https://www.czechpoint.cz/">Czech POINT web site</ulink> for more
 153         details.</para>
 154
 155       <para>Shigofumi allows to submit a digital document (local file or
 156         document delivered by an <abbrev>ISDS</abbrev> message) for
 157         authorized conversion into Czech POINT deposit. If deposit accepts
 158         the document, it will return a document identifier that user is
 159         required to tell to an officer in a office where he wants to obtain
 160         analogue version of his document.</para>
 161
 162       <para>Please note the deposit keeps submitted document for limited
 163         period only. Old documents (30 days currently) are removed
 164         automatically. Note also PDF documents with valid digital signature
 165         can be converted only.</para>
 166     </refsection>
 167
 168     <refsection>
 169       <title>Files</title>
 170       <variablelist>
 171         <varlistentry>
 172           <term><filename>~/.shigofumirc</filename></term>
 173           <listitem>
 174             <simpara>Default configuration file location.</simpara>
 175           </listitem>
 176         </varlistentry>
 177       </variablelist>
 178     </refsection>
 179
 180     <refsection>
 181       <title>See Also</title>
 182       <para>
 183         <link linkend="shigofumirc.5">
 184           <citerefentry>
 185             <refentrytitle>shigofumirc</refentrytitle>
 186             <manvolnum>5</manvolnum>
 187           </citerefentry>
 188         </link>
 189       </para>
 190     </refsection>
 191   </refentry>
 192
 193
 194   <refentry id="shigofumirc.5">
 195     <refmeta>
 196       <refentrytitle>shigofumirc</refentrytitle>
 197       <manvolnum>5</manvolnum>
 198     </refmeta>
 199
 200     <refnamediv>
 201       <refname>shigofumirc</refname>
 202       <refpurpose>Configuration file for Shigofumi</refpurpose>
 203     </refnamediv>
 204
 205     <refsection>
 206       <title>Description</title>
 207
 208       <para>Configuration for shigofumi is loaded from
 209         <filename>.shigofumirc</filename> in user's home directory by
 210         default.</para>
 211
 212       <para>The file is plain text file with simple syntax: Setting is stored
 213         in <replaceable>option</replaceable> <literal>=</literal>
 214         <replaceable>value</replaceable> format. If value is a type of string,
 215         it must be delimited by quotation marks. Boolean values can be
 216         expressed as <literal>"true"</literal> or non-zero integer
 217         (<literal>1</literal>) for affirmation, or <literal>"false"</literal>
 218         or zero integer (<literal>0</literal>) for negation. Simple numeric
 219         values are unquoted. Commentary starts with hash sign
 220         (<literal>#</literal>) and continues to the end of the line.</para>
 221     </refsection>
 222
 223     <refsection>
 224       <title>Options</title>
 225
 226       <para>Following options are recognized. Not all of them must present.
 227         Missing options fall to default value back.</para>
 228
 229       <refsection>
 230         <title>Account Options</title>
 231
 232         <variablelist>
 233           <varlistentry>
 234             <term><literal>base_url</literal></term>
 235             <listitem>
 236               <simpara>Base <abbrev>URL</abbrev> for <abbrev>ISDS</abbrev>
 237                 server.  <abbrev>E.g.</abbrev>
 238                 <literal>"https://www.czebox.cz/"</literal> for testing
 239                 instance of ISDS or
 240                 <literal>"https://www.mojedavaschranka.cz/"</literal> for
 241                 official instance with valid and legal data. Do not forget on
 242                 leading protocol schema and trailing slash. Default value is
 243                 value provided by libisds library.</simpara>
 244             </listitem>
 245           </varlistentry>
 246
 247           <varlistentry>
 248             <term><literal>password</literal></term>
 249             <listitem>
 250               <simpara>Password assigned to given user-name. User must keep it
 251                 in secret. This password is used while HTTP authentication and
 252                 is passed to underlying network libraries. Make sure this
 253                 configuration file or your swap partition (network library
 254                 together with password can be swapped out during physical
 255                 memory outage) will not get to bad guys. Encrypt them before.
 256                 Default value is empty string.</simpara>
 257             </listitem>
 258           </varlistentry>
 259
 260           <varlistentry>
 261             <term><literal>username</literal></term>
 262             <listitem>
 263               <simpara><abbrev>ISDS</abbrev> user log-in name. Identifies
 264                 a user in <abbrev>ISDS</abbrev>. One person can have more
 265                 identities. Default value is empty string.</simpara>
 266             </listitem>
 267           </varlistentry>
 268         </variablelist>
 269       </refsection>
 270
 271       <refsection>
 272         <title><abbrev>TLS</abbrev> Options</title>
 273
 274         <variablelist>
 275           <varlistentry>
 276             <term><literal>ca_directory</literal></term>
 277             <listitem>
 278               <simpara>Path to directory with trusted authorities certificates
 279                 stored in separate files (files must have special names
 280                 usually).  Default value is provided by underlying
 281                 cryptographic library.  Exact meaning of this option depends
 282                 on interpretation by used cryptographic library.</simpara>
 283             </listitem>
 284           </varlistentry>
 285
 286           <varlistentry>
 287             <term><literal>ca_file</literal></term>
 288             <listitem>
 289               <simpara>Path to file with trusted authorities certificates
 290                 (concatenated list of PEM-formatted certificates).
 291                 Default value is provided by underlying cryptographic library.
 292                 Exact meaning of this option depends on interpretation by used
 293                 cryptographic library.</simpara>
 294             </listitem>
 295           </varlistentry>
 296
 297           <varlistentry>
 298             <term><literal>crl_file</literal></term>
 299             <listitem>
 300               <simpara>Path to file with certificate revocation lists
 301                 (concatenated list of CRLs in PEM format usually).
 302                 Default value is provided by underlying cryptographic library.
 303                 Exact meaning of this option depends on interpretation by used
 304                 cryptographic library.</simpara>
 305             </listitem>
 306           </varlistentry>
 307
 308           <varlistentry>
 309             <term><literal>verify_server</literal></term>
 310             <listitem>
 311               <simpara>Boolean switch deciding whether server identity should
 312                 be verified. When using <abbrev>HTTPS</abbrev> connection to
 313                 the server, the identity of server can be verified in
 314                 <abbrev>TLS</abbrev> negotiation phase by validating server
 315                 certificate against trusted certificate authority certificate
 316                 and certificate revocation list. Default value is true. It's
 317                 strongly recommended to keep it on.</simpara>
 318             </listitem>
 319           </varlistentry>
 320         </variablelist>
 321       </refsection>
 322
 323       <refsection>
 324         <title>Network Options</title>
 325
 326         <variablelist>
 327           <varlistentry>
 328             <term><literal>timeout</literal></term>
 329             <listitem>
 330               <simpara>Non-negative integer setting network time-out in
 331                 miliseconds. Use 0 not to limit any network operation.
 332                 Default value is 10,000 ms.</simpara>
 333             </listitem>
 334           </varlistentry>
 335         </variablelist>
 336       </refsection>
 337
 338       <refsection>
 339         <title>Other Options</title>
 340         <variablelist>
 341           <varlistentry>
 342             <term><literal>normalize_mime_type</literal></term>
 343             <listitem>
 344               <simpara>Boolean switch deciding whether <abbrev>MIME</abbrev>
 345                 type of documents retrieved from a message should be normalized
 346                 to standard values. Default value is true.</simpara>
 347
 348               <simpara><abbrev>ISDS</abbrev> does not check document
 349                 <abbrev>MIME</abbrev> type a client supplies. Unfortunately,
 350                 official client sends invalid values (file name extension
 351                 usually). This option allows Shigofumi to fix the type
 352                 on-the-fly. Be ware the original value stored in
 353                 <abbrev>ISDS</abbrev> or locally saved message keeps
 354                 untouched.</simpara>
 355             </listitem>
 356           </varlistentry>
 357         </variablelist>
 358       </refsection>
 359
 360         <!--varlistentry>
 361           <term><literal></literal></term>
 362           <listitem>
 363             <simpara></simpara>
 364           </listitem>
 365         </varlistentry-->
 366     </refsection>
 367
 368     <refsection>
 369       <title>Notice on cryptographic library</title>
 370
 371       <para>Shigofumi uses libisds that utilizes cURL library that can use
 372         three different cryptographic libraries at this time: OpenSSL, GnuTLS
 373         and NSS. Each library has different set of features and different
 374         configuration. Thus exact meaning of some Shigofumi configuration
 375         options can be slightly shifted (<abbrev>e.g.</abbrev> the
 376         name of client certificate and key). Some options cannot be understood
 377         at all (<abbrev>e.g.</abbrev> GnuTLS does not support directory of
 378         certificates).</para>
 379
 380       <para>Current cryptographic library can be determined from
 381         <command>shigofumi -V</command> output.</para>
 382     </refsection>
 383
 384     <refsection>
 385       <title>Files</title>
 386       <variablelist>
 387         <varlistentry>
 388           <term><filename>~/.shigofumirc</filename></term>
 389           <listitem>
 390             <simpara>Default location of the configuration file.</simpara>
 391           </listitem>
 392         </varlistentry>
 393       </variablelist>
 394     </refsection>
 395
 396     <refsection>
 397       <title>Example</title>
 398       <programlisting><![CDATA[base_url = "https://www.czebox.cz/"
 399 # These credentials are invalid
 400 username = 1s79vd
 401 password = XY123456
 402 verify_server = true
 403 ca_file = /etc/ssl/certs/ca-certificates.crt
 404 ca_directory = /etc/ssl/certs
 405 crl_file = /etc/ssl/crl]]></programlisting>
 406     </refsection>
 407
 408     <refsection>
 409       <title>See Also</title>
 410       <para>
 411         <link linkend="shigofumi.1">
 412           <citerefentry>
 413             <refentrytitle>shigofumi</refentrytitle>
 414             <manvolnum>1</manvolnum>
 415           </citerefentry>
 416         </link>
 417       </para>
 418     </refsection>
 419   </refentry>
 420
 421 </reference>