-
Notifications
You must be signed in to change notification settings - Fork 58
Encryption tool
The goal of this cross-platform command line executable is to be usable on any kind of processing pipeline.
Note that several processes can be active in parallel if necessary.
Name: lcpencrypt
The encryption tool currently supports:
- EPUB 2
- EPUB 3 (including with embedded multimedia content)
- Readium Packages, i.e. Readium Web Publications (specification) archived using the Readium Packaging Format (specification). This includes Audiobooks (specification), PDF files embedded in Readium Packages, Digital visual Narratives (specification) and (X)HTML based Publications (specification).
- W3C Audiobooks (specification) packaged as LPF files ((specification))
The encryption tool stores the encrypted file in its target storage location and notifies the license server of the url of this new encrypted publication. The user must provide both a storage location and its corresponding public URL.
- -input: file path of the source file. The utility can load files from a file system or an http(s) server (it will use a GET command).
- -storage: target location for the encrypted publication, without filename. It is either an S3 bucket or the path to a file system in which files are accessible from http(s). See below details on its format.
- -url: base url associated with the storage. This must be a public URL.
- -contentid: optional, unique identifier of the encrypted publication. If omitted, a uuid is generated.
- -filename:optional, file name of the encrypted publication; if omitted, contentid is used as a file name.
- -temp: optional, working folder for temporary files.
- -lcpsv: optional, host name of the License Server to be notified; syntax http://username:[email protected].
- -v2: optional, boolean, indicates a License Server v2.
- -notify: optional, URL, notification endpoint of a CMS; syntax http://username:[email protected].
- -verbose: optional, boolean, the information sent to the LCP Server and CMS will be displayed.
If encrypted publications are stored in Amazon S3 buckets, the requested syntax is "s3:" + the AWS region (e.g. "eu-west-3") + ":" + the S3 bucket name (e.g. "lcp-storage"). Example: "s3:eu-west-3:lcp-storage".
If encrypted publications are stored in a file system (e.g. a network drive), the syntax depends on the OS on which the Encryption Tool is installed. On MacOS is could be something like "/Volumes/my.org/www/lcp-storage".
The url value must correspond to the chosen storage value. For instance, let's imagine that storage corresponds to a folder in a network drive, e.g. "/Volumes/my.org/www/lcp-storage" on a Mac, and that files stored in this network drive are accessible from the Web at "http://my.org/lcp-storage/*". url must therefore be set to "http://my.org/lcp-storage".
If you are using Amazon S3 buckets to store encrypted publications, and you are using something like "s3:eu-west-3:lcp-storage" as a storage value, the url value will be like "https://lcp-storage.s3.eu-west-3.amazonaws.com" (please read S3 documentation for more details).
The Encryption Tool will send to the License Server the value of the url parameter joined to the file name of the encrypted publication. This URL will then be inserted into each license generated for this publication, and it will be used by reading systems to fetch the encrypted publication.
The encryption tool will:
- Load the source file, exits on error if the file is not found or is not parsable.
- If the content identifier is not set, generate a unique publication identifier.
- Generate a content encryption key.
- Encrypt the source content, exits on error if the process aborts.
- Upload the protected file to the target location, exits on error if the process aborts.
- Optionally, send a notification to the license server.
The license server will:
- Store the unique identifier and the url of the encrypted file in its database.
- Use this information to populate the licenses it generates.
- Not be able to return an encrypted publication or generate a licensed publication, as it does not manage the stored publication.
The encryption tool stores the encrypted file in a temporary storage location and notifies the LCP license server of this new encrypted publication. The license server moves the encrypted file to its final storage location, which is static and set by configuration.
- -input: file path of the source file. The utility can load files from a file system or an http(s) server (uses GET).
- -output: temporary location of the encrypted publication. This is a directory path, without filename. This path must be directly accessible from the license server (i.e. it must be on a shared network drive). If not set, the encrypted publication will be temporarily created into the current directory.
- -contentid: optional, unique identifier of the encrypted publication. if omitted a uuid is generated.
- -temp: optional, working folder for temporary files.
- -lcpsv: optional, http endpoint of the license server (lcpserver), used for notifying that new content is available.
- -login: required if -lcpsv is used; login used to connect to the license server.
- -password: required if -lcpsv is used; password used to connect to the license server.
The encryption tool will:
- Load the source file, exits on error if the file is not found or is not parsable.
- If the content identifier is not set, generate a unique publication identifier.
- Generate a content encryption key.
- Encrypt the source content, exits on error if the process aborts.
- Upload the protected file to the output directory, exits on error if the process aborts.
- Optionally, send a notification to the license server.
The license server will:
- Move the encrypted file to its target storage location (as per its configuration).
- Store the unique identifier and the name of the encrypted file in its database.
- Use this information and the static configuration of the target url of the publication to populate the licenses it generates.
- Be able to return an encrypted publication and generate a licensed publication.
The encryption tool is using PUT on /content/ with a json structure as payload:
The json struct contains:
- content-id: content identifier.
- content-encryption-key: content encryption key.
- storage-mode: indication of the way the encrypted content is stored: 0 = not stored yet; 1 = stored on S3; 2 = stored in a file system.
- protected-content-location: absolute URL (cf recommended use) or temporary file path (cf legacy use) of the encrypted publication.
- protected-content-disposition: original file name.
- protected-content-type: media type of the encrypted content.
- protected-content-length: size of the encrypted content.
- protected-content-sha256: hash of the encrypted content.
See the corresponding License Server API method
lcpencrypt -input "~/epubfiles/epub31.epub" -storage "/Users/X/lcp/files/storage" -url "https://edrlab.org/pub/storage/" -lcpsv "http://192.168.0.1:8989" -login "login" -password "password"
lcpencrypt -input "~/epubfiles/epub31.epub" -storage "s3:eu-west-3:lcp-storage" -url "https://lcp-storage.s3.eu-west-3.amazonaws.com"
lcpencrypt -input "~/epubfiles/epub31.epub" -contentid epub31 -output "~/readiumlcp/encfiles/"
The communication between the utility and the LCP server is currently only protected by the use of https.