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