Merge branch 'smartcard'

1 files changed, 33 insertions, 8 deletions

diff --git a/README.md b/README.md
index 3e354fb..c54d551 100644
--- a/README.md
+++ b/README.md
@@ -4,18 +4,43 @@ Python script to replace [MargTools](https://businessconnect.margis.si/output/#o
 
 ## Usage
 
-Create the configuration file `~/.margfools` with the paths to your TLS private key and certificate in PEM format:
+Run `margfools -h` for a synopsis of command‐line arguments. Allowed arguments are
 
-    [https://gcsign.example.com/BCSign/]
-    user-key = <path/to/key.pem>
-    user-cert = <path/to/cert.pem>
+    margfools [-h] [-e {file,pkcs11}] [-k KEYFILE] [-c CERTFILE] [-i <KEY ID>] URL
+
+To use a signing key and certificate stored in PEM files, install `openssl` and run
+
+    margfools -e file -k KEYFILE -c CERTFILE bc-digsign://sign?…
 
-Section name is the percent-decoded value of `baseURL` in
+To sign using a PIV-II smartcard such as the Yubikey, install `pkcs11-tool` from [OpenSC](https://github.com/OpenSC/OpenSC) and run
 
-    bc-digsign://sign?accessToken=…&baseUrl=https%3a%2f%2fgcsign.example.com%2fBCSign%2f&…'
+    margfools -e pkcs11 -i <KEY ID> bc-digsign://sign?…
 
-You can set `margfools` as the default program for `bc-digsign` URLs by copying the `margfools.desktop` file to `~/.local/share/applications/` and running
+The script will prompt for the PIN to unlock the smartcard. To find the key ID, run
+
+    pkcs11-tool -O
+
+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
 
     xdg-mime default margfools.desktop x-scheme-handler/bc-digsign
 
-or by setting the default application in your browser.
+For this to work, the script must be configured as described below.
+
+## Configuration
+
+Settings can be saved on a per‐site basis in `~/.margfools` using the [configparser](https://docs.python.org/3/library/configparser.html) format.
+
+    [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>
+
+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
+
+    bc-digsign://sign?…&baseUrl=https%3a%2f%2fgcsign.example.com%2fBCSign%2f&…