1SHIGOFUMIRC(5) Manual for Shigofumi SHIGOFUMIRC(5)
2
6 shigofumirc - Configuration file for Shigofumi
7
9 Configuration for shigofumi is loaded from .shigofumirc in user's home
10 directory by default.
11 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 If an option accepts list of values, the syntax is traditional mathe‐
20 matical set notation: { value1 , value2 }.
21
23 Following options are recognized. Not all of them must present. Missing
24 options fall to default value back.
25 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 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 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 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 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 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 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 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 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 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 otp_code
102 One-time code for OTP authentication.
103 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 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 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 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 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 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 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 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 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 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 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 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 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 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 confirm_send
194 Boolean switch deciding whether to require confirmation before
195 sending composed message. Default value is true.
196 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 You can change the state to read state by read command manually
204 latter.
205 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 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 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 open_command
221 List of string values defining external utility to execute when
222 opening a document.
223 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 Default value is {"xdg-open", "%f"}.
232 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 This does not apply to log file. Its new content is appended
239 always.
240
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 Current cryptographic library can be determined from shigofumi -V out‐
251 put.
252
254 ~/.shigofumirc
255 Default location of the configuration file.
256
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
269 shigofumi(1)
270
272 Petr Písař
273 He's written Shigofumi and libisds.
274Shigofumi 08/18/2015 SHIGOFUMIRC(5)