Add READMEs to subpackages

README.md

@@ -2,10 +2,10 @@
 
 `irmago` is an IRMA implementation in Go. It contains multiple libraries and applications:
 
-* The Go package `irma` contains generic IRMA functionality used by all other components below, such as parsing [credential and issuer definitions and public keys](https://github.com/privacybydesign/irma-demo-schememanager), parsing [IRMA metadata attributes](https://credentials.github.io/docs/irma.html#the-metadata-attribute), and structs representing messages of the [IRMA protocol](https://credentials.github.io/protocols/irma-protocol/).
+* The commandline tool [`irma`](tree/master/irma), which contains an [IRMA server](tree/master/server/irmad); subcommands for manipulating [IRMA schemes](https://credentials.github.io/docs/irma.html#scheme-managers), generating IRMA issuer public/private keypairs, performing test IRMA sessions on the command line; and more.
+* The root package `irma` contains generic IRMA functionality used by all other components below, such as parsing [credential and issuer definitions and public keys](https://github.com/privacybydesign/irma-demo-schememanager), parsing [IRMA metadata attributes](https://credentials.github.io/docs/irma.html#the-metadata-attribute), and structs representing messages of the [IRMA protocol](https://credentials.github.io/protocols/irma-protocol/).
 * The Go package [`irmaclient`](tree/master/irmaclient) is a library that serves as the client in the IRMA protocol; it can receive and disclose IRMA attributes and store and read them from storage. It also implements the [keyshare protocol](https://github.com/privacybydesign/irma_keyshare_server) and handles registering to keyshare servers. The [IRMA mobile app](https://github.com/privacybydesign/irma_mobile) uses `irmaclient`.
 * The [`server`](tree/master/server) package contains the corresponding IRMA server as a Go library and as an executable.
-* The tool [`irma`](tree/master/irma) for generating IRMA issuer public/private keypairs, and for verifying and signing [IRMA schemes](https://credentials.github.io/docs/irma.html#scheme-managers).
 
 ## Dependencies
 

irma/README.md

+# irma
+
+`irma` is an IRMA swiss knife in the form of a command line executable, supporting the following subcommands:
+
+* `irma server`: an IRMA server daemon allowing you to perform IRMA sessions with [IRMA apps](https://github.com/privacybydesign/irma_mobile). [README](../server/irmad).
+* `irma session`: Perform an IRMA disclosure, issuance or signature session, using the [builtin](../server/irmaserver) IRMA server or a [remote](../server/irmad) server
+* `irma scheme`: Manage IRMA schemes, supporting downloading, updating, verifying, and signing schemes, and IRMA key generation
+* `irma request`: compose an IRMA session request
+* `irma meta`: Parse an IRMA metadata attribute and print its contents
+
+Pass `-h` or `--help` to any of these subcommands to see usage details and examples.
+
+## Install
+
+If necessary, clone `irmago` and install dependencies with [dep](https://github.com/golang/dep):
+```
+mkdir -p $GOPATH/github.com/privacybydesign && cd $GOPATH/github.com/privacybydesign
+git clone https://github.com/privacybydesign/irmago && cd irmago
+dep ensure
+```
+
+Build and install `irma`:
+```
+cd irma
+go install
+```
+
+## Examples
+
+Perform IRMA sessions on the command line (start the session, print the QR, and print session result when the session is done):
+```
+$ irma session --issue irma-demo.MijnOverheid.ageLower=yes,yes,yes,no
+$ irma session --disclose irma-demo.MijnOverheid.ageLower.over18
+$ irma session --request '{"type":"disclosing","content":[{"label":"BSN","attributes":["irma-demo.MijnOverheid.ageLower.over18"]}]}'
+$ irma session --server http://localhost:8088 --authmethod token --key mytoken --disclose irma-demo.MijnOverheid.ageLower.over18
+```
+
+Download an IRMA scheme and then verify its authenticity:
+```
+$ irma scheme download . https://privacybydesign.foundation/schememanager/irma-demo
+$ irma scheme verify irma-demo
+Verifying scheme irma-demo
+
+Verification was successful.
+```
+
+Generate an IRMA issuer private-public keypair (of 2048 bits and supporting a maximum of 10 attributes):
+```
+$ cd irma-demo/MijnIssuer
+$ irma scheme issuer keygen # takes a while
+$ ls PublicKeys PrivateKeys
+PrivateKeys:
+0.xml
+
+PublicKeys:
+0.xml
+```
+
+Sign an IRMA scheme after having made modifications:
+```
+$ cd irma-demo
+# Make modifications (e.g. add a public key to an issuer with irma scheme issuer keygen)
+$ irma scheme sign
+$ irma scheme verify
+Verifying scheme irma-demo
+
+Verification was successful.
+```

server/README.md

+# Package `server`
+
+This package contains the following components of the IRMA server:
+
+ * [`irmaserver`](irmaserver): Go library providing an HTTP server that handles IRMA session with the IRMA app, and functions for starting and managing IRMA sessions.
+ * [`requestorserver`](requestorserver): Go library providing an HTTP server that combines the HTTP endpoints from `irmaserver` with endpoints to start and manage IRMA sessions.
+ * [`irmad`](irmad): server executable (daemon) wrapping `requestorserver`, exposed as the `irma server` subcommand.
+
+### Specifying an email address
+In the configuration of each of the three components above, an email addres can be specified. If specified, the email address is uploaded to the [Privacy by Design Foundation](https://privacybydesign.foundation/) and subscribed to receive updates about changes in the IRMA software or ecosystem. If you use any of the above servers, especially in production environments, we encourage you to provide your email address.
+
+If you provide an email address, you will be notified of changes such as major updates of the IRMA server, and breaking changes in any part of the IRMA infrastructure that would require you to update your IRMA server or otherwise take action in order to stay compatible with the rest of the IRMA ecosystem.
+
+ * It will be very low volume (on average perhaps one email per several months). 
+ * If you have provided your email address in the past and wish to be unsubscribed, please email [the Foundation](https://privacybydesign.foundation/contact-en/).
+ * See also the Foundation's [privacy policy](https://privacybydesign.foundation/privacy-policy-en/).

server/irmad/README.md

+# irma server
+
+`irma server` is an IRMA server executable (daemon) allowing you to perform IRMA sessions with
+[IRMA apps](https://github.com/privacybydesign/irma_mobile).
+It exposes the following:
+ * HTTP endpoints used by the IRMA app during IRMA sessions
+ * a JSON API for [requestors](https://credentials.github.io/docs/irma.html#participants),
+   allowing them to request the server to verify or issue attributes.
+
+
+
+## Installing
+If necessary, clone `irmago` and install dependencies with [dep](https://github.com/golang/dep):
+```
+mkdir -p $GOPATH/github.com/privacybydesign && cd $GOPATH/github.com/privacybydesign
+git clone https://github.com/privacybydesign/irmago && cd irmago
+dep ensure
+```
+
+Build and install:
+```
+cd irma
+go install
+```
+
+Run `irma server -h` to see configuration options or just `irma server` to run the server with the default configuration.
+In order to verify your configuration, run `irma server check -v`.
+
+
+## Starting a session
+Assuming the server runs in the default configuration (see below; in particular [requestor authentication](#requestor-authentication) is disabled (`no_auth` is `true`) and the `irma-demo` scheme is installed), issue `irma-demo.MijnOverheid.ageLower` attributes using the [`session`](../../irma) subcommand of the `irma` tool:
+```
+irma session --server http://localhost:8088 --issue irma-demo.MijnOverheid.ageLower=yes,yes,yes,no
+```
+Verify the `irma-demo.MijnOverheid.ageLower.over18` attribute:
+```
+$ irma session --server http://localhost:8088 --disclose irma-demo.MijnOverheid.ageLower.over18
+```
+These print QRs in your terminal that you can scan with your IRMA app to perform the session.
+
+
+
+## Configuring
+Run `irma server -h` to see all configuration options.
+Each option may be passed as:
+ 1. a command line flags (e.g. `--listen-addr`)
+ 2. a environmental variable (e.g. `IRMASERVER_LISTEN_ADDR`)
+ 3. an item in a configuration file (e.g. `"listen_addr"`) (which may be in JSON, TOML or YAML)
+ 
+ with the following rules:
+ * Flags supersede environmental variables which supersede configuration file entries.
+ * Dashes are used in flags, but underscores are used in environmental variables and configuration file entries.
+ * Environmental variables are uppercased and prefixed with `IRMASERVER_`.
+ * The `requestors` option is special: when passed as a flag or environmental variable, it must be passed in JSON.
+
+In order to see the configuration that the server uses after having gathered input from these sources, specify `-v` or `-vv` or use the `verbose` option. Use `irma server check -v` (with the same flags, env vars and config files as `irma server`) to check your configuration for correctness before running the server.
+
+#### Configuration files
+A configuration file can be provided using the `config` option (for example: `irma server --config ./irmaserver.json`). When not specified, the server looks for a configuration file called `irmaserver.json` or `irmaserver.toml` or `irmaserver.yaml` in (1) the current path; (2) `/etc/irmaserver/`; (3) `$HOME/irmaserver`, in that order. A configuration file is not required; if none is found at any of these locations the server takes its configuration from just command line flags and environmental variables.
+
+#### Default configuration
+In the default configuration (run `irma server check -v` to see it) the server is immediately usable. In particular, it
+* uses the default [IRMA schemes](https://credentials.github.io/docs/irma.html#scheme-managers) ([pbdf](https://github.com/credentials/pbdf-schememanager) and [irma-demo](https://github.com/credentials/irma-demo-schememanager)), downloading them if necessary
+* allows anyone to use the server [without authentication](#requestor-authentication) (the `no_auth` setting is `true`).
+
+If the server is reachable from the internet, you should consider enabling authentication of session requests.
+
+#### Keys and certificate
+For each configuration option that refers to some kind of key or certificate (for example `jwt_privkey`), there is a corresponding option with the `_file` suffix (for example `jwt_privkey_file`). Keys can be specified either by setting former to a (PEM) string, or setting the the latter to a file containing the (PEM) string.
+
+#### Production mode
+When running the server in production, enable the `production` option. This enables stricter defaults on the configuration options for safety and prints warnings on possibly unsafe configurations.
+
+#### HTTP server endpoints
+The HTTP endpoints that this server offers is split into two parts:
+* `/session`: used by the requestor to start sessions, check session status, or get session results.
+* `/irma`: used by the IRMA app during IRMA sessions.
+
+In the default mode, the server starts one HTTP server that offers both, configured with `listen_addr` and `port`. If however the `client_port` and `client_listen_addr` options are provided, then the server starts two separate HTTP servers:
+* `/session` attaches to the address and port provided with `port` and `listen_addr`.
+* `/irma` attaches to the address and port provided with `client_port` and `client_listen_addr`.
+
+The `/irma` endpoints must always be reachable for the IRMA app. Using this double server mode you can restrict access to the `/session` endpoints by e.g. setting `listen_addr` to `127.0.0.1` or to an interface only reachable from an internal network. Restricting access to the `/session` endpoints in this way may make requestor authentication unnecessary.
+
+#### Requestor authentication
+The server runs in one of two modes: it either accepts all session requests from anyone that can reach the server, or it accepts only authenticated session requests from authorized requestors. This can be toggled with the `no_auth` boolean option. The default is `true` (requests are not authenticated) when `production` is not enabled, and `false` otherwise.
+
+The server supports three authentication methods:
+ * POSTing the JSON session request with an API token in the `Authorization` HTTP header
+ * POSTing the session request in a [JWT](https://jwt.io/) asymmetrically signed with RSA (RS256)
+ * POSTing the session request in a [JWT](https://jwt.io/) symmetrically signed with HS256
+
+Authorized requestors can be configured with the `requestor` option. For example, the following configuration file snippet configures a requestor called `myapp` using the API token authentication method.
+```json
+{
+    "requestors": {
+        "myapp": {
+            "auth_method": "token",
+            "key": "eGE2PSomOT84amVVdTU"
+        }
+    }
+} 
+```
+
+#### Permissions
+For each of the three IRMA session types (attribute verification; attribute issuance; and attribute-based signature sessions), permission to use specific attributes/credentials can be granted in the configuration.
+
+#### Signed JWT session results
+
+#### TLS
+
+#### Email
+
+Users of the server are encouraged to provide an email address with the `email` option, subscribing for notifications about changes in the IRMA software or ecosystem. [More information](../#specifying-an-email-address). In `production` mode, it is required to either provide an email address or to explicitly out with the `no_email` option. 
+
+## See also
+
+This executable wraps the Go library [`requestorserver`](../requestorserver) which wraps the Go library [`irmaserver`](../irmaserver).
+
+The [client](../../irmaclient) corresponding to this server is implemented by the [IRMA mobile app](https://github.com/privacybydesign/irma_mobile).
+
+This server replaces the Java [irma_api_server](https://github.com/privacybydesign/irma_api_server). 

server/irmaserver/README.md

+# irmaserver   [![GoDoc](https://godoc.org/github.com/privacybydesign/irmago/server/irmaserver?status.svg)](https://godoc.org/github.com/privacybydesign/irmago/server/irmaserver)
+
+`irmaserver` is a Go library providing a HTTP server that handles IRMA session with the IRMA app, and functions for starting and managing IRMA sessions.
+
+```go
+err := irmaserver.Initialize(&server.Configuration{
+    URL: "https://example.com:1234", // Replace with address that IRMA apps can reach
+}) // Check err
+_ = http.ListenAndServe(":1234", irmaserver.HandlerFunc()) // Start the server
+
+// In another goroutine, request a demo over18 attribute
+request := `{
+    "type": "disclosing",
+    "content": [{ "label": "Over 18", "attributes": [ "irma-demo.MijnOverheid.ageLower.over18" ]}]
+}`
+qr, _, err := irmaserver.StartSession(request, func (r *server.SessionResult) {
+    fmt.Println("Session done, result: ", server.ToJson(r))
+})
+// Check err
+
+// Send qr to frontend and render as QR
+```
+
+## Installing
+
+Clone `irmago` and install dependencies with [dep](https://github.com/golang/dep):
+```
+mkdir -p $GOPATH/github.com/privacybydesign && cd $GOPATH/github.com/privacybydesign
+git clone https://github.com/privacybydesign/irmago && cd irmago
+dep ensure
+```
+
+## Configuring
+The server is configured by passing a `server.Configuration` instance to `irmaserver.New()`. For the options and their meaning, see [Godoc](https://godoc.org/github.com/privacybydesign/irmago/server/#Configuration).
+
+## Email
+
+Users are encouraged to provide an email address with the `Email` option in the `server.Configuration` struct, subscribing for notifications about changes in the IRMA software or ecosystem. [More information](../#specifying-an-email-address).
+
+## See also
+
+The  Go library [`requestorserver`](../requestorserver) wraps the functions that this library exposes
+for starting and managing IRMA sessions into HTTP endpoints. The [`irmad`](../irmad) binary wraps
+`requestorserver` into an executable
+ 
+
+The [client](../../irmaclient) corresponding to this server is implemented by the [IRMA mobile app](https://github.com/privacybydesign/irma_mobile).