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="opt"><option>-c</option> <replaceable>FILE</replaceable></arg>
  44         <arg choice="plain"><option>-e</option>
  45           <replaceable>COMMANDS</replaceable></arg>
  46       </cmdsynopsis>
  47
  48       <cmdsynopsis>
  49         <command>shigofumi</command>
  50         <arg choice="plain"><option>-V</option></arg>
  51       </cmdsynopsis>
  52     </refsynopsisdiv>
  53
  54     <refsection>
  55       <title>Description</title>
  56
  57       <para>Shigofumi is an <abbrev>ISDS</abbrev> client based on libisds
  58         library.  The client can access <abbrev>ISDS</abbrev>, processes local
  59         message and delivery details, and submit file to authorized
  60         conversion.</para>
  61
  62       <para>Shigofumi is command line oriented program. Once you start it, use
  63         <command>help</command> to get list of embedded commands. Use
  64         <command>help <replaceable>COMMAND</replaceable></command> to get
  65         details about selected <replaceable>COMMAND</replaceable>. Be ware
  66         that command listing changes contextually. User can use casual
  67         readline shortcuts for line editing (like tab completing).</para>
  68
  69       <para>While transmitting data over Internet, a progress-bar is updated.
  70         User can cancel current network operation by emitting SIGINT signal
  71         (<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
  72         usually).</para>
  73     </refsection>
  74
  75     <refsection>
  76       <title>Options</title>
  77
  78       <variablelist>
  79         <varlistentry>
  80           <term><option>-c <replaceable>FILE</replaceable></option></term>
  81           <listitem>
  82             <simpara>Use configuration <replaceable>FILE</replaceable> instead
  83             of default one.</simpara>
  84           </listitem>
  85         </varlistentry>
  86
  87         <varlistentry>
  88           <term><option>-e <replaceable>COMMANDS</replaceable></option></term>
  89           <listitem>
  90             <simpara>Run shigofumi in batch mode: execute each command and
  91               terminate then.</simpara>
  92
  93             <simpara>Commands are delimited by new line (<literal>\n</literal>
  94               or <literal>\r</literal>). If any command fails, other commands
  95               will not be processed and shigofumi will quit immediately with
  96               non-zero exit code. If all commands succeed, shigofumi will return
  97               zero code.</simpara>
  98
  99             <example>
 100               <title>Authorized Conversion from Shell</title>
 101
 102               <programlisting>$ shigofumi -e 'convert /etc/passwd'</programlisting>
 103
 104               <simpara>The command submits <filename>/etc/passwd</filename>
 105                 file to authorized conversion. Although it's syntactically
 106                 correct, it will fail because plain text files are not allowed
 107                 to be converted. Check always return code in your scripts.</simpara>
 108             </example>
 109           </listitem>
 110         </varlistentry>
 111
 112         <varlistentry>
 113           <term><option>-V</option></term>
 114           <listitem>
 115             <simpara>Show program version and linked libraries details and
 116               exit.</simpara>
 117           </listitem>
 118         </varlistentry>
 119       </variablelist>
 120     </refsection>
 121
 122     <refsection>
 123       <title>Shigofumi Command Language</title>
 124
 125       <simpara>The language is straightforward. Each command is one case sensitive
 126         word followed by (empty) sequence of arguments. Command and arguments
 127         are separated by one or more white spaces. If you need to embed white
 128         space into argument, use backslash (<literal>\</literal>) to escape
 129         it. If you need to write backslash, escape it with backslash again.
 130         String quotation is not currently supported.</simpara>
 131
 132       <simpara>If argument type is file name, you can use tilde symbol
 133         (<literal>~</literal>) as abbreviation for user's home directory. Home
 134         directory is derived from <envar>HOME</envar> environment
 135         variable.</simpara>
 136
 137       <simpara>Command names, file names and message identifiers can be
 138         completed by pressing completion key (depends on readline
 139         configuration, <keycap>Tab</keycap> usually). They are expanded only
 140         after commands expecting argument of appropriate type.</simpara>
 141
 142       <simpara>Set of available commands changes with context.
 143         <abbrev>E.g.</abbrev> If a message is loaded, commands for message
 144         operation like save to file will become available. Also meaning of the
 145         same command can change. <abbrev>E.g.</abbrev> <command>show</command>
 146         command will print list of incoming messages if such list is
 147         loaded; if a message is loaded, prints the message. List of currently
 148         available commands can be obtained by <command>help</command>
 149         command.</simpara>
 150
 151       <simpara>Syntax help for a command is printed after calling command with
 152         invalid option or by <command>help</command> command with interested
 153         command as first argument. Command option <option>-h</option> is
 154         reserved as invalid option and shows always command usage.</simpara>
 155     </refsection>
 156
 157     <refsection>
 158       <title><abbrev>ISDS</abbrev></title>
 159
 160       <para><abbrev>ISDS</abbrev> (<phrase lang="cs">Informační systém
 161           datových schránek</phrase> / Data Box Information System)
 162         is defined by <ulink url="http://portal.gov.cz/zakon/300/2008">Czech <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
 163         and implied documents.</para>
 164
 165       <para>The system is designed to deliver messages between public
 166         authorities (government, courts <abbrev>etc.</abbrev>) and other
 167         entities (corporations, persons, other government or municipality
 168         offices) in reliable and traceable way.</para>
 169
 170       <para>Shigofumi implements following <abbrev>ISDS</abbrev> operations:
 171         <simplelist type="inline"><member>Log in by name and password</member>
 172           <member>Incoming and outgoing message listing</member>
 173           <member>Accepting commercial message</member>
 174           <member>Retrieving incoming and outgoing message</member>
 175           <member>Explicit marking a message as read</member>
 176           <member>Verifying message hash</member>
 177           <member>Getting message hash stored in ISDS</member>
 178           <member>Retrieving delivery details</member>
 179           <member>Sending a message to one or more recipients</member>
 180           <member>Searching a box by any criteria</member>
 181           <member>Getting a box status</member>
 182           <member>Changing user password</member>
 183           <member>Getting user password expiration time</member>
 184           <member>Getting details about user's box</member>
 185           <member>Listing box users</member>
 186       </simplelist>.</para>
 187
 188       <para>In addition, Shigofumi can save a message and delivery details
 189         into local file and load it later again. Program can save each
 190         document into local file (except XML documents).</para>
 191     </refsection>
 192
 193     <refsection>
 194       <title>Authorized conversion</title>
 195
 196       <para>Czech government offers a document conversion from digital to analogue
 197         form and vice versa preserving legal impacts. This is done at Czech POINT
 198         meeting place (in government, municipality or post office usually). Visit <ulink
 199         url="https://www.czechpoint.cz/">Czech POINT web site</ulink> for more
 200         details.</para>
 201
 202       <para>Shigofumi allows to submit a digital document (local file or
 203         document delivered by an <abbrev>ISDS</abbrev> message) for
 204         authorized conversion into Czech POINT deposit. If deposit accepts
 205         the document, it will return a document identifier that user is
 206         required to tell to an officer in a office where he wants to obtain
 207         analogue version of his document.</para>
 208
 209       <para>Please note the deposit keeps submitted document for limited
 210         period only. Old documents (30 days currently) are removed
 211         automatically. Note also PDF documents with valid digital signature
 212         can be converted only.</para>
 213     </refsection>
 214
 215     <refsection>
 216       <title>Files</title>
 217       <variablelist>
 218         <varlistentry>
 219           <term><filename>~/.shigofumirc</filename></term>
 220           <listitem>
 221             <simpara>Default configuration file location.</simpara>
 222           </listitem>
 223         </varlistentry>
 224       </variablelist>
 225     </refsection>
 226
 227     <refsection>
 228       <title>See Also</title>
 229       <para>
 230         <link linkend="shigofumirc.5">
 231           <citerefentry>
 232             <refentrytitle>shigofumirc</refentrytitle>
 233             <manvolnum>5</manvolnum>
 234           </citerefentry>
 235         </link>
 236       </para>
 237     </refsection>
 238   </refentry>
 239
 240
 241   <refentry id="shigofumirc.5">
 242     <refmeta>
 243       <refentrytitle>shigofumirc</refentrytitle>
 244       <manvolnum>5</manvolnum>
 245     </refmeta>
 246
 247     <refnamediv>
 248       <refname>shigofumirc</refname>
 249       <refpurpose>Configuration file for Shigofumi</refpurpose>
 250     </refnamediv>
 251
 252     <refsection>
 253       <title>Description</title>
 254
 255       <para>Configuration for shigofumi is loaded from
 256         <filename>.shigofumirc</filename> in user's home directory by
 257         default.</para>
 258
 259       <para>The file is plain text file with simple syntax: Setting is stored
 260         in <replaceable>option</replaceable> <literal>=</literal>
 261         <replaceable>value</replaceable> format. If value is a type of string,
 262         it must be delimited by quotation marks. Boolean values can be
 263         expressed as <literal>"true"</literal> or non-zero integer
 264         (<literal>1</literal>) for affirmation, or <literal>"false"</literal>
 265         or zero integer (<literal>0</literal>) for negation. Simple numeric
 266         values are unquoted. Commentary starts with hash sign
 267         (<literal>#</literal>) and continues to the end of the line.</para>
 268
 269       <para>If an option accepts list of values, the syntax is traditional
 270         mathematical set notation: <literal>{</literal>
 271         <replaceable>value1</replaceable> <literal>,</literal>
 272         <replaceable>value2</replaceable> <literal>}</literal>.</para>
 273     </refsection>
 274
 275     <refsection>
 276       <title>Options</title>
 277
 278       <para>Following options are recognized. Not all of them must present.
 279         Missing options fall to default value back.</para>
 280
 281       <refsection>
 282         <title>Account Options</title>
 283
 284         <variablelist>
 285           <varlistentry>
 286             <term><literal>base_url</literal></term>
 287             <listitem>
 288               <simpara>Base <abbrev>URL</abbrev> for <abbrev>ISDS</abbrev>
 289                 server.  Be carefull when setting this value: This can reveal
 290                 your password to bad guys running fake server (if you do not
 291                 verify server identity preciously) and different host names
 292                 are used with different log-in mechanism. In addition, there
 293                 are two system instances administred by Czech government:
 294                 official one and testing one.</simpara>
 295
 296               <simpara><abbrev>E.g.</abbrev> use
 297                 <literal>"https://ws1.czebox.cz/"</literal> for testing
 298                 instance of ISDS or
 299                 <literal>"https://ws1.mojedatovaschranka.cz/"</literal> for
 300                 official instance with valid and legal data when loging in
 301                 without <abbrev>TLS</abbrev> client certificate. Otherwise,
 302                 with client certificate in use, replace the
 303                 <literal>ws1</literal> domain with <literal>ws1c</literal>
 304                 domain. <abbrev>I.e.</abbrev>
 305                 <literal>"https://ws1c.czebox.cz/"</literal> for testing
 306                 instance or
 307                 <literal>"https://ws1c.mojedatovaschranka.cz/"</literal> for
 308                 offical instance.</simpara>
 309
 310               <simpara>Do not forget on leading protocol schema and trailing
 311                 slash. Default value is official instance locator provided by
 312                 libisds library.</simpara>
 313             </listitem>
 314           </varlistentry>
 315
 316           <varlistentry>
 317             <term><literal>password</literal></term>
 318             <listitem>
 319               <simpara>Password assigned to given user-name. User must keep it
 320                 in secret. This password is used while HTTP authentication and
 321                 is passed to underlying network libraries. Make sure this
 322                 configuration file or your swap partition (network library
 323                 together with password can be swapped out during physical
 324                 memory outage) will not get to bad guys. Encrypt them before.
 325                 Default value is empty string.</simpara>
 326             </listitem>
 327           </varlistentry>
 328
 329           <varlistentry>
 330             <term><literal>username</literal></term>
 331             <listitem>
 332               <simpara><abbrev>ISDS</abbrev> user log-in name. Identifies
 333                 a user in <abbrev>ISDS</abbrev>. One person can have more
 334                 identities. Default value is empty string.</simpara>
 335             </listitem>
 336           </varlistentry>
 337         </variablelist>
 338       </refsection>
 339
 340       <refsection>
 341         <title><abbrev>TLS</abbrev> Options</title>
 342
 343         <variablelist>
 344           <varlistentry>
 345             <term><literal>ca_directory</literal></term>
 346             <listitem>
 347               <simpara>Path to directory with trusted authorities certificates
 348                 stored in separate files (files must have special names
 349                 usually).  Default value is provided by underlying
 350                 cryptographic library.  Exact meaning of this option depends
 351                 on interpretation by used cryptographic library.</simpara>
 352             </listitem>
 353           </varlistentry>
 354
 355           <varlistentry>
 356             <term><literal>ca_file</literal></term>
 357             <listitem>
 358               <simpara>Path to file with trusted authorities certificates
 359                 (concatenated list of PEM-formatted certificates).
 360                 Default value is provided by underlying cryptographic library.
 361                 Exact meaning of this option depends on interpretation by used
 362                 cryptographic library.</simpara>
 363             </listitem>
 364           </varlistentry>
 365
 366           <varlistentry>
 367             <term><literal>crl_file</literal></term>
 368             <listitem>
 369               <simpara>Path to file with certificate revocation lists
 370                 (concatenated list of CRLs in PEM format usually).
 371                 Default value is provided by underlying cryptographic library.
 372                 Exact meaning of this option depends on interpretation by used
 373                 cryptographic library.</simpara>
 374             </listitem>
 375           </varlistentry>
 376
 377           <varlistentry>
 378             <term><literal>verify_server</literal></term>
 379             <listitem>
 380               <simpara>Boolean switch deciding whether server identity should
 381                 be verified. When using <abbrev>HTTPS</abbrev> connection to
 382                 the server, the identity of server can be verified in
 383                 <abbrev>TLS</abbrev> negotiation phase by validating server
 384                 certificate against trusted certificate authority certificate
 385                 and certificate revocation list. Default value is true. It's
 386                 strongly recommended to keep it on.</simpara>
 387             </listitem>
 388           </varlistentry>
 389         </variablelist>
 390       </refsection>
 391
 392       <refsection>
 393         <title>Network Options</title>
 394
 395         <variablelist>
 396           <varlistentry>
 397             <term><literal>timeout</literal></term>
 398             <listitem>
 399               <simpara>Non-negative integer setting network time-out in
 400                 milliseconds. Use 0 not to limit any network operation.
 401                 Default value is 10,000 ms.</simpara>
 402             </listitem>
 403           </varlistentry>
 404         </variablelist>
 405       </refsection>
 406
 407       <refsection>
 408         <title>Log Options</title>
 409         <variablelist>
 410           <varlistentry>
 411             <term><literal>log_facilities</literal></term>
 412             <listitem>
 413               <para>List of string values selecting libisds facility to
 414                 log. Valid values are: <simplelist type="inline">
 415                   <member><literal>none</literal></member>
 416                   <member><literal>http</literal></member>
 417                   <member><literal>soap</literal></member>
 418                   <member><literal>isds</literal></member>
 419                   <member><literal>file</literal></member>
 420                   <member><literal>sec</literal></member>
 421                   <member><literal>xml</literal></member>
 422                   <member><literal>all</literal></member>
 423                 </simplelist>.
 424                 Default set is <literal>{"none"}</literal>.
 425               </para>
 426             </listitem>
 427           </varlistentry>
 428
 429           <varlistentry>
 430             <term><literal>log_file</literal></term>
 431             <listitem>
 432               <simpara>String value selecting file to append
 433                 <abbrev>ISDS</abbrev> log. The log catches libisds internal
 434                 debugging protocol. It does not cover messages produces by
 435                 shigofumi itself. This feature is designed to debug underlying
 436                 libraries and protocols like <abbrev>ISDS</abbrev>
 437                 <abbrev>SOAP</abbrev> or cURL's <abbrev>HTTP(S)</abbrev>.
 438                 If undefined, shigofumi logs to standard error output.</simpara>
 439             </listitem>
 440           </varlistentry>
 441
 442           <varlistentry>
 443             <term><literal>log_level</literal></term>
 444             <listitem>
 445               <simpara>Integer value setting log verbosity of libisds from
 446                 interval &lt;0;100&gt;. 0 is no logging, 10 is critical
 447                 messages, 20 errors, 30 warnings, 40 informative messages,
 448                 50 debug messages, 100 messages of all severities. Default
 449                 log level is 20.</simpara>
 450             </listitem>
 451           </varlistentry>
 452         </variablelist>
 453       </refsection>
 454
 455       <refsection>
 456         <title>Other Options</title>
 457         <variablelist>
 458           <varlistentry>
 459             <term><literal>normalize_mime_type</literal></term>
 460             <listitem>
 461               <simpara>Boolean switch deciding whether <abbrev>MIME</abbrev>
 462                 type of documents retrieved from a message should be normalized
 463                 to standard values. Default value is true.</simpara>
 464
 465               <simpara><abbrev>ISDS</abbrev> does not check document
 466                 <abbrev>MIME</abbrev> type a client supplies. Unfortunately,
 467                 official client sends invalid values (file name extension
 468                 usually). This option allows Shigofumi to fix the type
 469                 on-the-fly. Be ware the original value stored in
 470                 <abbrev>ISDS</abbrev> or locally saved message keeps
 471                 untouched.</simpara>
 472             </listitem>
 473           </varlistentry>
 474         </variablelist>
 475       </refsection>
 476
 477         <!--varlistentry>
 478           <term><literal></literal></term>
 479           <listitem>
 480             <simpara></simpara>
 481           </listitem>
 482         </varlistentry-->
 483     </refsection>
 484
 485     <refsection>
 486       <title>Notice on cryptographic library</title>
 487
 488       <para>Shigofumi uses libisds that utilizes cURL library that can use
 489         three different cryptographic libraries at this time: OpenSSL, GnuTLS
 490         and NSS. Each library has different set of features and different
 491         configuration. Thus exact meaning of some Shigofumi configuration
 492         options can be slightly shifted (<abbrev>e.g.</abbrev> the
 493         name of client certificate and key). Some options cannot be understood
 494         at all (<abbrev>e.g.</abbrev> GnuTLS does not support directory of
 495         certificates).</para>
 496
 497       <para>Current cryptographic library can be determined from
 498         <command>shigofumi -V</command> output.</para>
 499     </refsection>
 500
 501     <refsection>
 502       <title>Files</title>
 503       <variablelist>
 504         <varlistentry>
 505           <term><filename>~/.shigofumirc</filename></term>
 506           <listitem>
 507             <simpara>Default location of the configuration file.</simpara>
 508           </listitem>
 509         </varlistentry>
 510       </variablelist>
 511     </refsection>
 512
 513     <refsection>
 514       <title>Example</title>
 515       <programlisting><![CDATA[base_url = "https://ws1.czebox.cz/"
 516 # These credentials are invalid
 517 username = 1s79vd
 518 password = XY123456
 519 verify_server = true
 520 ca_file = /etc/ssl/certs/ca-certificates.crt
 521 ca_directory = /etc/ssl/certs
 522 crl_file = /etc/ssl/crl
 523 log_facilities = {"http", "soap"}
 524 ]]></programlisting>
 525     </refsection>
 526
 527     <refsection>
 528       <title>See Also</title>
 529       <para>
 530         <link linkend="shigofumi.1">
 531           <citerefentry>
 532             <refentrytitle>shigofumi</refentrytitle>
 533             <manvolnum>1</manvolnum>
 534           </citerefentry>
 535         </link>
 536       </para>
 537     </refsection>
 538   </refentry>
 539
 540 </reference>