1SHIGOFUMIRC(5)               Manual for Shigofumi               SHIGOFUMIRC(5)
2
3
4

NAME

6       shigofumirc - Configuration file for Shigofumi
7

DESCRIPTION

9       Configuration  for shigofumi is loaded from .shigofumirc in user's home
10       directory by default.
11
12       The file is plain text file with simple syntax: Setting  is  stored  in
13       option  = value format. If value is a type of string, it must be delim‐
14       ited by quotation marks. Boolean values can be expressed as  "true"  or
15       non-zero  integer  (1)  for affirmation, or "false" or zero integer (0)
16       for negation. Simple numeric values  are  unquoted.  Commentary  starts
17       with hash sign (#) and continues to the end of the line.
18
19       If  an  option accepts list of values, the syntax is traditional mathe‐
20       matical set notation: { value1 , value2 }.
21

OPTIONS

23       Following options are recognized. Not all of them must present. Missing
24       options fall to default value back.
25
26   Account Options
27       base_url
28           Base  URL for ISDS server. Be careful when setting this value: This
29           can reveal your password to bad guys running fake server (if you do
30           not verify server identity preciously) and different host names are
31           used with different log-in mechanism. In addition,  there  are  two
32           system  instances  administrated  by Czech government: official one
33           and testing one.
34
35           E.g.  use "https://ws1.czebox.cz/" for testing instance of ISDS  or
36           "https://ws1.mojedatovaschranka.cz/"  for  official  instance  with
37           valid and legal data when logging in without  TLS  client  certifi‐
38           cate.  Otherwise,  with  client certificate in use, replace the ws1
39           domain with ws1c domain. Or, with OTP authentication, replace  with
40           www  domain.   I.e.  "https://ws1c.czebox.cz/" for testing instance
41           with   certificate   authentication    or    "https://www.mojedato
42           vaschranka.cz/" for official instance with OTP authentication.
43
44           Do  not  forget  on  leading  protocol  schema  and trailing slash.
45           Default value is official instance locator  suitable  for  selected
46           authentication method provided by libisds library.
47
48       certificate_format
49           Format  of  client certificate used to authenticate user into ISDS.
50           Three distinct values are recognized: PEM for Base64  serialization
51           to  file,  DER for binary serialization to file, and ENG to specify
52           the certificate is stored in cryptographic engine. Default value is
53           empty string.
54
55       certificate_path
56           File  where  client certificate used to authenticate user into ISDS
57           is, if certificate_format option is set to PEM or DER. If  certifi‐
58           cate_format is ENG, this is an identifier of the certificate inside
59           the cryptograhic engine.  NSS library uses this option as  certifi‐
60           cate  nickname.  Default  value  is  empty  string signaling not to
61           authenticate user by a certificate.
62
63       key_engine
64           Cryptographic engine holding client private key and/or  certificate
65           used  to authenticate user into ISDS. The value identifies a device
66           (e.g.  a smart card)  known  to  underlying  cryptographic  library
67           where  key  and/or certificate is stored. Interpretation depends on
68           the  cryptographic  library.  This  option  takes  effect  only  if
69           key_format  or  certificate_format  is  ENG. Default value is empty
70           string.
71
72       key_format
73           Format of client key used to authenticate  user  into  ISDS.  Three
74           distinct  values  are  recognized:  PEM for Base64 serialization to
75           file, DER for binary serialization to file, and ENG to specify  the
76           key  is  stored  in  cryptographic  engine.  Default value is empty
77           string.
78
79       key_path
80           File where client key used to authenticate user into  ISDS  is,  if
81           key_format  option is set to PEM or DER. If key_format is ENG, this
82           is an identifier of the key inside the  cryptograhic  engine.   NSS
83           library  uses this option as certificate nickname. Default value is
84           empty string. This can mean the key is stored  along  the  certifi‐
85           cate.
86
87       key_password
88           Password  protecting  private  key  used  for client authentication
89           using asymetric cryptography. Default value is empty string. Under‐
90           lying  cryptographic  library  can  raise its own password query or
91           require to obtain the code in other way (e.g.  typing PIN on  smart
92           card reader key pad).
93
94       otp_method
95           One-time password authentication method. Default value is undefined
96           string what means do not use OTP authentication. If this option  is
97           defined,  OTP  will  be  used  for  authentication. Two methods are
98           recognised: HOTP for HMAC-based One-Time Password method  and  TOTP
99           for Time-based One-Time Password method.
100
101       otp_code
102           One-time code for OTP authentication.
103
104           If  HMAC-based  method  is  used,  this  code will be computed in a
105           device or a piece of software which should be in exclusive  posses‐
106           sion of its user.
107
108           If  Time-based  method  is used, the code will be generated by ISDS
109           server and delivered to the user by a side channel. (The channel is
110           an  SMS  currently.  Because  the delivery is specialy charged, the
111           time code generation is protected by plain password too. User sends
112           standard password without OTP code first, then server delivers code
113           by the SMS message and finally user will  retry  log-in  with  both
114           password and both OTP code.)
115
116           Default  value is empty string and user will be asked interactively
117           for the OTP code when needed. Because of  dynamic  nature  of  this
118           code,  setting the value in a configuration file is pointless. How‐
119           ever you could rewrite this value for each shigofumi run  in  batch
120           mode.
121
122       password
123           Password  assigned to given user-name. User must keep it in secret.
124           This password is used while HTTP authentication and  is  passed  to
125           underlying  network libraries. Make sure this configuration file or
126           your swap partition (network library together with password can  be
127           swapped  out  during  physical  memory  outage) will not get to bad
128           guys. Encrypt them before. Default value is empty string.
129
130       username
131           ISDS user log-in name. Identifies a user in ISDS.  One  person  can
132           have more identities. Default value is empty string.
133
134   TLS Options
135       ca_directory
136           Path  to  directory with trusted authorities certificates stored in
137           separate files (files must have  special  names  usually).  Default
138           value  is provided by underlying cryptographic library. Exact mean‐
139           ing of this option depends on interpretation by used  cryptographic
140           library.
141
142       ca_file
143           Path  to  file  with trusted authorities certificates (concatenated
144           list of PEM-formatted certificates). Default value is  provided  by
145           underlying  cryptographic  library.  Exact  meaning  of this option
146           depends on interpretation by used cryptographic library.
147
148       crl_file
149           Path to file with certificate revocation lists  (concatenated  list
150           of CRLs in PEM format usually). Default value is provided by under‐
151           lying cryptographic library. Exact meaning of this  option  depends
152           on interpretation by used cryptographic library.
153
154       verify_server
155           Boolean switch deciding whether server identity should be verified.
156           When using HTTPS connection to the server, the identity  of  server
157           can  be verified in TLS negotiation phase by validating server cer‐
158           tificate against trusted certificate authority certificate and cer‐
159           tificate revocation list. Default value is true. It's strongly rec‐
160           ommended to keep it on.
161
162   Network Options
163       timeout
164           Non-negative integer setting network time-out in milliseconds.  Use
165           0 not to limit any network operation. Default value is 10,000 ms.
166
167   Log Options
168       log_facilities
169           List of string values selecting libisds facility to log. Valid val‐
170           ues are: none, http, soap, isds, file, sec, xml, all.  Default  set
171           is {"none"}.
172
173       log_file
174           String  value  selecting  file  to append ISDS log. The log catches
175           libisds internal debugging protocol. It  does  not  cover  messages
176           produces  by  shigofumi  itself.  This feature is designed to debug
177           underlying libraries and  protocols  like  ISDS,  SOAP,  or  cURL's
178           HTTP(S). If undefined, shigofumi logs to standard error output.
179
180       log_level
181           Integer  value  setting  log  verbosity  of  libisds  from interval
182           <0;100>. 0 is no logging, 10 is critical messages,  20  errors,  30
183           warnings,  40 informative messages, 50 debug messages, 100 messages
184           of all severities. Default log level is 20.
185
186   Other Options
187       clean_temporary_files
188           Boolean switch deciding whether to remove temporary files at shigo‐
189           fumi  exit.  This  applies to files created for opendoc command, as
190           external utility can  access  the  file  after  quiting  shigofumi.
191           Default value is true.
192
193       confirm_send
194           Boolean  switch  deciding  whether  to  require confirmation before
195           sending composed message. Default value is true.
196
197       mark_message_read
198           Boolean switch deciding whether right downloaded incoming  messages
199           should  be  marked  as  read automatically. If true, change message
200           state to read on the server. Otherwise keep message  state  intact.
201           Default value is false.
202
203           You  can  change  the  state to read state by read command manually
204           latter.
205
206           Be ware ISDS web portal marks messages as read automatically. Note,
207           there is no way to unmark a message to unread state back.
208
209       normalize_mime_type
210           Boolean  switch  deciding  whether MIME type of documents retrieved
211           from a message should be normalized  to  standard  values.  Default
212           value is true.
213
214           ISDS  does not check document MIME type a client supplies. Unfortu‐
215           nately, official client sends invalid values (file  name  extension
216           usually).  This option allows Shigofumi to fix the type on-the-fly.
217           Be ware the original value stored in ISDS or locally saved  message
218           keeps untouched.
219
220       open_command
221           List  of  string  values  defining external utility to execute when
222           opening a document.
223
224           First value is command,  other  values  are  command  arguments  in
225           order. If command is not absolute file name, it's located according
226           PATH environment variable. If value contains %f substring, it  will
227           be  expanded  to  name  of  file to open. If value contains %t sub‐
228           string, it will be expanded to MIME type of document to  open.  Use
229           %% sequence to escape per-cent character.
230
231           Default value is {"xdg-open", "%f"}.
232
233       overwrite_files
234           Boolean  switch  deciding  whether newly created files should over‐
235           write existing ones. If true, existing files  will  be  overwritten
236           silently. Otherwise error wil be raised. Default value is true.
237
238           This  does  not  apply  to  log  file.  Its new content is appended
239           always.
240

NOTICE ON CRYPTOGRAPHIC LIBRARY

242       Shigofumi uses libisds that utilizes cURL library that  can  use  three
243       different  cryptographic  libraries  at  this time: OpenSSL, GnuTLS and
244       NSS. Each library has different set of features and different  configu‐
245       ration.  Thus exact meaning of some Shigofumi configuration options can
246       be slightly shifted (e.g.  the name of  client  certificate  and  key).
247       Some options cannot be understood at all (e.g.  GnuTLS does not support
248       directory of certificates).
249
250       Current cryptographic library can be determined from shigofumi -V  out‐
251       put.
252

FILES

254       ~/.shigofumirc
255           Default location of the configuration file.
256

EXAMPLE

258           base_url = "https://ws1.czebox.cz/"
259           # These credentials are invalid
260           username = 1s79vd
261           password = XY123456
262           verify_server = true
263           ca_file = /etc/ssl/certs/ca-certificates.crt
264           ca_directory = /etc/ssl/certs
265           crl_file = /etc/ssl/crl
266           log_facilities = {"http", "soap"}
267

SEE ALSO

269       shigofumi(1)
270

AUTHOR

272       Petr Písař
273           He's written Shigofumi and libisds.
274
275
276
277Shigofumi                         08/18/2015                    SHIGOFUMIRC(5)
Impressum