diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 47 |
1 files changed, 25 insertions, 22 deletions
@@ -4,40 +4,43 @@ Python script to replace [MargTools](https://businessconnect.margis.si/output/#o ## Usage -Create the configuration file `~/.margfools`. The contents are described in the sections below. +Run `margfools -h` for a synopsis of command‐line arguments. Allowed arguments are -### Certificates in files + margfools [-h] [-e {file,pkcs11}] [-k KEYFILE] [-c CERTFILE] [-i <KEY ID>] URL -If you are using certificate files, add the paths to your TLS private key and certificate in PEM format: +To use a signing key and certificate stored in PEM files, install `openssl` and run - [https://gcsign.example.com/BCSign/] - key = <path/to/key.pem> - cert = <path/to/cert.pem> - -### Certificates on smartcards + margfools -e file -k KEYFILE -c CERTFILE bc-digsign://sign?… -If you have your certificate on a PIV-II smart card (e.g. Yubikey), first determine the slot on your card which contains the certificate you wish to use: +To sign using a PIV-II smartcard such as the Yubikey, install `pkcs11-tool` from [OpenSC](https://github.com/OpenSC/OpenSC) and run - pkcs11-tool -O + margfools -e pkcs11 -i <KEY ID> bc-digsign://sign?… -Look for "ID:" in the output. +The script will prompt for the PIN to unlock the smartcard. To find the key ID, run -Assuming the ID of your certificate was 07, specify the engine and certificate slot in your config file: + pkcs11-tool -O - [https://gcsign.example.com/BCSign/] - engine = pkcs11 - key = 07 +To use `margfools` from the web app, set it as the default program for `x-scheme-handler/bc-digsign` URLs, or copy the `margfools.desktop` file to `~/.local/share/applications/` and run -You will be asked for your pin during signing. + xdg-mime default margfools.desktop x-scheme-handler/bc-digsign -### Add URL schema +For this to work, the script must be configured as described below. -Section name is the percent-decoded value of `baseURL` in +## Configuration - bc-digsign://sign?accessToken=…&baseUrl=https%3a%2f%2fgcsign.example.com%2fBCSign%2f&…' +Settings can be saved on a per‐site basis in `~/.margfools` using the [configparser](https://docs.python.org/3/library/configparser.html) format. -You can set `margfools` as the default program for `bc-digsign` URLs by copying the `margfools.desktop` file to `~/.local/share/applications/` and running + [DEFAULT] + engine = pkcs11 + + [https://gcsign.example.org/BCSign/] + id = 02 + + [https://gcsign.example.com/BCSign/] + engine = file + keyfile = <path/to/key.pem> + certfile = <path/to/cert.pem> - xdg-mime default margfools.desktop x-scheme-handler/bc-digsign +All settings can be specified for all sites in the default section, or for individual sites. The section name should match the percent-decoded value of `baseURL` in -or by setting the default application in your browser. + bc-digsign://sign?…&baseUrl=https%3a%2f%2fgcsign.example.com%2fBCSign%2f&… |