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">
11 <firstname>Petr</firstname>
12 <surname>Písař</surname>
15 <simpara>He's written Shigofumi and libisds.</simpara>
18 <productname>Shigofumi</productname>
21 <title>Manual for Shigofumi</title>
24 <refentry id="shigofumi.1">
26 <refentrytitle>shigofumi</refentrytitle>
27 <manvolnum>1</manvolnum>
31 <refname>shigofumi</refname>
32 <refpurpose>ISDS client</refpurpose>
37 <command>shigofumi</command>
38 <arg choice="opt"><option>-c</option> <replaceable>FILE</replaceable></arg>
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>
49 <command>shigofumi</command>
50 <arg choice="plain"><option>-V</option></arg>
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
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>
76 <title>Options</title>
80 <term><option>-c <replaceable>FILE</replaceable></option></term>
82 <simpara>Use configuration <replaceable>FILE</replaceable> instead
83 of default one.</simpara>
88 <term><option>-e <replaceable>COMMANDS</replaceable></option></term>
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
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>
113 <term><option>-V</option></term>
115 <simpara>Show program version and linked libraries details and
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 String quotation is not currently supported.</simpara>
132 <simpara>The argument list can be terminated prematurely with pipe
133 character (<literal>|</literal>). In that case, the rest of the line
134 will be considered as shell command and output of preceding shigofumi
135 command will be passed to standard input of the shell command.</simpara>
137 <simpara>If argument type is file name, you can use tilde symbol
138 (<literal>~</literal>) as abbreviation for user's home directory. Home
139 directory is derived from <envar>HOME</envar> environment
142 <simpara>Command names, file names and message identifiers can be
143 completed by pressing completion key (depends on readline
144 configuration, <keycap>Tab</keycap> usually). They are expanded only
145 after commands expecting argument of appropriate type.</simpara>
147 <simpara>Set of available commands changes with context.
148 <abbrev>E.g.</abbrev> If a message is loaded, commands for message
149 operation like save to file will become available. Also meaning of the
150 same command can change. <abbrev>E.g.</abbrev> <command>show</command>
151 command will print list of incoming messages if such list is
152 loaded; if a message is loaded, it will print the message. List of
153 currently available commands can be obtained by
154 <command>help</command> command.</simpara>
156 <simpara>Syntax help for a command is printed after calling command with
157 invalid option or by <command>help</command> command with interested
158 command as first argument. Command option <option>-h</option> is
159 reserved as invalid option and shows always command usage.</simpara>
163 <title><abbrev>ISDS</abbrev></title>
165 <para><abbrev>ISDS</abbrev> (<phrase lang="cs">Informační systém
166 datových schránek</phrase> / Data Box Information System) is defined
168 <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
169 <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
170 and implied documents. Current implementation details are described in
171 <phrase lang="cs">Provozní řád</phrase> that can be downloaded from
172 <ulink url="http://www.datoveschranky.info/dokumenty/">Documents
173 section of <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>
175 <para>The system is designed to deliver messages between public
176 authorities (government, courts <abbrev>etc.</abbrev>) and other
177 entities (corporations, persons, other government or municipality
178 offices) in reliable and traceable way.</para>
180 <para>Shigofumi implements following <abbrev>ISDS</abbrev> operations:
181 <simplelist type="inline"><member>Log in by name and password</member>
182 <member>Listing incoming and outgoing message</member>
183 <member>Accepting commercial message</member>
184 <member>Retrieving incoming and outgoing message</member>
185 <member>Explicit marking a message as read</member>
186 <member>Verifying message hash</member>
187 <member>Getting message hash stored in <abbrev>ISDS</abbrev></member>
188 <member>Verifying message authenticity</member>
189 <member>Retrieving delivery details</member>
190 <member>Getting message sender name</member>
191 <member>Sending a message to one or more recipients</member>
192 <member>Searching a box by any criteria</member>
193 <member>Getting a box status</member>
194 <member>Changing user password</member>
195 <member>Getting user password expiration time</member>
196 <member>Getting details about user's box</member>
197 <member>Listing box users</member>
198 <member>Getting archive with list of all boxes</member>
199 </simplelist>.</para>
201 <para>In addition, Shigofumi can save a message and delivery details
202 into local file and load it later again. Program can save each
203 document into local file.</para>
207 <title>Authorized conversion</title>
209 <para>Czech government offers a document conversion from digital to analogue
210 form and vice versa preserving legal impacts. This is done at Czech POINT
211 meeting place (in government, municipality or post office usually). Visit <ulink
212 url="https://www.czechpoint.cz/">Czech POINT web site</ulink> for more
215 <para>Shigofumi allows to submit a digital document (local file or
216 document delivered by an <abbrev>ISDS</abbrev> message) for
217 authorized conversion into Czech POINT deposit. If deposit accepts
218 the document, it will return a document identifier that user is
219 required to tell to an officer in a office where he wants to obtain
220 analogue version of his document.</para>
222 <para>Please note the deposit keeps submitted document for limited
223 period only. Old documents (30 days currently) are removed
224 automatically. Note also PDF documents with valid digital signature
225 can be converted only.</para>
232 <term><filename>~/.shigofumirc</filename></term>
234 <simpara>Default configuration file location.</simpara>
241 <title>See Also</title>
243 <link linkend="shigofumirc.5">
245 <refentrytitle>shigofumirc</refentrytitle>
246 <manvolnum>5</manvolnum>
254 <refentry id="shigofumirc.5">
256 <refentrytitle>shigofumirc</refentrytitle>
257 <manvolnum>5</manvolnum>
261 <refname>shigofumirc</refname>
262 <refpurpose>Configuration file for Shigofumi</refpurpose>
266 <title>Description</title>
268 <para>Configuration for shigofumi is loaded from
269 <filename>.shigofumirc</filename> in user's home directory by
272 <para>The file is plain text file with simple syntax: Setting is stored
273 in <replaceable>option</replaceable> <literal>=</literal>
274 <replaceable>value</replaceable> format. If value is a type of string,
275 it must be delimited by quotation marks. Boolean values can be
276 expressed as <literal>"true"</literal> or non-zero integer
277 (<literal>1</literal>) for affirmation, or <literal>"false"</literal>
278 or zero integer (<literal>0</literal>) for negation. Simple numeric
279 values are unquoted. Commentary starts with hash sign
280 (<literal>#</literal>) and continues to the end of the line.</para>
282 <para>If an option accepts list of values, the syntax is traditional
283 mathematical set notation: <literal>{</literal>
284 <replaceable>value1</replaceable> <literal>,</literal>
285 <replaceable>value2</replaceable> <literal>}</literal>.</para>
289 <title>Options</title>
291 <para>Following options are recognized. Not all of them must present.
292 Missing options fall to default value back.</para>
295 <title>Account Options</title>
299 <term><literal>base_url</literal></term>
301 <simpara>Base <abbrev>URL</abbrev> for <abbrev>ISDS</abbrev>
302 server. Be careful when setting this value: This can reveal
303 your password to bad guys running fake server (if you do not
304 verify server identity preciously) and different host names
305 are used with different log-in mechanism. In addition, there
306 are two system instances administrated by Czech government:
307 official one and testing one.</simpara>
309 <simpara><abbrev>E.g.</abbrev> use
310 <literal>"https://ws1.czebox.cz/"</literal> for testing
312 <literal>"https://ws1.mojedatovaschranka.cz/"</literal> for
313 official instance with valid and legal data when logging in
314 without <abbrev>TLS</abbrev> client certificate. Otherwise,
315 with client certificate in use, replace the
316 <literal>ws1</literal> domain with <literal>ws1c</literal>
317 domain. Or, with <abbrev>OTP</abbrev> authentication, replace
318 with <literal>www</literal> domain. <abbrev>I.e.</abbrev>
319 <literal>"https://ws1c.czebox.cz/"</literal> for testing
320 instance with certificate authentication or
321 <literal>"https://www.mojedatovaschranka.cz/"</literal> for
322 official instance with <abbrev>OTP</abbrev>
323 authentication.</simpara>
325 <simpara>Do not forget on leading protocol schema and trailing
326 slash. Default value is official instance locator suitable for
327 selected authentication method provided by libisds
333 <term><literal>certificate_format</literal></term>
335 <simpara>Format of client certificate used to
336 authenticate user into <abbrev>ISDS</abbrev>. Three distinct
337 values are recognized: <literal>PEM</literal> for Base64
338 serialization to file, <literal>DER</literal> for binary
339 serialization to file, and <literal>ENG</literal> to specify
340 the certificate is stored in cryptographic engine.
341 Default value is empty string.</simpara>
346 <term><literal>certificate_path</literal></term>
348 <simpara>File where client certificate used to authenticate
349 user into <abbrev>ISDS</abbrev> is, if
350 <literal>certificate_format</literal> option is set to
351 <literal>PEM</literal> or <literal>DER</literal>. If
352 <literal>certificate_format</literal> is
353 <literal>ENG</literal>, this is an identifier of the
354 certificate inside the cryptograhic engine.
355 <abbrev>NSS</abbrev> library uses this option as certificate
356 nickname. Default value is empty string signaling not to
357 authenticate user by a certificate.</simpara>
362 <term><literal>key_engine</literal></term>
364 <simpara>Cryptographic engine holding client private key and/or
365 certificate used to authenticate user into
366 <abbrev>ISDS</abbrev>. The value identifies a device
367 (<abbrev>e.g.</abbrev> a smart card) known to underlying
368 cryptographic library where key and/or certificate is stored.
369 Interpretation depends on the cryptographic library. This
370 option takes effect only if <literal>key_format</literal> or
371 <literal>certificate_format</literal> is
372 <literal>ENG</literal>. Default value is empty
378 <term><literal>key_format</literal></term>
380 <simpara>Format of client key used to authenticate user into
381 <abbrev>ISDS</abbrev>. Three distinct values are recognized:
382 <literal>PEM</literal> for Base64 serialization to file,
383 <literal>DER</literal> for binary serialization to file, and
384 <literal>ENG</literal> to specify the key is stored in
385 cryptographic engine. Default value is empty string.</simpara>
390 <term><literal>key_path</literal></term>
392 <simpara>File where client key used to authenticate
393 user into <abbrev>ISDS</abbrev> is, if
394 <literal>key_format</literal> option is set to
395 <literal>PEM</literal> or <literal>DER</literal>. If
396 <literal>key_format</literal> is <literal>ENG</literal>, this
397 is an identifier of the key inside the cryptograhic engine.
398 <abbrev>NSS</abbrev> library uses this option as certificate
399 nickname. Default value is empty string. This can
400 mean the key is stored along the certificate.</simpara>
405 <term><literal>key_password</literal></term>
407 <simpara>Password protecting private key used for client
408 authentication using asymetric cryptography. Default value is
409 empty string. Underlying cryptographic library can raise its
410 own password query or require to obtain the code in other way
411 (<abbrev>e.g.</abbrev> typing <abbrev>PIN</abbrev> on smart
412 card reader key pad).</simpara>
417 <term><literal>otp_method</literal></term>
419 <simpara>One-time password authentication method. Default value
420 is undefined string what means do not use <abbrev>OTP</abbrev>
421 authentication. If this option is defined, <abbrev>OTP</abbrev>
422 will be used for authentication. Two methods are recognised:
423 <literal>HOTP</literal> for HMAC-based One-Time Password method
424 and <literal>TOTP</literal> for Time-based One-Time Password
430 <term><literal>otp_code</literal></term>
432 <simpara>One-time code for <abbrev>OTP</abbrev>
433 authentication.</simpara>
435 <simpara>If HMAC-based method is used, this code will be
436 computed in a device or a piece of software which should be in
437 exclusive possession of its user.</simpara>
439 <simpara>If Time-based method is used, the code will be
440 generated by <abbrev>ISDS</abbrev> server and delivered to the
441 user by a side channel. (The channel is an
442 <abbrev>SMS</abbrev> currently. Because the delivery is
443 specialy charged, the time code generation is protected by
444 plain password too. User sends standard password without
445 <abbrev>OTP</abbrev> code first, then server delivers code by
446 the <abbrev>SMS</abbrev> message and finally user will retry
447 log-in with both password and both <abbrev>OTP</abbrev>
450 <simpara>Default value is empty string and user will be asked
451 interactively for the <abbrev>OTP</abbrev> code when needed.
452 Because of dynamic nature of this code, setting the value in
453 a configuration file is pointless. However you could rewrite
454 this value for each shigofumi run in batch mode.</simpara>
459 <term><literal>password</literal></term>
461 <simpara>Password assigned to given user-name. User must keep it
462 in secret. This password is used while <abbrev>HTTP</abbrev>
464 is passed to underlying network libraries. Make sure this
465 configuration file or your swap partition (network library
466 together with password can be swapped out during physical
467 memory outage) will not get to bad guys. Encrypt them before.
468 Default value is empty string.</simpara>
473 <term><literal>username</literal></term>
475 <simpara><abbrev>ISDS</abbrev> user log-in name. Identifies
476 a user in <abbrev>ISDS</abbrev>. One person can have more
477 identities. Default value is empty string.</simpara>
484 <title><abbrev>TLS</abbrev> Options</title>
488 <term><literal>ca_directory</literal></term>
490 <simpara>Path to directory with trusted authorities certificates
491 stored in separate files (files must have special names
492 usually). Default value is provided by underlying
493 cryptographic library. Exact meaning of this option depends
494 on interpretation by used cryptographic library.</simpara>
499 <term><literal>ca_file</literal></term>
501 <simpara>Path to file with trusted authorities certificates
502 (concatenated list of <abbrev>PEM</abbrev>-formatted
503 certificates). Default value is provided by underlying
504 cryptographic library. Exact meaning of this option depends on
505 interpretation by used cryptographic library.</simpara>
510 <term><literal>crl_file</literal></term>
512 <simpara>Path to file with certificate revocation lists
513 (concatenated list of <abbrev>CRL</abbrev>s in
514 <abbrev>PEM</abbrev> format usually). Default value is
515 provided by underlying cryptographic library. Exact meaning
516 of this option depends on interpretation by used cryptographic
522 <term><literal>verify_server</literal></term>
524 <simpara>Boolean switch deciding whether server identity should
525 be verified. When using <abbrev>HTTPS</abbrev> connection to
526 the server, the identity of server can be verified in
527 <abbrev>TLS</abbrev> negotiation phase by validating server
528 certificate against trusted certificate authority certificate
529 and certificate revocation list. Default value is true. It's
530 strongly recommended to keep it on.</simpara>
537 <title>Network Options</title>
541 <term><literal>timeout</literal></term>
543 <simpara>Non-negative integer setting network time-out in
544 milliseconds. Use 0 not to limit any network operation.
545 Default value is 10,000 ms.</simpara>
552 <title>Log Options</title>
555 <term><literal>log_facilities</literal></term>
557 <para>List of string values selecting libisds facility to
558 log. Valid values are: <simplelist type="inline">
559 <member><literal>none</literal></member>
560 <member><literal>http</literal></member>
561 <member><literal>soap</literal></member>
562 <member><literal>isds</literal></member>
563 <member><literal>file</literal></member>
564 <member><literal>sec</literal></member>
565 <member><literal>xml</literal></member>
566 <member><literal>all</literal></member>
568 Default set is <literal>{"none"}</literal>.
574 <term><literal>log_file</literal></term>
576 <simpara>String value selecting file to append
577 <abbrev>ISDS</abbrev> log. The log catches libisds internal
578 debugging protocol. It does not cover messages produces by
579 shigofumi itself. This feature is designed to debug underlying
580 libraries and protocols like <abbrev>ISDS</abbrev>,
581 <abbrev>SOAP</abbrev>, or cURL's <abbrev>HTTP(S)</abbrev>.
582 If undefined, shigofumi logs to standard error output.</simpara>
587 <term><literal>log_level</literal></term>
589 <simpara>Integer value setting log verbosity of libisds from
590 interval <0;100>. 0 is no logging, 10 is critical
591 messages, 20 errors, 30 warnings, 40 informative messages,
592 50 debug messages, 100 messages of all severities. Default
593 log level is 20.</simpara>
600 <title>Other Options</title>
603 <term><literal>clean_temporary_files</literal></term>
605 <simpara>Boolean switch deciding whether to remove temporary
606 files at shigofumi exit. This applies to files created for
607 <command>opendoc</command> command, as external utility can
608 access the file after quiting shigofumi. Default value is
614 <term><literal>mark_message_read</literal></term>
616 <simpara>Boolean switch deciding whether right downloaded
617 incoming messages should be marked as read automatically.
618 If true, change message state to read on the server.
619 Otherwise keep message state intact. Default value is
622 <simpara>You can change the state to read state by
623 <command>read</command> command manually latter.</simpara>
625 <simpara>Be ware <abbrev>ISDS</abbrev> web portal marks messages
626 as read automatically. Note, there is no way to unmark
627 a message to unread state back.</simpara>
632 <term><literal>normalize_mime_type</literal></term>
634 <simpara>Boolean switch deciding whether <abbrev>MIME</abbrev>
635 type of documents retrieved from a message should be normalized
636 to standard values. Default value is true.</simpara>
638 <simpara><abbrev>ISDS</abbrev> does not check document
639 <abbrev>MIME</abbrev> type a client supplies. Unfortunately,
640 official client sends invalid values (file name extension
641 usually). This option allows Shigofumi to fix the type
642 on-the-fly. Be ware the original value stored in
643 <abbrev>ISDS</abbrev> or locally saved message keeps
649 <term><literal>open_command</literal></term>
651 <simpara>List of string values defining external utility to
652 execute when opening a document.</simpara>
654 <simpara>First value is command, other values are command
655 arguments in order. If command is not absolute file name, it's
656 located according <envar>PATH</envar> environment variable.
657 If value contains <literal>%f</literal> substring, it will be
658 expanded to name of file to open. If value contains
659 <literal>%t</literal> substring, it will be expanded to
660 <abbrev>MIME</abbrev> type of document to open. Use
661 <literal>%%</literal> sequence to escape per-cent
664 <simpara>Default value is
665 <literal>{"xdg-open", "%f"}</literal>.</simpara>
670 <term><literal>overwrite_files</literal></term>
672 <simpara>Boolean switch deciding whether newly created files
673 should overwrite existing ones. If true, existing files will
674 be overwritten silently. Otherwise error wil be raised.
675 Default value is true.</simpara>
677 <simpara>This does not apply to log file. Its new content is
678 appended always.</simpara>
685 <term><literal></literal></term>
693 <title>Notice on cryptographic library</title>
695 <para>Shigofumi uses libisds that utilizes cURL library that can use
696 three different cryptographic libraries at this time: OpenSSL, GnuTLS
697 and NSS. Each library has different set of features and different
698 configuration. Thus exact meaning of some Shigofumi configuration
699 options can be slightly shifted (<abbrev>e.g.</abbrev> the
700 name of client certificate and key). Some options cannot be understood
701 at all (<abbrev>e.g.</abbrev> GnuTLS does not support directory of
702 certificates).</para>
704 <para>Current cryptographic library can be determined from
705 <command>shigofumi -V</command> output.</para>
712 <term><filename>~/.shigofumirc</filename></term>
714 <simpara>Default location of the configuration file.</simpara>
721 <title>Example</title>
722 <programlisting><![CDATA[base_url = "https://ws1.czebox.cz/"
723 # These credentials are invalid
727 ca_file = /etc/ssl/certs/ca-certificates.crt
728 ca_directory = /etc/ssl/certs
729 crl_file = /etc/ssl/crl
730 log_facilities = {"http", "soap"}
735 <title>See Also</title>
737 <link linkend="shigofumi.1">
739 <refentrytitle>shigofumi</refentrytitle>
740 <manvolnum>1</manvolnum>