Home
Welcome to the readium-lcp-server wiki!
In this Wiki, you'll find guidelines and the specification of the REST API of the LCP License Server and LCP Status Server.
Please open a Github issue of you don't find sufficient information in this documentation.
This open-source server software is split into three parts:
- LCP Encryption tool: a command line utility for content encryption.
- LCP License Server: the server module which generates LCP licenses.
- LCP Status Server: the server module which generates LCP license status documents, handles device activation, lending returns and renewals, license revocation.
The LCP License Server must be closely interfaced with the Provider Server. Please read carefully the notes below and the instructions relative to the integration of the LCP Server into a distribution platform.
The Provider Server (i.e. the system Bookseller, Public Library or Distributor implements for handling its catalog of ebooks, users and purchases or loans) and LCP Status Server must be accessible from the Web. The LCP License Server must be hidden from the Web and only accessible from the Provider Server and Encryption Tool with proper authentication.
In order to facilitate testing, we also provide a Test Frontend server module and its Angular.js client, which mimics a Provider Server. This Test Frontend should not be used in production: as its name indicates, it is only used for testing the LCP solution more easily.
The Provider Server (Bookseller's website, Library's circulation manager ...) must be able to:
- request from the License Server the generation of a license, using the publication identifier as a key, when a user acquires a publication. API details here.
- request from the License Server an existing license, using the license identifier as a key, when a client device requests an up-to-date license. API details here.
The Provider Server, or a separate tool developed by the provider, should also be able to use the Status Server API in order to:
- Check which licenses are used by a large number of devices. API details here.
- If the number of devices hooked to a license exceeds a certain business limit (which is up to the provider to decide), revoke this license. API details here.
- Handle license cancellations, in case a user declares he cannot use a license because he has no LCP compliant device in hand. API details here.
Note: The Provider Server may also request from the License Server the generation of a protected publication (with a license embedded in the content) but this is not a recommended practice as it invalidates any effort to cache the encrypted content on the Web.
-
Install the servers: the installation steps and server configuration are listed in the home page of this project.
-
Integrate these servers into your infrastructure, a.k.a the Provider Server.
-
Start the LCP License Server and LCP Status Server.
-
Batch encrypt your ebooks. You can use the encryption tool provided as open-source as a command line tool or embed it in any workflow you like.
Note: that publications encrypted using the encryption tool are not visible from the Test Frontend (which has an embedded encryption service).
The following diagrams illustrate the interactions between the different modules of a Readium LCP server side solution.
Step 1: publications are encrypted. Each encrypted publication is notified to the License Server. The resulting encrypted publication is stored by the License Server into a repository accessible from the Web; let's call it the Encrypted Content Repository. It can be a Web folder managed by the Provider, or it can be an S3 bucket. Be careful about the content identifier you pass to the encryption tool (see the command line parameters), as it will be the key you'll use later to generate licenses for such content.
Step 2: the user acquires a publication on the Provider Server via a client device. The Provider Server requests the generation of an LCP license from the License Server, with user information as parameters. The Status Server is notified of this new license. Be careful to store the license identifier inside the Provider Server, and associate this information with the user who owns this license. The license identifier will be the key the Provider Server will use later to get up-to-date licenses by their id. The Provider Server returns the newly generated license to the client device.
Step 3: the client device requests the encrypted content referenced by a license; it is directly fetched from the Encrypted Content Repository.
Step 4: the client device requests a status document from the Status Server (GET). A license registration (POST), loan return or renewal (PUT) or license revocation (PATCH) use the same protocol.
Step 5: the client device requests an existing license via the Provider Server, used as a proxy to the License Server. The Provider Server fetches from its database some user information associated with the license and calls the License Server to obtain an up-to-date license. This license is then returned to the client device.
Step 6: the client device requests an early loan return or loan extension. The Status Server directly receives the request and forwards to the License Server a request to modify the end date of the license.
Step 7: the Provider Server requests the cancellation or revocation of a license. The Status Server directly receives the request and forwards to the License Server a request to modify the end date of the license.
This more detailed process diagram can help understanding the different interactions.
To get more details about the interactions shown in this process diagram, you'll find useful to check the associated sequence diagrams.
Just follow the links on the right column menu.
Note also the the specification of Readium LCP and Readium License Status Document are found on the Readium.org website.