Merge pull request #128 from readium/develop

Refactored database and server models, + shiny frontend (AngularJS app)

.gitignore

@@ -3,3 +3,23 @@ readium-lcp-server
 lcpencrypt/lcpencrypt
 files/
 *.sqlite*
+config.yaml
+lcpserver/manage/config.js
+.vscode/launch.json
+debug
+*.exe
+*.yaml
+**/manage/config.js
+frontend/manage/node_modules/*
+frontend/manage/dist/*
+frontend/manage/js/*
+frontend/manage/js/components/*
+*.map
+*.htpasswd
+lcpserver/test.sqllite
+.DS_Store
+.vscode
+lcpencrypt/.DS_Store
+lcpserver/.DS_Store
+npm-debug.log
+manage/config.js

README.md

@@ -1,53 +1,188 @@
 Readium LCP Server
-========
-
-This server allows you to both encrypt EPUBs as well as deliver licenses in accordance with the Readium LCP specification.
+==================
 
 Requirements
 ============
 
 No binaries are currently pre-built, so you need to get a working Golang installation. Please refer to the official documentation for
 installation procedures at https://golang.org/.
 
-In order to keep the content keys for each encrypted EPUB, the server requires a SQL Database. The server currently includes drivers
-for SQLite (the default option, and should be fine for small to medium installations) as well as MySQL and Postgres.
+In order to keep the content keys for each encrypted EPUB, the server requires an SQL Database. The server currently includes drivers
+for SQLite (the default option, which should be fine for small to medium installations) as well as MySQL and Postgres.
 
-If you wish to use the external licenses, where a client gets a simple json file that contains instructions on how to fetch the encrypted EPUBS,
+If you wish to use the external licenses, where a client gets a simple json file that contains instructions on how to fetch the encrypted EPUB file,
 a publicly accessible folder must be made available for the server to store the file.
 
-You must obtain a X.509 certificate through the Readium Foundation in order for your licenses to be accepted by the Reading Systems.
+You must obtain a X.509 certificate through EDRLab in order for your licenses to be accepted by Readium LCP compliant Reading Systems.
 
-Install
-======
+Executables
+===========
+The server software is composed of three independant parts:
 
-Assuming a working Go installation,
+## [lcpencrypt]  
 
-go get github.com/readium/readium-lcp-server
+A command line utility for EPUB content encryption. This utility can be included in any processing pipeline. 
+
+* takes one unprotected EPUB 3 file as input and generates an encrypted file as output.
+* notifies the License server of the generation of an encrypted file.
+
+## [lcpserver]
+
+A License server, which implements Readium Licensed Content Protection 1.0.
 
-Usage
-=====
+Private functionalities (authentication needed):
+* Store the data resulting from an external encryption
+* Generate a license
+* Generate a protected publication
+* Update the rights associated with a license
+* Get a set of licenses
+* Get a license
 
-*Please note that the LCP Server currently does not include any authentication. Make sure it is only available to your internal services or add an authenticating
-proxy in front of it*
 
-The server is controlled by a set of environment variables. Here are their descriptions and possible values:
+## [lsdserver]
 
-- CERT - Points to the certificate file (a .crt)
-- PRIVATE_KEY - Points to the private key (a .pem)
-- PORT - Where lcpserve will listen, by default 8989
-- HOST - The public hostname, defaults to `hostname`
-- READONLY - Readonly mode for demo purposes, no new file can be packaged
-- DB - the connection string to the database, by default sqlite3://file:lcpserve.sqlite?cache=shared&mode=rwc
+A License Status server, which implements Readium License Status Document 1.0.
 
-You can also use a YAML config file named config.yaml, which follows the structure presented in config.yaml.sample
+Public functionalities (accessible from the web):
+* Return a license status document
+* Process a device registration
+* Process a lending return
+* Process a lending renewal
 
+Private functionalities (authentication needed):
+* Create a license status document
+* Filter licenses
+* List all registered devices for a given licence
+* Revoke/cancel a license
 
-Once those are set, you can run the server by calling the following:
-$GOPATH/bin/readium-lcp-server
 
+Install
+=======
+
+Assuming a working Go installation, the following will install the three executables that constitute a complete Readium LCP Server.
+
+If you want to use the master branch:
+```sh
+// from the go workspace
+cd $GOPATH
+// get the different packages and their dependencies, then installs the packages
+go get github.com/readium/readium-lcp-server
+```
+
+If you want to use a feature/F branch:
+```sh
+// from the go workspace
+cd $GOPATH
+// create the project repository
+mkdir -p src/github.com/readium/readium-lcp-server
+// clone the repo, selecting the development branch
+git clone -b feature/F https://github.com/readium/readium-lcp-server.git src/github.com/readium/readium-lcp-server
+// move to the project repository
+cd src/github.com/readium/readium-lcp-server
+// get the different packages and their dependencies, then installs the packages (dot / triple dot pattern)
+go get ./...
+```
+
+You may prefer to install only some of the three executables. 
+In such a case, the "go get" command should be called once for each package, e.g. for the lcpserver from the master branch:
+```sh
+// from the go workspace
+cd $GOPATH
+// get the different packages and their dependencies, then installs the packages
+go get github.com/readium/readium-lcp-server/lcpserver
+```
+
+Server Configuration
+====================
+
+The server is controlled by a yaml configuration file (e.g. "config.yaml").  
+The License Server and License Status Server will search their configuration file in the bin directory by default;
+but the path to this file can be changed using the environment variable READIUM_LICENSE_CONFIG.
+The License Server and License Status Server may share the same configuration file (if they are both executed on the same server)
+or they can have their own configucation file. In the first case, the htpasswd file and database may also be shared.
+In the latter case, the License Server will have a "lcp" section and a "lsd_notify_auth" section;
+the License Status Server will have a "lsd" section and a "lcp_update_auth" section.
+
+"certificate":	parameters related to the signature of the licenses	
+- "cert": the provider certificate file (.pem or .crt). It will be inserted in the licenses and used by clients for checking the signature.
+- "private_key": the private key (.pem). It will be used for signing  licenses.
+
+"lcp" (License Server) & "lsd" (License Status Server) sections have an identical structure:
+- "host": the public server hostname, `hostname` by default
+- "port": the listening port, `8989` by default
+- "public_base_url": the public base URL, combination of the host and port values on http by default 
+- "database": the URI formatted connection string to the database, `sqlite3://file:lcpserve.sqlite?cache=shared&mode=rwc` by default
+- "auth_file": mandatory; the authentication file (an .htpasswd). Passwords must be encrypted using MD5.
+	The source example for creating password is http://www.htaccesstools.com/htpasswd-generator/. 
+	The format of the file is:
+```sh
+	User1:$apr1$OMWGq53X$Qf17b.ezwEM947Vrr/oTh0
+	User2:$apr1$lldfYQA5$8fVeTVyKsiPeqcBWrjBKMT
+```
+
+"lsd_notify_auth": authentication parameters used by the License Server for notifying the License Status Server 
+of a license generation. The notification endpoint is configured in the "lsd" section.
+- "username": mandatory, authentication username
+- "password": mandatory, authentication password
+
+"lcp_update_auth": authentication parameters used by the License Status Server for updating a license via the License Server.
+The notification endpoint is configured in the "lcp" section.
+- "username": mandatory, authentication username
+- "password": mandatory, authentication password
+
+"storage": parameters related to the storage of the protected publications.
+- "filesystem": parameters related to a file system storage
+  - "directory": absolute path to the directory in which the protected publications are stored.
+
+"license": parameters related to static information to be included in all licenses generated by the License Server
+- "links": links that will be included in all licenses. "hint" and "publication" links are required in a Readium LCP license.
+  If no such link exists in the partial license passed from the frontend when a new license his requested, 
+  these link values will be inserted in the partial license.  
+  If no value is present in the configuration file and no value is inserted in the partial license, 
+  the License server will reply with a 500 Server Error at license creation.
+  - "hint": required; location where a Reading System can redirect a User looking for additional information about the User Passphrase. 
+  - "publication": optional, templated URL; 
+    location where the Publication associated with the License Document can be downloaded.
+    The publication identifier is inserted via the variable {publication_id}.
+  - "status": optional, templated URL; location of the Status Document associated with a License Document.
+    The license identifier is inserted via the variable {license_id}.
+
+NOTE: here is a license section snippet:
+```json
+license:
+    links:
+        hint: "http://www.edrlab.org/readiumlcp/static/hint.html"
+        publication: "http://www.edrlab.org/readiumlcp/files/{publication_id}"
+        status: "http://www.edrlab.org/readiumlcp/licenses/{license_id}/status"
+```
+
+"license_status": parameters related to the interactions implemented by the License Status server, if any
+- renting_days: number of days be the license ends.
+- renew: boolean; if `true`, rental renewal is possible. 
+- renew_days: number of days added to the license if renewal is active.
+- return: boolean; if `true`,  early return is possible.  
+- register: boolean; if `true`,  registering a device is possible.
+
+"localization": parameters related to the localization of the messages sent by the server
+- languages: array of supported localization languages
+- folder: point to localization file (a .json)
+- default_language: default language for localization
+
+NOTE: list files for localization (ex: 'en-US.json, de-DE.json') must match the array of supported localization languages
+
+"logging": parameters for logging results of API methods
+- log_directory: point to log file (a .log).
+- compliance_tests_mode_on: boolean; if `true`, logging is turned on.
+
+
+The following CBC / GCM configurable property is DISABLED, see https://github.com/readium/readium-lcp-server/issues/109
+"aes256_cbc_or_gcm": either "GCM" or "CBC" (which is the default value). This is used only for encrypting publication resources, not the content key, not the user key check, not the LCP license fields.
+
+
+Documentation
+============
+Detailed documentation can be found in the [Wiki pages](../../wiki) of the project.
 
-The server includes a basic web interface that can be reached at http://HOST:PORT/manage/. You can drag and drop EPUB files to encrypt them,
-as well as emit licenses for the currently encrypted EPUBs.
 
 Contributing
 ============