Adobe Primetime Adobe Primetime DRM On Premises Individualization Server Guide

Adobe Primetime Adobe Primetime DRM On Premises Individualization Server Guide

Contents Adobe Primetime DRM On Premises Individualization Server Guide...3 Software Requirements...3 Code Delivery / Package Contents...3 Obtain Individualization Server Certificates...3 Server Configuration...4 Server Properties...4 Monitoring...12 Update the License Server WAR File...12 Generate the On Premises DRM Metadata...13 Client Integration...13 Sample Client Requests...13 FAQ...14 Copyright...15 Last updated 9/26/2016 Adobe Primetime DRM On Premises Individualization Server Guide

3 Adobe Primetime DRM On Premises Individualization Server Guide - 5.3.1 Software Requirements Tomcat 6 JDK 1.8 Code Delivery / Package Contents The Adobe Primetime DRM On Premises Individualization Server package contains the following: flashaccess.war - The Individualization Server flashaccess-kgs.war - The optional Key Generation Server /shared - Contains: adobe-flashaccess-certs.jar AdobeInitial.properties - Sample properties file thirdparty/ - Includes Crypto-J support as native libraries: libjsafe.so (Linux) jsafe.dll (Windows) adobe-flashaccess-i15n-setup.jar - A utility for encrypting server credential passwords ROOT - contains a crossdomain.xml file ECI cache files - Pre-downloaded addindivcert.py - A script for updating a License Server s root of trust to support On Premises individualizations CreateMetadata.jar - A utility for creating On Premises DRM Metadata client_sample/ - A folder with a client code snippet Release Notes - For any last minute additions to the documentation Obtain Individualization Server Certificates To use the On Premises Individualization Server, you must first obtain two digital credentials (certificates): Individualization Transport Credential - issued by Adobe Individualization CA Credential - issued by Symantec (VeriSign) To obtain these certificates: Please submit a request via Zendesk ticket to: https://adobeprimetime.zendesk.com Please note that these credentials are in addition to the credentials required for operating a Primetime DRM License Server.

4 Server Configuration Server Properties You must configure server properties to reflect your environment. You can do this using any of the following: flashaccess-i15n.properties - Samples included in each of the.war files AdobeInitial.properties - Sample located in the /shared folder on the DVD You can use this file to override the properties set in the WAR file as follows: 1. Set the overriding property values in AdobeInitial.properties 2. Place AdobeInitial.properties on the classpath. Note: Adobe recommends that you make use of the AdobeInitial.properties file, since this allows you to update your application WAR files without risking the loss of any previous property configuration setup you may have done in the flashaccess-i15n.properties file. The Java System property mechanism. Apply properties to server environments You can apply individual properties to these specific server environments: Development Staging Production With this capability, you can use the same WAR file for all server environments. To apply properties to specific environments, do the following: Append two underscore characters (' ') plus one of the following environment codes to the property name: DEV STAGE PROD For example, to set the log level to INFO for your production and staging servers, and to DEBUG for your development server: log.level=info log.level DEV=DEBUG The server employs this search order for properties: 1. propertyname_environment in AdobeInitial.properties 2. propertyname_environment in flashaccess-15n.properties 3. propertyname_environment in Java System properties 4. propertyname in AdobeInitial.properties 5. propertyname in flashaccess-15n.properties 6. propertyname in Java System properties

5 Note: You must specify the server s environment name as a Java System property when starting the server. For example, when starting Tomcat with catalina.bat, set the CATALINA_OPTS environment variable as follows: -DENVIRONMENT_NAME=[ DEV STAGE PROD ] Encrypt Passwords The properties files include several password values that you should not enter as plain text. Encrypt these values using the following command: java -jar adobe-flashaccess-i15n-setup.jar password This command will output an encrypted password, which you then use in the properties files. Note: This is not the utility used for encrypting License Server passwords. Server Properties Reference Table 1: Individualization Server Configuration Transport Credential Individualization CA Credential Individualization Encryption Credential Content Cache Description The transport credential is used to decrypt requests received from the client and sign the responses sent back. Be sure to configure the AdobeInitial.properties file appropriately with both the path to the transport credential file, as well as the encrypted PKCS12 password. The Individualization server uses the Individualization CA credential to sign the machine certificates that it issues. Be sure to configure the AdobeInitial.properties file appropriately with both the path to the I15N CA credential file, as well as the encrypted PKCS12 password. The Individualization server uses the Encryption credential to encrypt sensitive files that need to be transmitted to the Individualization servers. For example, this cert supports license migration and is also used to encrypt the DRM private keys for the Individualization servers. These settings control the location from which the Individualization server downloads content and where the content is cached on disk. The Individualization Example cert.i15n.transport.file = [PKCS12 file containing the Individualization Transport cert and key] cert.i15n.transport.password = [Encrypted password for PKCS12 file] cert.i15n.ica.file = [PKCS12 file containing the Individualization CA cert and key] cert.i15n.ica.password = [Encrypted password for PKCS12 file] cert.i15n.decryption.file=i15n_transport.pfx cert.i15n.decryption.password=password contentserver.localdirectory = [Directory in which to store local content (normally tomcat/temp)]

6 Configuration Individualization CA CRL Description server will check the content server for new content once at startup, then at the frequency/time specified by these properties. For the On Premises Individualization Server, we have included an initial set of content cache data. Be sure to copy the CONTENTS of the cache folder (not the cache folder itself) to the configured AdobeInitial.properties contentserver.localdirectory location. Example contentserver.server = [Web server to contact for ECI info (unsupported in this release)] contentserver.timeout = [Connection timeout, in seconds] contentserver.pollfrequency = [How frequently to poll the server, in days (minimum is 1 day)] contentserver.polltime = [Time of day to poll the server, in minutes since midnight] Please be sure to read the section CRL and ECI Files about keeping the cache up to date. This Certificate Revocation List (CRL) cert.machine.crldp = [CRL distribution point is included within each distribution point] machine certificate issued by the For example: Individualization server. During machine cert.machine.crldp DEV= certificate validation on the license server, http://onprem-individualization.com/ the CRL will be downloaded from the CRL/onprem-individualization-ca.crl distribution point listed in the certificate The License Server should automatically (or read from the cache if already downloaded) and checked to be sure the certificate has not been revoked. It is recommended to perform this server configuration change after going through the process of creating and deploying the Individualization CA CRL. Restart the Individualization server after any configuration change. To set the URL for the CRL distribution point, you will need to set the AdobeInitial.properties cert.machine.crldp field. download this CRL, once a license request is handled. Note: This distribution point is not checked by Primetime DRM for validity. You must verify that this URL is valid. Errors resulting from an invalid URL will not appear until validation errors appear from the license server. Logging Configure the AdobeInitial.properties for logging as necessary. adobe.weblogs.loc = [Directory where log files will be created] log.level = [The lowest level of log messages which may appear in the logs [DEBUG INFO] ] log.filename = [Prefix for log files. Date/time and ".log" extension will be added to the filename] log.rollinterval = [Specifies how frequently the logs are rolled.]

7 Configuration Other Description Example log.rollsize = [Roll the logs when they reach this size (Logs will roll when either the RollInterval or RollSize is reached, whichever comes first)] log.reportlogging.enabled =[ [true false ] Specifies whether a separate file should be generated which contains data used by Adobe to generate Individualization reports.] log.reportlogging.filename = [Prefix for report log files. Date/time and.log extension will be added to the filename. The log.level property does not apply to this log file, but log.rollinterval and log.rollsize do.] deviceinfo.key = [Encrypted Base64 encoded key used to HMAC device info before including it in the machine token. The key can be different for the Dev/Staging/Production environments, but must be the same for all servers in a particular environment. ] keys.kgs.server = [Location of Key Gen Server (a single host/port, representing a pool of key servers) ] keys.minqueuesize = [Fetch another batch of keys from the KGS when there are this many keys left in the queue] status.timeout = [Status page will ping the KGS to determine if it can reach the server. It will time out if a response isn t received back in the specified amount of time.] Key Generation Server Configuration Key Generation Description Example kgs.threads = [Number of threads to use to generate keys (should equal the number of processors available on the machine)] kgs.batchsize = [Number of keys to generate per batch] kgs.keydirectory = [Directory in which to store key batch files] kgs.maxqueuesize = [Maximum number of key batch files to generate]

8 Configuration Logging Description Example adobe.weblogs.loc = [Directory where log files will be created] log.filename = [Prefix for log files. Date/time and.log extension will be added to the filename] log.level = [The lowest level of log messages which may appear in the logs] log.rollinterval = [Specifies how frequently the logs are rolled.] log.rollsize = [Roll the logs when they reach this size (Logs will roll when either the RollInterval or RollSize is reached, whichever comes first)] Create Individualization CA CRL This Certificate Revocation List (CRL) distribution point is included within each machine certificate issued by the individualization server. During machine certificate validation on the license server, this CRL will be downloaded from the distribution point listed in the certificate (or read from the cache if already downloaded) and checked to be sure the certificate has not been revoked. Note: To set the URL for the CRL distribution point, you will need to set the AdobeInitial.properties cert.machine.crldp field. This distribution point is not checked by Primetime DRM for validity. You must verify that this URL is valid. Errors resulting from an invalid URL will not become apparent until validation errors appear from the license server. Outlined below are simplified, sample instructions for using OpenSSL to create CRLs that your license server can consume. Adobe recommends that you perform these steps in a secure fashion and environment, once a Production Individualization CA credential has been obtained. 1. Change the working directory to the create_crl directory included in this distribution. 2. Copy your Individualization CA pfx to the same create_crl directory. The subsequent steps assume that the Individualization CA pfx is named i15n.pfx. Adjust as appropriate for your setup. 3. Extract the Individualization CA pfx file s private key. openssl pkcs12 -ini15n.pfx -nocerts -out i15n_priv.pem 4. Convert the private key to pksc8 format. openssl pkcs8 -topk8 -in i15n_priv.pem -inform pem -out i15n_pk8.pem -outform pem -nocrypt 5. Generate the CRL. openssl ca -keyform pem -keyfile./i15n_pk8.pem -cert i15n.pem -gencrl -out onprem-individualization -ca.crl This example creates a CRL with a default 1 month validity period. Use the -crldays and -crlhours options to override the default values. Generating a CRL uses the index and crlnumber file pointed to in your openssl.conf. By default, the democa location in the working directory is used. Sample index and crlnumber files are included in the supplied democa directory.

9 6. Deploy the CRL file generated in the previous step to a suitable location that is reachable by the license server (for example: individualization server ROOT). 7. Restart the license server, once the CRL is in place. Configure the Path and Classpath The flashaccess.war contains jsafewithnative.jar, which is the Crypto-J library. The latter requires an additional native library to perform crypto operations. 1. Add the native jsafe library to your path. Linux / libjsafe.so - The directory containing libjsafe.so must be on the Path (native Crypto-J libraries are also available for other platforms). For example, set libjsafe.so on LD_LIBRARY_PATH. Windows / jsafe.dll - The counterpart on Windows to libjsafe.so is the appropriate jsafe.dll. These libraries are available to you in the thirdparty library folder. 2. Put one of the adobe-flashaccess-certs jar files on the classpath. This JAR file is not included in the WAR file; you must add it explicitly to the classpath. Development servers - Should only use adobe-flashaccess-certs-prerelease.jar. Production servers - Should only use adobe-flashaccess- certs.jar. The disstribution includes a shared folder that includes both the jar file as well as a pre-configured AdobeInitial.properties file. Adobe recommends that you add these items to the common.loader via the catalina.properties file. For example: common.loader=<any Pre-Existing Values>,${catalina.home}/shared/classes,${catalina.home}/shared/lib/*.jar Configure Tomcat On the Individualization server, modify Tomcat s conf/server.xml file to include additional information in the access log. You can use this information for reporting purposes. 1. Locate the configuration for the AccessLogValve in server.xml and modify the pattern as shown here: <Valve classname="org.apache.catalina.valves.accesslogvalve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %{x-forwarded-for}i %l %u %t "%r" %s %b %{request-id}r" resolvehosts="false"/> %{x-forwarded-for}i will record the value of the x-forwarded-for header. If you use an Apache reverse proxy to forward requests to the Tomcat server, this header will contain the original client's IP address, whereas %h records the Apache server s IP address. %{request-id}r will record the request identifier, which corresponds to the request ID contained in the Individualization application log. 2. Edit conf/server.xml and set the unpackwars property to false. For both the Individualization and Key Generation servers, it is a good idea to edit conf/server.xml and set the unpackwars property to false. Otherwise, when you update the WARs, you may have to clean out the unpacked WAR folders as well. Note: Future DRM clients will require you to enable and configure the CORS (Cross-Origin Resource Sharing) filter that is available for Tomcat. Currently, no DRM clients have this requirement.

10 Deploy the WAR files 1. Copy the WAR file to Tomcat s webapps directory. Individualization Server: flashaccess.war Key Generation Server: flashaccess-kgs.war 2. Copy the ROOT folder from the package provided by Adobe to the webapps directory. The Individualization server also needs to host the crossdomain.xml file. (The ROOT folder contains the crossdomain.xml file; ROOT must be in all caps.) The Key Generation server does not require this file. Firewall Rules To secure access to the Individualization server, only certain application paths need to be exposed. The Individualization server must accept requests from clients to these paths: /flashaccess/i15n/* /flashaccess/status /crossdomain.xml Service paths, such as /flashaccess/admin/* (i.e., status and admin pages) must only be accessible from within the firewall. No parts of the Key Generation Server should be accessed from outside the firewall. About CRL Files In order to properly function, Individualization and License servers need to have several Certificate Revocation List (CRL) files cached to disk on the running application server (e.g., Tomcat). New CRL files have to be downloaded and cached on disk on a regularly scheduled basis. If the validity period of CRL files on disk are allowed to lapse, the Individualization Server will refuse to individualize clients, and the License Server will refuse to issue licenses. The CRLs cached to disk must have file names that match the corresponding URLs. Special characters such as colons ':' and '/' slashes are converted to underscores '_' in the file names. The following is a list of externally hosted CRLs that are used by both the Individualization and License Servers: Intermediate CRL: URL: http://crl2.adobe.com/adobe/flashaccessintermediateca.crl File: http crl2.adobe.com_adobe_flashaccessintermediateca.crl Validity: Good for approximately 12 months from creation Root CRL: URL: http://crl2.adobe.com/adobe/flashaccessrootca.crl File: http crl2.adobe.com_adobe_flashaccessrootca.crl Validity: Good for approximately 5 years from creation Latest CRL: URL: http://crl3.adobe.com/adobesystemsincorporatedflashaccessruntime/latestcrl.crl File: http crl3.adobe.com_adobesystemsincorporatedflashaccessruntime_latestcrl.crl Validity: Good for approximately 3 months from creation The following are externally hosted CRLs that are used only by the License Servers:

11 URL: http://crl2.adobe.com/adobe/flashaccessindividualizationca.crl File: http crl2.adobe.com_adobe_flashaccessindividualizationca.crl Validity: Good for approximately 3 months from creation URL: http://individualization-crl.primetime.adobe.com/flashaccessindividualizationca.crl File: http individualization-crl.primetime.adobe.com_flashaccessindividualizationca.crl Validity: Good for approximately 3 months from creation URL: http://individualization-crl.s3-website-us-east-1.amazonaws.com/flashaccessindividualizationca.crl File: http individualization-crl.s3-website-us-east-1.amazonaws.com_flashaccessindividualizationca.crl Validity: Good for approximately 3 months from creation In addition to the aforementioned CRLs, you must create and maintain an additional CRL. This is the Individualization CA CRL, as specified in the Create Individualization CA CRL section of this document. CRLs are scheduled to be updated 45 days before they are to expire. This should allow you adequate time to acquire and install newly generated CRLs from the Internet. You must take care to update CRL files before they are expired. About ECI Files In addition to the CRLs, you also need to periodically update Embedded Common Interface (ECI) files. Whenever Adobe adds support for a new Primetime DRM client platform (for example: ios, Android, Windows FlashPlayer, etc.), a new ECI record is created. In order to support the individualization of this client, a corresponding ECI record needs to be present on the Individualization Server. Since the release of new Primetime DRM clients is not very frequent, Adobe will be releasing updated ECI data on an as needed basis. Periodically, Adobe will collect ECI files and host them to the location below for distribution: http://cdmdownload.adobe.com/indiv/onprem/eci/latest.txt The Latest.txt file will contain the URL to the most recent CRL distribution file. Adobe will create the ECI zip file in the manner described below: Folder Structure: ECI\* The contents of the folder will be zipped up recursively: zip -R ECI ECI.zip An OpenSSL SHA- 256 digest will be calculated of the zip file: openssl dgst -sha256 -hex ECI.zip The zip file will be renamed to contain the archive date as well as the SHA-256 digest: Rename ECI.zip to <DATE_SHA-256>.zip For example: 20150310_aea45bf06241f04fba2b310ff9a8066c6aba73c8d22387b60509481e9cefc43e.zip

12 You should periodically check the location above for updated ECI files. Perform the following process for installation after download: 1. Note the SHA-256 digest and recalculate it using OpenSSL or an equivalent tool. 2. Compare it to the one specified in the file name. 3. Rename the file to ECI.zip. 4. Unzip the ECI directory. 5. Replace the old ECI directory with the new one. 6. Restart the Individualization server. Monitoring The Individualization server and Key Generation server each have a status page, which you can use to determine the health of the servers. Individualization status page: http://[server:port]/flashaccess/status Reports Alive if the app server is running and the app can make a GET request to the Key Generation server The page reports either Alive or nothing. No info about the application is revealed, so this page could be used for monitoring from outside the firewall. Key Generation status page: http://[server:port]/flashaccess-kgs/status Reports "Alive" if the app server is running All Key Generation URLs must only be accessible internally Individualization Statistics page: http://[server:port]/flashaccess/admin/appstats Includes statistics about the Individualization server, such as number of requests served and the number of keys available in the cache This page must only be accessible internally Key Generation Statistics page: http://[server:port]/flashaccess-kgs/appstats Includes statistics about the Key Generation server, such as the number of requests served and the number of key files available on disk All Key Generation URLs must only be accessible internally Update the License Server WAR File In order to support clients that have individualized via an On Premises Individualization server, you must update the License Server s certificate root of trust to include the newly acquired Individualization CA credential. A Python script (addindivcert.py) is included in the update_license_server folder. Do the following to update the License Server: 1. Make a copy of the WAR files to be updated (examples: flashaccess.war, faxsks.war). 2. Make sure the WAR files are unlocked and have their permissions set so they can be modified. 3. Run the addindivcert.py Python script to update the License Server WAR files. The inputs for the script are as follows: cert: PKCS12 file containing the Individualization CA certificate

13 war: WAR file to be updated The output file is an updated WAR file../addindivcert.py cert NEW_IndivCA.cer -war flashaccess.war The WAR files will be modified in place. If necessary, you can edit the Python script to suit your particular needs. After you perform the updates, you can deploy the WAR files normally. Generate the On Premises DRM Metadata A CreateMetadata.jar utility is included in the create_metadata folder. The point of this utility is to create an On Premises DRM Metadata that will initiate the client into performing the individualization process against the specified On Premises Individualization Server. Update the Primetime DRM Reference Implementation - Command Line Tools with the following files: CreateMetadata.jar commons-cli-1.2.jar createmetadata.properties The two JAR files can reside in the Command Line Tools/libs folder. The createmetadata.properties file can reside next to the flashaccesstools.properties file. Included is an examplecreate.sh script that demonstrates a sample creation of metadata. Be sure to configure the License Server URL and Individualization Server URL in both the script and properties files before attempting to generate metadata. The inputs for the utility are as follows: createmetadata.properties - Properties file containing a default Policy, Certificate locations and passwords, etc. indivcert - PKCS12 file containing Individualization Transport certificate indivurl - URL of the On Premises Individualization Server The output file is an On Premises DRM Metadata file that will be consumed by the DRM client. For example: java -jar libs/createmetadata.jar -c createmetadata.properties -indivcert i15n_transport.cer -indivurl http://[yourindivserver:port] onpremdrm.metadata. Client Integration In order to direct the client into individualizing against the On Premises Individualization server (as opposed to the Adobe Hosted Global Individualization Server), the client should utilize the previously created On Premises DRM Metadata. Having an un-individualized client perform a license acquisition or initialize DRM, using the special metadata, will result in the client connecting to the custom Individualization Server URL. A sample code snippet is included in the client_sample folder. Sample Client Requests You can collect a library of sample client requests using tools such as Charles Proxy or Wireshark. You should capture client requests after the Individualization server has been set up, using the Individualization Transport credential. You can then send

14 these client requests (via curl or another tool) to the Individualization Server s end point to verify that the server is up and running properly. For example: curl http://<<yourindivserver:port>>/flashaccess/i15n/v5 -data binary @sample_client_request.bin > sample_client_response.ber You may also want to send these requests again after any server configuration changes or ECI / CRL updates. You should also update the Individualization Statistics page appropriately with successful individualization transactions. FAQ How often do ECI changes occur? Anytime a new Adobe DRM client is released, an ECI device record is added. How large are ECI files? They are typically less than 1 Kilobyte per device record. What happens if the server is missing an ECI device record? That particular class of clients will not be able to individualize against the On Premises Individualization Server and errors will be logged to the log files. What happens if a server s CRLs are expired? The server will stop functioning correctly and errors will be logged to the log files.

Copyright 15 Copyright 2017 Adobe Systems Incorporated. All rights reserved. Adobe Primetime DRM On Premises Individualization Guide Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.