Security Tools

This project contains the security tools required for developing BD-J Applications. Here is the list of tools we currently have available:

Introduction to Blu-ray Security

A Blu-ray disc with signed JAR files must contain an Application Root Certificate. This is often just called a "Root Certificate," and it is described in part 3-2 section 12.2.7. The application root certificate is stored on the optical disc as app.discroot.crt. A signed JAR file is verified against this root certificate. This ensures that the JAR file was signed by the same party that generated the app.discroot.crt file, or by a second party that was permitted access through a trust chain.

The first step, then, in making a signed Blu-ray disc is to generate a root keypair. This is stored in a secure keystore. A working root keypair can be created with the cookbook tools, as described in the next section. The root keypair consists of a public and a private key. The public key is stored in the file app.discroot.crt. Sometimes, you may hear people say that a JAR needs to be "signed with the root certificate," but this is really a shorthand for signing with the private key that corresponds to the public key contained in the root certificate. A root certificate can't sign anything, because it lacks the private key.

Another public/private keypair can be generated, with the root keypair as its parent. This process can continue recursively, to make a leaf certificate at any desired distance from the root. For Blu-ray, a depth of two keypairs is recommended, but three is also common. A maximum depth is set in the guidelines, but there's probably no reason to want to go beyond three or four anyway. A longer certificate chain takes more time during jar verification.

Making an intermediate keypair allows the entity that generated the root certificate to grant permission to sign xlets based on that root certificate, without giving out the private key associated with the root certificate. This can be useful for managing vendors, so you can tell who signed what. The leaf keypair (at the end of the chain) is used to sign the JAR file(s) of the xlet. A signed JAR file contains a certificate chain from the root certificate to the leaf certificate. Again, people will often say the JAR is "signed with the leaf certificate," but this is actually shorthand for signing the JAR with the private key of the keypair used to generate the leaf certificate. In Blu-ray, the leaf certificate must contain the organization ID associated with the JAR.

For VFS updates, the binding unit manifest file (BUMF) is signed with a different keypair. This keypair is the one used to generate the Binding Unit Root Certificate. This is specified in part 3-2 sections 12.2.8.1.2 and 12.2.8.1.3, and the certificate for this rootk keypair is stored in the file bu.discroot.root.

Finally, there is a third signing procedure, for the "online certificate." This is documented in part 3-2 section DD.2.1, and it involves signing the file app.discroot.crt. Having an online certificate and Signing an app.discroot.crt is not required. However, players have a configurable setting that allows the consumer to disallow network connections for discs that do not have an application root certificate that is signed with this mechanism. If you're making a disc for test or demo purposes, you can just change the player setting, but if you're making a commercial disc it makes sense to include the online signature.

Certificate Generation and Signing

There are two steps involved in signing a BD-J application.

Step 1: Generate the ceritficate{s} and key{s} for signing.
Step 2: Sign the application jar using a key{s} generate above.

Step 1: Certificate Generation:

BDCertGenerator tool can be used for generating certificates for the BD-J Platform. This tool generates three types of certificates for singing the application jar and the Binding Unit Manifest File (BUMF).

SYNOPSIS

BDCertGenerator -root|-app|-binding [options] [organization_id]

The mandatory argument for this tool is the type of the certificate. It could be either:

"-root" or "-app" or "-binding"

The organization_id (orgID) is required based on the type of certificate. For example, If the certificate type is "root", the orgID is not mandated.

If the type is "app", the orgID is typically required, unless it's a non-leaf certificate (i.e the certificate is not used for signing the application). In this case the tool does not mandate the orgID but warns the user about adding an orgID in the certificate.

And finally, if the certificate type is "binding" an orgID corresponding to the one used in the bumf.xml (or whatever BUMF file name is) must be used.

For other options type: 

	BDCertGenerator -help

Example:

Lets say, SEC_JAR, an environment variable represents the path for hdcookbook security jar. 
set SEC_JAR=<path of security jar>
The security.jar typically resides in the location below, please make sure that it does. 
<HDCOOKBOOK_HOME>\DiscCreationTools\security\build\security.jar

And BC_JAR, an environment variable represents path for Bouncy Castle Provider jar. We are using: bdprov-jdk15-137.jar, a bouncycastle distribution, it should be fine to use the later versions as well. A copy of which can be found in the "resource" directory of security tools. For more information see: Bouncy Castle Provider. 

set BC_JAR=<path of bouncy castle jar>

If signer is used, then one more jar is required in the classpath, this jar should contain the JDK JarSigner tool. For Windows platform this jar is found in the directory below: 

set TOOLS_JAR=<java.home>\lib\tools.jar
Set the CLASSPATH variable: 
set CLASSPATH=%CLASSPATH%;%SEC_JAR%;%BC_JAR%;%TOOLS_JAR%

Note: All the examples below assume that the CLASSPATH variable is set as above before invoking the security tools.

Here is the command line for generating a root certificate. 

java net.java.bd.tools.security.BDCertGenerator -root 7fff0001
Here is the command line for generating an application certificate. 

java net.java.bd.tools.security.BDCertGenerator -app 7fff0001
Place the generated certificate file: app.discroot.crt, in the 
BDMV\CERTIFICATE
and 
BDMV\CERTIFCATE\BACKUP
directories.

Step 2: Signing application jar

BDSigner tool can be used for signing the application jar. This tool can also be used for signing BUMF using the Binding Unit Root certificate. It can also generate "online.sig" file provided BDA generated private key is imported into the keystore.

SYNOPSIS

BDSigner [options] BUMF|app.discroot.crt|jarfiles

The mandatory argument for this tool is one or more jarfiles, or a BUMF file in case BUMF signing or an application certificate for online.sig generation.

For other options type: 

	BDSigner -help.

Example:

The signing key for the BDSigner to sign the jars is generated in Step 1.

Here is the command line for signing the jar. 

	java net.java.bd.tools.security.BDSigner 00000.jar
BDsigner is built on top of JDK's jarsigner which is bundled in tools.jar

Why can't we just use the standard "jarsigner" tool in Java SE?

Blu-Ray specification requires an extra header in the signature manifest file in signed jar files. The signature manifest file must have an attribute called "BDJ-Signature-Version" with the value of "1.0". Please refer to the section "12.1.4.2" of the "System Description Blu-Ray Disc Read-Only Format - Part 3 Audio Visual Basic Specifications" - DRAFT Version 2.02". The "jarsigner" tool in Java SE generates signature manifest file automatically. There is no way to specify extensions to the signature manifest file. So, it can not be used to sign jars for BD-J.

Signing BUMF

Here is an example of signing a BUMF using some of the options provided by the tools described above. Lets generate a binding unit root certificate with an alias:bucert and a key password: mypass, created in a new keystore: bindingstore, with a password: mystorepass

Here is the command line to generate a binding unit root certificate. 

	java net.java.bd.tools.security.BDCertGenerator -binding -keystore binding.store -storepass mystorepass -alias mybinder -keypass mypass -debug 00000001

The tool prints the following debug messages: 

	Certificate stored in file 
	Starting the verfication for certificate file:bu.discroot.crt 
	Checking the certiticate
	Done with the verification for the certificate file:bu.discroot.crt

Now, lets sign a BUMF file named: bumf.xml using the above keystore.

Here is the command line to sign BUMF 

	java net.java.bd.tools.security.BDSigner -keystore binding.store -storepass mystorepass -alias mybinder -keypass mypass -debug bumf.xml

The tool prints the following debug messages: 

	Signer of bumf.xml file is:mybinder
	Verifier of bumf.sf file is:mybinder
	BUSF Verification PASSED..
	The signed file is written into:bumf.sf

Note: If the default keystores, passwords and aliases are used, then the command line for signing a BUMF file is very simple as below: 
  	java net.java.bd.tools.security.BDCertGenerator -binding 00000001
  	java net.java.bd.tools.security.BDSigner bumf.xml

Online Signature generation

When a BD-J application tries to access network the player checks for online authorization for the disc. The online access is granted through online.sig, online.crt and online.crl files. The online.crt and online.crl are provided by BDA and online.sig file is generated using the credentials obtained from BDA.

The BDSigner generates online.sig file either by directly using BDA formatted key and certificate files or by reading them from the keystore. A utility called OnlineKeyTool enables importing keys from the BDA files into the Java Keystore. There by enabling storage of critical credentials in a single, protected place like keystore.

Here is the command line to generate a online.sig file using BDA provided files. The online.sig generation may nor may not require (see below) app.discroot.crt file. 
	java net.java.bd.tools.security.BDSigner -debug -onlinekey bda/keyfile.bin -onlinecrt bda/online.crt app.discroot.crt

This results in online.sig generation with following debug messages: 

        Content owner ID: 100
        Content owner Name: My Studio Ltd
        Imported online keys into keystore: keystore.store with an alias: "onlinecert"
        Signed online cert stored in file online.sig
        Online Cert signature verification PASSED
Note: The signature verification (for sanity check) is performed on the generated file only when -debug is used. This is in general true for other options as well.

If the app.discroot.crt file is not present then use -nodiscroot option as below: 

	java net.java.bd.tools.security.BDSigner -debug -nodiscroot -onlinekey bda/keyfile.bin -onlinecrt bda/online.crt

OnlineKeyTool:

This tool enables importing the BDA provided private key file and the public key from online.crt file into a Java Keystore. A new keystore can be used or the keys can be added to an existing keystore.

The public key is stored in a self signed certificate. This is not a certificate signed using BDA public key.

SYNOPSIS

OnlineKeytool [options] path-to-private-key-file path-to-online.crt

The mandatory argument for this tool is the private key file and the online.crt file.

For other options type: 

	OnlineKeytool -help.

Example:

Here is the command line to import a key pair from BDA provided files. 

	java net.java.bd.tools.security.OnlineKeytool -debug  bda/keyfile.bin  bda/online.crt

The above command results in a keystore that contains a key entry set to the public and private online keys obtained from BDA. When no options are provided the default keystore parameters are used.

Credential Generation and Signing:

BDCredentialSigner tool generates persistant file credentials and BUDA credentials for accessing the common data area across organizations (orgIDs). It can be used both by Grantor (one who "grants" access to its own data area by someone else). and a Grantee (one who accesses Grantor's data area). This tool is used in a workflow as below.
  • Grantor uses this tool to generate signed credentials, given a Permission Request File (PRF) received from a grantee for verification and signature.
  • The Grantee then uses this tool to update certificates and sign a jar file. The certificates required for verification of Grantor's signature inside the PRF are provided by the Grantor.

SYNOPSIS

BDCredentialSigner [options] PRF jarfile

With no options specified this tool does both tasks, i.e generates signed credentials (Grantor) and updates certificates and signs the jar file (Grantee). This is useful in testing environments.

For more options type: 

	BDCredentialSigner -help

In a real environment, both these processes are disjoint as described in a workflow above. The tool options for going with this workflow are described below.

Signing Credentials:

The command line option: -gencred generates the signed credentials.

Input: Permission request file, access to grantor's private key (by means of keystore) for signing and application disc root certificate of the grantee.

Output: A permission request file with signed credentials and the grantor's certificate chain stored in the file: "grantorchain.crt"

Example: The example below uses the same default values as that of the BDCertGenerator but the name of the keystore is: "grantor.store" (which is a default grantor keystore used by this tool). The default values save on typing. 

    BDCredentialSigner -gencred -gecert grantee.discroot.crt bluray.MyXlet.perm
The above command line results in a permission request file that is populated with credential elements containing the grantor's signature. The grantor certificate chain is store in the file: "grantorchain.crt"

Signing Jar:

The command line option: -updatecerts updates the certificates and signs the jar.

Input: Permission request file with signed credentials, grantor's certificate chain, both these are received from the grantor, grantee private key information for signing the jar (by means of keystore), jar file that uses the credentials and needs to be signed.

Output: The signed jar file updated with signed credentials and grantor certificates.

Example: 

    BDCredentialSigner -updatecert -gacerts grantorchain.crt bluray.MyXlet.perm 00000.jar

If none of the above options are specified, then the tool performs both the steps above In this case the specifed permission request file is extracted from the specified jarfile to be signed.

Input: Grantor and Grantee's keystore information for signing. Location of permission request file with in the given jarfile to be signed

Output: The signed jar file updated with credentials.

Example: This example shows use of custom values for key related information. 

    BDCredentialSigner -gastore GA.keystore -gastorepass GApass -gaalias GA -gakeypass GApass 
	               -store GE.keystore -storepass GEpass -alias GE -keypass GEpass
		        myxlet/bluray.MyXlet.perm 00000.jar

Permission Request File Example

Below is an example of a PRF created by the Grantee before sending it to the Grantor for signing. The PRF has all fields of persistent file credentials but the <signature> and the <certchainfileidi> elements.

Consider the following PRF, that is requesting a write access to a file: "01/4000/tmp.txt" located in the Application Data Area of another disk that belongs to an OrgID:7fff3456. The access validity is from now, till 10/12/2050. 


 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <n:permissionrequestfile xmlns:n="urn:BDA:bdmv;PRF" appid="0x4001" orgid="0x7fff1234">
   <file value="true"/>
   <applifecyclecontrol value="true"/>
   <servicesel value="true"/>
   <userpreferences read="true" write="false"/>
  <persistentfilecredential>
      <grantoridentifier id="0x7fff3456"/>
      <expirationdate date="10/12/2010"/>
      <filename read="true" write="true">01/4000/tmp.txt</filename>
  </persistentfilecredential>
 </n:permissionrequestfile>

The Grantor received the above PRF, and Grantee's application disc root certificate, signs the credentials and generates the PRF below:

The output PRF with -gencred option: 


      ......
     <persistentfilecredential>
       <grantoridentifier id="0x7fff3456"/>
       <expirationdate date="10/12/2010"/>
       <filename read="true" write="true">01/4000/tmp.txt</filename>
       <signature>KSrmmBCGY9RkOCug6HRWjBLC29VkCOKBoPAVbbxv+q7Ed4iVv6tzerrkXudjs1rez
 CYtrGysX0VK&#13;
 qKE/GlqQy2ICTWl8RVdWHFR/1KobWcsghIqtXeyR89pKrUWw8Z52o00pQsV351MrYAb7wZUzRozO&#13
 ;
 1VWAViCRoKkjHbxw/pI=</signature><certchainfileid>MGIwXTEPMA0GA1UEAwwGU3R1ZGlvMR8
 wHQYDVQQLDBZDb2Rlc2lnbmluZyBEZXBhcnRtZW50MRww&#13;
 GgYDVQQKDBNCREpDb21wYW55LjAwMDAwMDAxMQswCQYDVQQGDAJVUwIBAQ==</certchainfileid>
 </persistentfilecredential>
 </n:permissionrequestfile>
 ...
Note: The permission request file must always be placed in a directory as it would appear inside the jar bundle. For example: if the application sources that require PRF are placed in a package called: com.foo.bar, then the PRF file should be placed in a directory: com\foo\bar\bluray.MyApp.perm. The BDCredentialsSigner expects the whole path in the PRF argument for both credential and jar signing.

Tables of default values used:

Keystore:

Keystore Filename Keystore Password
keystore.store keystorepassword

Keys and Certificates defaults:

Certificate Type Alias Password
Root Certificate rootcert rootcertpassword
Application Certificate appcert appcertpassword
Binding Unit Root Certificate bucert rootcertpassword
BDA Online Certificate onlinecert onlinecertpassword

Output file names generated by the tools:

Filename Description Tool name (created by)
keystore.store (new or updated) Newly created/added keys and certificates BDCertGenerator and OnlineKeyTool
app.discroot.crt Disc root certificate for jar verfication BDCertGenerator
bu.discroot.crt Binding unit root certificate for BUMF verification BDCertGenerator
*.sf (example: bumf.sf) Signed BUMF for VFS updates BDSigner
online.sig Online signature file BDSigner

Credential Generation, Grantor's defaults:

Keystore Store Password Alias Key Password Certifcate chain filename
grantor.store keystorepassword appcert appcertpassword grantorchain.crt

Credential Generation, Grantee's defaults:

Keystore Store Password Root Alias Alias Key Password
keystore.store keystorepassword rootcert appcert appcertpassword