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         Also quotation is supported with double quotes (<literal>"</literal>).
 131         White space and pipe symbol loose their delimiting properties until next
 132         double quotes. Backslash is still meta-character inside quoted string and
 133         it can be used to embed double quotes into quoted string.</simpara>
 134
 135       <simpara>The argument list can be terminated prematurely with pipe
 136         character (<literal>|</literal>). In that case, the rest of the line
 137         will be considered as shell command and output of preceding shigofumi
 138         command will be passed to standard input of the shell command.</simpara>
 139
 140       <simpara>If argument type is file name, you can use tilde symbol
 141         (<literal>~</literal>) as abbreviation for user's home directory. Home
 142         directory is derived from <envar>HOME</envar> environment
 143         variable.</simpara>
 144
 145       <simpara>Command names, file names and message identifiers can be
 146         completed by pressing completion key (depends on readline
 147         configuration, <keycap>Tab</keycap> usually). They are expanded only
 148         after commands expecting argument of appropriate type.</simpara>
 149
 150       <simpara>Set of available commands changes with context.
 151         <abbrev>E.g.</abbrev> If a message is loaded, commands for message
 152         operation like save to file will become available. Also meaning of the
 153         same command can change. <abbrev>E.g.</abbrev> <command>show</command>
 154         command will print list of incoming messages if such list is
 155         loaded; if a message is loaded, it will print the message. List of
 156         currently available commands can be obtained by
 157         <command>help</command> command.</simpara>
 158
 159       <simpara>Syntax help for a command is printed after calling command with
 160         invalid option or by <command>help</command> command with interested
 161         command as first argument. Command option <option>-h</option> is
 162         reserved as invalid option and shows always command usage.</simpara>
 163     </refsection>
 164
 165     <refsection>
 166       <title><abbrev>ISDS</abbrev></title>
 167
 168       <para><abbrev>ISDS</abbrev> (<phrase lang="cs">Informační systém
 169           datových schránek</phrase> / Data Box Information System) is defined
 170         by
 171         <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
 172           <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
 173         and implied documents. Current implementation details are described in
 174         <phrase lang="cs">Provozní řád</phrase> that can be downloaded from
 175         <ulink url="http://www.datoveschranky.info/ke-stazeni"><phrase
 176             lang="cs">Dokumenty ke stažení</phrase> section of
 177           <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>
 178
 179       <para>The system is designed to deliver messages between public
 180         authorities (government, courts <abbrev>etc.</abbrev>) and other
 181         entities (corporations, persons, other government or municipality
 182         offices) in reliable and traceable way.</para>
 183
 184       <para>Shigofumi implements following <abbrev>ISDS</abbrev> operations:
 185         <simplelist type="inline"><member>Log in by name and password</member>
 186           <member>Log in by name and password and one-time pasword</member>
 187           <member>Log in by name and/or password and/or X.509 certificate</member>
 188           <member>Listing incoming and outgoing message</member>
 189           <member>Accepting commercial message</member>
 190           <member>Retrieving incoming and outgoing message</member>
 191           <member>Explicit marking a message as read</member>
 192           <member>Verifying message hash</member>
 193           <member>Getting message hash stored in <abbrev>ISDS</abbrev></member>
 194           <member>Verifying message authenticity</member>
 195           <member>Retrieving delivery details</member>
 196           <member>Getting message sender name</member>
 197           <member>Sending a message to one or more recipients</member>
 198           <member>Searching a box by any criteria</member>
 199           <member>Searching a box by full-text</member>
 200           <member>Getting a box status</member>
 201           <member>Changing user password</member>
 202           <member>Getting user password expiration time</member>
 203           <member>Getting details about user's box</member>
 204           <member>Listing box users</member>
 205           <member>Getting archive with list of all boxes</member>
 206           <member>Re-signing message or delivery datails</member>
 207           <member>Getting details about credit for sending commercial messages</member>
 208       </simplelist>.</para>
 209
 210       <para>In addition, Shigofumi can save a message and delivery details
 211         into local file and load it later again. Program can save each
 212         document into local file.</para>
 213     </refsection>
 214
 215     <refsection>
 216       <title>Authorized conversion</title>
 217
 218       <para>Czech government offers a document conversion from digital to analogue
 219         form and vice versa preserving legal impacts. This is done at Czech POINT
 220         meeting place (in government, municipality or post office usually). Visit <ulink
 221         url="https://www.czechpoint.cz/">Czech POINT web site</ulink> for more
 222         details.</para>
 223
 224       <para>Shigofumi allows to submit a digital document (local file or
 225         document delivered by an <abbrev>ISDS</abbrev> message) for
 226         authorized conversion into Czech POINT deposit. If deposit accepts
 227         the document, it will return a document identifier that user is
 228         required to tell to an officer in a office where he wants to obtain
 229         analogue version of his document.</para>
 230
 231       <para>Please note the deposit keeps submitted document for limited
 232         period only. Old documents (30 days currently) are removed
 233         automatically. Note also PDF documents with valid digital signature
 234         can be converted only.</para>
 235     </refsection>
 236
 237     <refsection>
 238       <title>Environment</title>
 239       <variablelist>
 240         <varlistentry>
 241           <term><envar>EDITOR</envar></term>
 242           <listitem>
 243             <simpara>Text editor to use if <envar>VISUAL</envar> is not
 244               set.</simpara>
 245           </listitem>
 246         </varlistentry>
 247
 248         <varlistentry>
 249           <term><envar>VISUAL</envar></term>
 250           <listitem>
 251             <simpara>Text editor to use.</simpara>
 252           </listitem>
 253         </varlistentry>
 254       </variablelist>
 255     </refsection>
 256
 257     <refsection>
 258       <title>Files</title>
 259       <variablelist>
 260         <varlistentry>
 261           <term><filename>~/.shigofumirc</filename></term>
 262           <listitem>
 263             <simpara>Default configuration file location.</simpara>
 264           </listitem>
 265         </varlistentry>
 266       </variablelist>
 267     </refsection>
 268
 269     <refsection>
 270       <title>See Also</title>
 271       <para>
 272         <link linkend="shigofumirc.5">
 273           <citerefentry>
 274             <refentrytitle>shigofumirc</refentrytitle>
 275             <manvolnum>5</manvolnum>
 276           </citerefentry>
 277         </link>
 278       </para>
 279     </refsection>
 280   </refentry>
 281
 282
 283   <refentry id="shigofumirc.5">
 284     <refmeta>
 285       <refentrytitle>shigofumirc</refentrytitle>
 286       <manvolnum>5</manvolnum>
 287     </refmeta>
 288
 289     <refnamediv>
 290       <refname>shigofumirc</refname>
 291       <refpurpose>Configuration file for Shigofumi</refpurpose>
 292     </refnamediv>
 293
 294     <refsection>
 295       <title>Description</title>
 296
 297       <para>Configuration for shigofumi is loaded from
 298         <filename>.shigofumirc</filename> in user's home directory by
 299         default.</para>
 300
 301       <para>The file is plain text file with simple syntax: Setting is stored
 302         in <replaceable>option</replaceable> <literal>=</literal>
 303         <replaceable>value</replaceable> format. If value is a type of string,
 304         it must be delimited by quotation marks. Boolean values can be
 305         expressed as <literal>"true"</literal> or non-zero integer
 306         (<literal>1</literal>) for affirmation, or <literal>"false"</literal>
 307         or zero integer (<literal>0</literal>) for negation. Simple numeric
 308         values are unquoted. Commentary starts with hash sign
 309         (<literal>#</literal>) and continues to the end of the line.</para>
 310
 311       <para>If an option accepts list of values, the syntax is traditional
 312         mathematical set notation: <literal>{</literal>
 313         <replaceable>value1</replaceable> <literal>,</literal>
 314         <replaceable>value2</replaceable> <literal>}</literal>.</para>
 315     </refsection>
 316
 317     <refsection>
 318       <title>Options</title>
 319
 320       <para>Following options are recognized. Not all of them must present.
 321         Missing options fall to default value back.</para>
 322
 323       <refsection>
 324         <title>Account Options</title>
 325
 326         <variablelist>
 327           <varlistentry>
 328             <term><literal>base_url</literal></term>
 329             <listitem>
 330               <simpara>Base <abbrev>URL</abbrev> for <abbrev>ISDS</abbrev>
 331                 server.  Be careful when setting this value: This can reveal
 332                 your password to bad guys running fake server (if you do not
 333                 verify server identity preciously) and different host names
 334                 are used with different log-in mechanism. In addition, there
 335                 are two system instances administrated by Czech government:
 336                 official one and testing one.</simpara>
 337
 338               <simpara><abbrev>E.g.</abbrev> use
 339                 <literal>"https://ws1.czebox.cz/"</literal> for testing
 340                 instance of ISDS or
 341                 <literal>"https://ws1.mojedatovaschranka.cz/"</literal> for
 342                 official instance with valid and legal data when logging in
 343                 without <abbrev>TLS</abbrev> client certificate. Otherwise,
 344                 with client certificate in use, replace the
 345                 <literal>ws1</literal> domain with <literal>ws1c</literal>
 346                 domain. Or, with <abbrev>OTP</abbrev> authentication, replace
 347                 with <literal>www</literal> domain. <abbrev>I.e.</abbrev>
 348                 <literal>"https://ws1c.czebox.cz/"</literal> for testing
 349                 instance with certificate authentication or
 350                 <literal>"https://www.mojedatovaschranka.cz/"</literal> for
 351                 official instance with <abbrev>OTP</abbrev>
 352                 authentication.</simpara>
 353
 354               <simpara>Do not forget on leading protocol schema and trailing
 355                 slash. Default value is official instance locator suitable for
 356                 selected authentication method provided by libisds
 357                 library.</simpara>
 358             </listitem>
 359           </varlistentry>
 360
 361           <varlistentry>
 362             <term><literal>certificate_format</literal></term>
 363             <listitem>
 364               <simpara>Format of client certificate used to
 365                 authenticate user into <abbrev>ISDS</abbrev>. Three distinct
 366                 values are recognized: <literal>PEM</literal> for Base64
 367                 serialization to file, <literal>DER</literal> for binary
 368                 serialization to file, and <literal>ENG</literal> to specify
 369                 the certificate is stored in cryptographic engine.
 370                 Default value is empty string.</simpara>
 371             </listitem>
 372           </varlistentry>
 373
 374           <varlistentry>
 375             <term><literal>certificate_path</literal></term>
 376             <listitem>
 377               <simpara>File where client certificate used to authenticate
 378                 user into <abbrev>ISDS</abbrev> is, if
 379                 <literal>certificate_format</literal> option is set to
 380                 <literal>PEM</literal> or <literal>DER</literal>. If
 381                 <literal>certificate_format</literal> is
 382                 <literal>ENG</literal>, this is an identifier of the
 383                 certificate inside the cryptograhic engine.
 384                 <abbrev>NSS</abbrev> library uses this option as certificate
 385                 nickname. Default value is empty string signaling not to
 386                 authenticate user by a certificate.</simpara>
 387             </listitem>
 388           </varlistentry>
 389
 390           <varlistentry>
 391             <term><literal>key_engine</literal></term>
 392             <listitem>
 393               <simpara>Cryptographic engine holding client private key and/or
 394                 certificate used to authenticate user into
 395                 <abbrev>ISDS</abbrev>. The value identifies a device
 396                 (<abbrev>e.g.</abbrev> a smart card) known to underlying
 397                 cryptographic library where key and/or certificate is stored.
 398                 Interpretation depends on the cryptographic library.  This
 399                 option takes effect only if <literal>key_format</literal> or
 400                 <literal>certificate_format</literal> is
 401                 <literal>ENG</literal>.  Default value is empty
 402                 string.</simpara>
 403             </listitem>
 404           </varlistentry>
 405
 406           <varlistentry>
 407             <term><literal>key_format</literal></term>
 408             <listitem>
 409               <simpara>Format of client key used to authenticate user into
 410                 <abbrev>ISDS</abbrev>. Three distinct values are recognized:
 411                 <literal>PEM</literal> for Base64 serialization to file,
 412                 <literal>DER</literal> for binary serialization to file, and
 413                 <literal>ENG</literal> to specify the key is stored in
 414                 cryptographic engine. Default value is empty string.</simpara>
 415             </listitem>
 416           </varlistentry>
 417
 418           <varlistentry>
 419             <term><literal>key_path</literal></term>
 420             <listitem>
 421               <simpara>File where client key used to authenticate
 422                 user into <abbrev>ISDS</abbrev> is, if
 423                 <literal>key_format</literal> option is set to
 424                 <literal>PEM</literal> or <literal>DER</literal>. If
 425                 <literal>key_format</literal> is <literal>ENG</literal>, this
 426                 is an identifier of the key inside the cryptograhic engine.
 427                 <abbrev>NSS</abbrev> library uses this option as certificate
 428                 nickname. Default value is empty string. This can
 429                 mean the key is stored along the certificate.</simpara>
 430             </listitem>
 431           </varlistentry>
 432
 433           <varlistentry>
 434             <term><literal>key_password</literal></term>
 435             <listitem>
 436               <simpara>Password protecting private key used for client
 437                 authentication using asymetric cryptography. Default value is
 438                 empty string. Underlying cryptographic library can raise its
 439                 own password query or require to obtain the code in other way
 440                 (<abbrev>e.g.</abbrev> typing <abbrev>PIN</abbrev> on smart
 441                 card reader key pad).</simpara>
 442             </listitem>
 443           </varlistentry>
 444
 445           <varlistentry>
 446             <term><literal>otp_method</literal></term>
 447             <listitem>
 448               <simpara>One-time password authentication method. Default value
 449                 is undefined string what means do not use <abbrev>OTP</abbrev>
 450                 authentication. If this option is defined, <abbrev>OTP</abbrev>
 451                 will be used for authentication. Two methods are recognised:
 452                 <literal>HOTP</literal> for HMAC-based One-Time Password method
 453                 and <literal>TOTP</literal> for Time-based One-Time Password
 454                 method.</simpara>
 455             </listitem>
 456           </varlistentry>
 457
 458           <varlistentry>
 459             <term><literal>otp_code</literal></term>
 460             <listitem>
 461               <simpara>One-time code for <abbrev>OTP</abbrev>
 462                 authentication.</simpara>
 463
 464               <simpara>If HMAC-based method is used, this code will be
 465                 computed in a device or a piece of software which should be in
 466                 exclusive possession of its user.</simpara>
 467
 468               <simpara>If Time-based method is used, the code will be
 469                 generated by <abbrev>ISDS</abbrev> server and delivered to the
 470                 user by a side channel. (The channel is an
 471                 <abbrev>SMS</abbrev> currently. Because the delivery is
 472                 specialy charged, the time code generation is protected by
 473                 plain password too. User sends standard password without
 474                 <abbrev>OTP</abbrev> code first, then server delivers code by
 475                 the <abbrev>SMS</abbrev> message and finally user will retry
 476                 log-in with both password and both <abbrev>OTP</abbrev>
 477                 code.)</simpara>
 478
 479               <simpara>Default value is empty string and user will be asked
 480                 interactively for the <abbrev>OTP</abbrev> code when needed.
 481                 Because of dynamic nature of this code, setting the value in
 482                 a configuration file is pointless. However you could rewrite
 483                 this value for each shigofumi run in batch mode.</simpara>
 484             </listitem>
 485           </varlistentry>
 486
 487           <varlistentry>
 488             <term><literal>password</literal></term>
 489             <listitem>
 490               <simpara>Password assigned to given user-name. User must keep it
 491                 in secret. This password is used while <abbrev>HTTP</abbrev>
 492                 authentication and
 493                 is passed to underlying network libraries. Make sure this
 494                 configuration file or your swap partition (network library
 495                 together with password can be swapped out during physical
 496                 memory outage) will not get to bad guys. Encrypt them before.
 497                 Default value is empty string.</simpara>
 498             </listitem>
 499           </varlistentry>
 500
 501           <varlistentry>
 502             <term><literal>username</literal></term>
 503             <listitem>
 504               <simpara><abbrev>ISDS</abbrev> user log-in name. Identifies
 505                 a user in <abbrev>ISDS</abbrev>. One person can have more
 506                 identities. Default value is empty string.</simpara>
 507             </listitem>
 508           </varlistentry>
 509         </variablelist>
 510       </refsection>
 511
 512       <refsection>
 513         <title><abbrev>TLS</abbrev> Options</title>
 514
 515         <variablelist>
 516           <varlistentry>
 517             <term><literal>ca_directory</literal></term>
 518             <listitem>
 519               <simpara>Path to directory with trusted authorities certificates
 520                 stored in separate files (files must have special names
 521                 usually).  Default value is provided by underlying
 522                 cryptographic library.  Exact meaning of this option depends
 523                 on interpretation by used cryptographic library.</simpara>
 524             </listitem>
 525           </varlistentry>
 526
 527           <varlistentry>
 528             <term><literal>ca_file</literal></term>
 529             <listitem>
 530               <simpara>Path to file with trusted authorities certificates
 531                 (concatenated list of <abbrev>PEM</abbrev>-formatted
 532                 certificates). Default value is provided by underlying
 533                 cryptographic library. Exact meaning of this option depends on
 534                 interpretation by used cryptographic library.</simpara>
 535             </listitem>
 536           </varlistentry>
 537
 538           <varlistentry>
 539             <term><literal>crl_file</literal></term>
 540             <listitem>
 541               <simpara>Path to file with certificate revocation lists
 542                 (concatenated list of <abbrev>CRL</abbrev>s in
 543                 <abbrev>PEM</abbrev> format usually).  Default value is
 544                 provided by underlying cryptographic library.  Exact meaning
 545                 of this option depends on interpretation by used cryptographic
 546                 library.</simpara>
 547             </listitem>
 548           </varlistentry>
 549
 550           <varlistentry>
 551             <term><literal>verify_server</literal></term>
 552             <listitem>
 553               <simpara>Boolean switch deciding whether server identity should
 554                 be verified. When using <abbrev>HTTPS</abbrev> connection to
 555                 the server, the identity of server can be verified in
 556                 <abbrev>TLS</abbrev> negotiation phase by validating server
 557                 certificate against trusted certificate authority certificate
 558                 and certificate revocation list. Default value is true. It's
 559                 strongly recommended to keep it on.</simpara>
 560             </listitem>
 561           </varlistentry>
 562         </variablelist>
 563       </refsection>
 564
 565       <refsection>
 566         <title>Network Options</title>
 567
 568         <variablelist>
 569           <varlistentry>
 570             <term><literal>timeout</literal></term>
 571             <listitem>
 572               <simpara>Non-negative integer setting network time-out in
 573                 milliseconds. Use 0 not to limit any network operation.
 574                 Default value is 10,000 ms.</simpara>
 575             </listitem>
 576           </varlistentry>
 577         </variablelist>
 578       </refsection>
 579
 580       <refsection>
 581         <title>Log Options</title>
 582         <variablelist>
 583           <varlistentry>
 584             <term><literal>log_facilities</literal></term>
 585             <listitem>
 586               <para>List of string values selecting libisds facility to
 587                 log. Valid values are: <simplelist type="inline">
 588                   <member><literal>none</literal></member>
 589                   <member><literal>http</literal></member>
 590                   <member><literal>soap</literal></member>
 591                   <member><literal>isds</literal></member>
 592                   <member><literal>file</literal></member>
 593                   <member><literal>sec</literal></member>
 594                   <member><literal>xml</literal></member>
 595                   <member><literal>all</literal></member>
 596                 </simplelist>.
 597                 Default set is <literal>{"none"}</literal>.
 598               </para>
 599             </listitem>
 600           </varlistentry>
 601
 602           <varlistentry>
 603             <term><literal>log_file</literal></term>
 604             <listitem>
 605               <simpara>String value selecting file to append
 606                 <abbrev>ISDS</abbrev> log. The log catches libisds internal
 607                 debugging protocol. It does not cover messages produces by
 608                 shigofumi itself. This feature is designed to debug underlying
 609                 libraries and protocols like <abbrev>ISDS</abbrev>,
 610                 <abbrev>SOAP</abbrev>, or cURL's <abbrev>HTTP(S)</abbrev>.
 611                 If undefined, shigofumi logs to standard error output.</simpara>
 612             </listitem>
 613           </varlistentry>
 614
 615           <varlistentry>
 616             <term><literal>log_level</literal></term>
 617             <listitem>
 618               <simpara>Integer value setting log verbosity of libisds from
 619                 interval &lt;0;100&gt;. 0 is no logging, 10 is critical
 620                 messages, 20 errors, 30 warnings, 40 informative messages,
 621                 50 debug messages, 100 messages of all severities. Default
 622                 log level is 20.</simpara>
 623             </listitem>
 624           </varlistentry>
 625         </variablelist>
 626       </refsection>
 627
 628       <refsection>
 629         <title>Other Options</title>
 630         <variablelist>
 631           <varlistentry>
 632             <term><literal>clean_temporary_files</literal></term>
 633             <listitem>
 634               <simpara>Boolean switch deciding whether to remove temporary
 635                 files at shigofumi exit. This applies to files created for
 636                 <command>opendoc</command> command, as external utility can
 637                 access the file after quiting shigofumi. Default value is
 638                 true.</simpara>
 639             </listitem>
 640           </varlistentry>
 641
 642           <varlistentry>
 643             <term><literal>confirm_send</literal></term>
 644             <listitem>
 645               <simpara>Boolean switch deciding whether to require confirmation
 646                 before sending composed message. Default value is
 647                 true.</simpara>
 648             </listitem>
 649           </varlistentry>
 650
 651           <varlistentry>
 652             <term><literal>mark_message_read</literal></term>
 653             <listitem>
 654               <simpara>Boolean switch deciding whether right downloaded
 655                 incoming messages should be marked as read automatically.
 656                 If true, change message state to read on the server.
 657                 Otherwise keep message state intact. Default value is
 658                 false.</simpara>
 659
 660               <simpara>You can change the state to read state by
 661                 <command>read</command> command manually latter.</simpara>
 662
 663               <simpara>Be ware <abbrev>ISDS</abbrev> web portal marks messages
 664                 as read automatically. Note, there is no way to unmark
 665                 a message to unread state back.</simpara>
 666             </listitem>
 667           </varlistentry>
 668
 669           <varlistentry>
 670             <term><literal>normalize_mime_type</literal></term>
 671             <listitem>
 672               <simpara>Boolean switch deciding whether <abbrev>MIME</abbrev>
 673                 type of documents retrieved from a message should be normalized
 674                 to standard values. Default value is true.</simpara>
 675
 676               <simpara><abbrev>ISDS</abbrev> does not check document
 677                 <abbrev>MIME</abbrev> type a client supplies. Unfortunately,
 678                 official client sends invalid values (file name extension
 679                 usually). This option allows Shigofumi to fix the type
 680                 on-the-fly. Be ware the original value stored in
 681                 <abbrev>ISDS</abbrev> or locally saved message keeps
 682                 untouched.</simpara>
 683             </listitem>
 684           </varlistentry>
 685
 686           <varlistentry>
 687             <term><literal>open_command</literal></term>
 688             <listitem>
 689               <simpara>List of string values defining external utility to
 690                 execute when opening a document.</simpara>
 691
 692               <simpara>First value is command, other values are command
 693                 arguments in order. If command is not absolute file name, it's
 694                 located according <envar>PATH</envar> environment variable.
 695                 If value contains <literal>%f</literal> substring, it will be
 696                 expanded to name of file to open. If value contains
 697                 <literal>%t</literal> substring, it will be expanded to
 698                 <abbrev>MIME</abbrev> type of document to open. Use
 699                 <literal>%%</literal> sequence to escape per-cent
 700                 character.</simpara>
 701
 702               <simpara>Default value is
 703                 <literal>{"xdg-open", "%f"}</literal>.</simpara>
 704             </listitem>
 705           </varlistentry>
 706
 707           <varlistentry>
 708             <term><literal>overwrite_files</literal></term>
 709             <listitem>
 710               <simpara>Boolean switch deciding whether newly created files
 711                 should overwrite existing ones. If true, existing files will
 712                 be overwritten silently. Otherwise error wil be raised.
 713                 Default value is true.</simpara>
 714
 715               <simpara>This does not apply to log file. Its new content is
 716                 appended always.</simpara>
 717             </listitem>
 718           </varlistentry>
 719         </variablelist>
 720       </refsection>
 721
 722         <!--varlistentry>
 723           <term><literal></literal></term>
 724           <listitem>
 725             <simpara></simpara>
 726           </listitem>
 727         </varlistentry-->
 728     </refsection>
 729
 730     <refsection>
 731       <title>Notice on cryptographic library</title>
 732
 733       <para>Shigofumi uses libisds that utilizes cURL library that can use
 734         three different cryptographic libraries at this time: OpenSSL, GnuTLS
 735         and NSS. Each library has different set of features and different
 736         configuration. Thus exact meaning of some Shigofumi configuration
 737         options can be slightly shifted (<abbrev>e.g.</abbrev> the
 738         name of client certificate and key). Some options cannot be understood
 739         at all (<abbrev>e.g.</abbrev> GnuTLS does not support directory of
 740         certificates).</para>
 741
 742       <para>Current cryptographic library can be determined from
 743         <command>shigofumi -V</command> output.</para>
 744     </refsection>
 745
 746     <refsection>
 747       <title>Files</title>
 748       <variablelist>
 749         <varlistentry>
 750           <term><filename>~/.shigofumirc</filename></term>
 751           <listitem>
 752             <simpara>Default location of the configuration file.</simpara>
 753           </listitem>
 754         </varlistentry>
 755       </variablelist>
 756     </refsection>
 757
 758     <refsection>
 759       <title>Example</title>
 760       <programlisting><![CDATA[base_url = "https://ws1.czebox.cz/"
 761 # These credentials are invalid
 762 username = 1s79vd
 763 password = XY123456
 764 verify_server = true
 765 ca_file = /etc/ssl/certs/ca-certificates.crt
 766 ca_directory = /etc/ssl/certs
 767 crl_file = /etc/ssl/crl
 768 log_facilities = {"http", "soap"}
 769 ]]></programlisting>
 770     </refsection>
 771
 772     <refsection>
 773       <title>See Also</title>
 774       <para>
 775         <link linkend="shigofumi.1">
 776           <citerefentry>
 777             <refentrytitle>shigofumi</refentrytitle>
 778             <manvolnum>1</manvolnum>
 779           </citerefentry>
 780         </link>
 781       </para>
 782     </refsection>
 783   </refentry>
 784
 785 </reference>