shigofumirc - Man Page
Configuration file for Shigofumi
Description
Configuration for shigofumi is loaded from .shigofumirc in user's home directory by default.
The file is plain text file with simple syntax: Setting is stored in option = value format. If value is a type of string, it must be delimited by quotation marks. Boolean values can be expressed as "true" or non-zero integer (1) for affirmation, or "false" or zero integer (0) for negation. Simple numeric values are unquoted. Commentary starts with hash sign (#) and continues to the end of the line.
If an option accepts list of values, the syntax is traditional mathematical set notation: { value1 , value2 }.
Options
Following options are recognized. Not all of them must present. Missing options fall to default value back.
Account Options
- base_url
Base URL for ISDS server. Be careful when setting this value: This can reveal your password to bad guys running fake server (if you do not verify server identity preciously) and different host names are used with different log-in mechanism. In addition, there are two system instances administrated by Czech government: official one and testing one.
E.g. use "https://ws1.czebox.cz/" for testing instance of ISDS or "https://ws1.mojedatovaschranka.cz/" for official instance with valid and legal data when logging in without TLS client certificate. Otherwise, with client certificate in use, replace the ws1 domain with ws1c domain. Or, with OTP authentication, replace with www domain. I.e. "https://ws1c.czebox.cz/" for testing instance with certificate authentication or "https://www.mojedatovaschranka.cz/" for official instance with OTP authentication.
Do not forget on leading protocol schema and trailing slash. Default value is official instance locator suitable for selected authentication method provided by libisds library.
- certificate_format
Format of client certificate used to authenticate user into ISDS. Three distinct values are recognized: PEM for Base64 serialization to file, DER for binary serialization to file, and ENG to specify the certificate is stored in cryptographic engine. Default value is empty string.
- certificate_path
File where client certificate used to authenticate user into ISDS is, if certificate_format option is set to PEM or DER. If certificate_format is ENG, this is an identifier of the certificate inside the cryptograhic engine. NSS library uses this option as certificate nickname. Default value is empty string signaling not to authenticate user by a certificate.
- key_engine
Cryptographic engine holding client private key and/or certificate used to authenticate user into ISDS. The value identifies a device (e.g. a smart card) known to underlying cryptographic library where key and/or certificate is stored. Interpretation depends on the cryptographic library. This option takes effect only if key_format or certificate_format is ENG. Default value is empty string.
- key_format
Format of client key used to authenticate user into ISDS. Three distinct values are recognized: PEM for Base64 serialization to file, DER for binary serialization to file, and ENG to specify the key is stored in cryptographic engine. Default value is empty string.
- key_path
File where client key used to authenticate user into ISDS is, if key_format option is set to PEM or DER. If key_format is ENG, this is an identifier of the key inside the cryptograhic engine. NSS library uses this option as certificate nickname. Default value is empty string. This can mean the key is stored along the certificate.
- key_password
Password protecting private key used for client authentication using asymetric cryptography. Default value is empty string. Underlying cryptographic library can raise its own password query or require to obtain the code in other way (e.g. typing PIN on smart card reader key pad).
- otp_method
One-time password authentication method. Default value is undefined string what means do not use OTP authentication. If this option is defined, OTP will be used for authentication. Two methods are recognised: HOTP for HMAC-based One-Time Password method and TOTP for Time-based One-Time Password method.
- otp_code
One-time code for OTP authentication.
If HMAC-based method is used, this code will be computed in a device or a piece of software which should be in exclusive possession of its user.
If Time-based method is used, the code will be generated by ISDS server and delivered to the user by a side channel. (The channel is an SMS currently. Because the delivery is specialy charged, the time code generation is protected by plain password too. User sends standard password without OTP code first, then server delivers code by the SMS message and finally user will retry log-in with both password and both OTP code.)
Default value is empty string and user will be asked interactively for the OTP code when needed. Because of dynamic nature of this code, setting the value in a configuration file is pointless. However you could rewrite this value for each shigofumi run in batch mode.
- password
Password assigned to given user-name. User must keep it in secret. This password is used while HTTP authentication and is passed to underlying network libraries. Make sure this configuration file or your swap partition (network library together with password can be swapped out during physical memory outage) will not get to bad guys. Encrypt them before. Default value is empty string.
- username
ISDS user log-in name. Identifies a user in ISDS. One person can have more identities. Default value is empty string.
TLS Options
- ca_directory
Path to directory with trusted authorities certificates stored in separate files (files must have special names usually). Default value is provided by underlying cryptographic library. Exact meaning of this option depends on interpretation by used cryptographic library.
- ca_file
Path to file with trusted authorities certificates (concatenated list of PEM-formatted certificates). Default value is provided by underlying cryptographic library. Exact meaning of this option depends on interpretation by used cryptographic library.
- crl_file
Path to file with certificate revocation lists (concatenated list of CRLs in PEM format usually). Default value is provided by underlying cryptographic library. Exact meaning of this option depends on interpretation by used cryptographic library.
- verify_server
Boolean switch deciding whether server identity should be verified. When using HTTPS connection to the server, the identity of server can be verified in TLS negotiation phase by validating server certificate against trusted certificate authority certificate and certificate revocation list. Default value is true. It's strongly recommended to keep it on.
Network Options
- timeout
Non-negative integer setting network time-out in milliseconds. Use 0 not to limit any network operation. Default value is 10,000 ms.
Log Options
- log_facilities
List of string values selecting libisds facility to log. Valid values are: none, http, soap, isds, file, sec, xml, all. Default set is {"none"}.
- log_file
String value selecting file to append ISDS log. The log catches libisds internal debugging protocol. It does not cover messages produces by shigofumi itself. This feature is designed to debug underlying libraries and protocols like ISDS, SOAP, or cURL's HTTP(S). If undefined, shigofumi logs to standard error output.
- log_level
Integer value setting log verbosity of libisds from interval <0;100>. 0 is no logging, 10 is critical messages, 20 errors, 30 warnings, 40 informative messages, 50 debug messages, 100 messages of all severities. Default log level is 20.
Other Options
- clean_temporary_files
Boolean switch deciding whether to remove temporary files at shigofumi exit. This applies to files created for opendoc command, as external utility can access the file after quiting shigofumi. Default value is true.
- confirm_send
Boolean switch deciding whether to require confirmation before sending composed message. Default value is true.
- mark_message_read
Boolean switch deciding whether right downloaded incoming messages should be marked as read automatically. If true, change message state to read on the server. Otherwise keep message state intact. Default value is false.
You can change the state to read state by read command manually latter.
Be ware ISDS web portal marks messages as read automatically. Note, there is no way to unmark a message to unread state back.
- normalize_mime_type
Boolean switch deciding whether MIME type of documents retrieved from a message should be normalized to standard values. Default value is true.
ISDS does not check document MIME type a client supplies. Unfortunately, official client sends invalid values (file name extension usually). This option allows Shigofumi to fix the type on-the-fly. Be ware the original value stored in ISDS or locally saved message keeps untouched.
- open_command
List of string values defining external utility to execute when opening a document.
First value is command, other values are command arguments in order. If command is not absolute file name, it's located according PATH environment variable. If value contains %f substring, it will be expanded to name of file to open. If value contains %t substring, it will be expanded to MIME type of document to open. Use %% sequence to escape per-cent character.
Default value is {"xdg-open", "%f"}.
- overwrite_files
Boolean switch deciding whether newly created files should overwrite existing ones. If true, existing files will be overwritten silently. Otherwise error wil be raised. Default value is true.
This does not apply to log file. Its new content is appended always.
Notice on Cryptographic Library
Shigofumi uses libisds that utilizes cURL library that can use three different cryptographic libraries at this time: OpenSSL, GnuTLS and NSS. Each library has different set of features and different configuration. Thus exact meaning of some Shigofumi configuration options can be slightly shifted (e.g. the name of client certificate and key). Some options cannot be understood at all (e.g. GnuTLS does not support directory of certificates).
Current cryptographic library can be determined from shigofumi -V output.
Files
- ~/.shigofumirc
Default location of the configuration file.
Example
base_url = "https://ws1.czebox.cz/"
# These credentials are invalid
username = 1s79vd
password = XY123456
verify_server = true
ca_file = /etc/ssl/certs/ca-certificates.crt
ca_directory = /etc/ssl/certs
crl_file = /etc/ssl/crl
log_facilities = {"http", "soap"}See Also
Author
Petr Písař
He's written Shigofumi and libisds.