Java DTV Content and Application Packaging, Authentication, and Authorization

Application packaging is constructed to allow the compact distribution of content and applications, to enable authentication of the content or application and to authorize applications to access functions and APIs normally denied or restricted. Content authentication is used in order to authenticate single files delivered separately in the broadcast filesystem. Content that is treated as data to the application MUST NOT be delivered to the application if the authentication, if any, fails. For the Java DTV Runtime, the BroadcastFilesystem MUST authenticate each file if authentication meta data is available.

Applications fall into two categories, signed and unsigned. Signed applications are applications that can be authenticated to a set of trusted root certificates. The security of Java DTV applications consists of separate policies for signed and unsigned applications. Unsigned applications use a default policy that protects the device and the user from malicious actions. Signed applications can request a Per Application Policy that grants access to additional functions and APIs.

Application Packaging

Each application is contained within one or more JARs [JAR]. The main JAR contains the application files, resource files, and a manifest that describes the application and its requirements. For Java DTV applications additional JARs can be added to the classpath using the Class-Path attribute in the Manifest.

The device MUST support two complementary mechanisms for creating compact JARs. In the first, each file within the JAR is compressed individually and the compressed form is included in the JAR as specified in the [ Application Note on the .ZIP file format]. In addition, the entire JAR can be compressed using GZip. [GZip]. JARs compressed using GZip must have the suffix .jar.gz. Devices MUST recognize the GZipped JARs and support decompression as necessary.

For signed JAR files, the meta data used to authenticate the contents is stored in the root of the JAR in the /META-INF/ directory as specified in the JAR specification and described below in the Content Authentication section. The steps for signing are shown in this Example of Signing a Java DTV application.

Content Authentication

Authentication of any content or application is specified using meta data that is signed and can be authenticated on the device. The mechanism is used for hierarchical file storage and protects files, named with relative paths, within a subtree of the hierarchy by placing meta data at the top of the subtree. The mechanisms are used for signed JARs and adapted for the case where the hierarchical file storage is not provided by the zip format. For a file within a file hierarchy, the authentication meta data can be found by searching for the ./META-INF/ directory. The search MUST begin in the same directory as the file and search up the hierarchy until the meta data is found, but no further than the filesystem root. Of course, an implementation may be optimized to avoid the search and use other algorithms to evaluate the authentication information and to cache it until either the file changes or the meta data changes.

The JAR specification defines the syntax, encoding and storage of the meta data used for authentication. The information is stored in three files in a ./META-INF/ directory relative to the tree with contents to be authenticated. The metadata files are:

The files can be signed by one or more signers using different algorithms and keys. As per the JAR specification each signing produces two files that are located in the "META-INF" directory. The signature file, for example, XXX.SF, contains digest information about each entry in the manifest for each file within the JAR that is to be authenticated. The signature block file, for example, XXX.DSA or XXX.RSA, contains the PKCS#7 signature of the corresponding XXX.SF file. The two files MUST have the same name with the required suffix. The signature block file MUST contain the signing certificate and all necessary intermediate certificates up to but not including the root certificate. For each signer, each file of the JAR which is to be authenticated, an entry must be included in the XXX.SF file that contains the digest of the entry in the manifest file. Only one of the available signers is used to authenticate the manifest and the files.

The signature file MUST contain the main section and per entry sections and attributes as required by the JAR signing specification. The main section MUST contain SHA1-Digest-Manifest attribute and the value is the SHA1 hash of MANIFEST.MF. For each file to be authenticated, the manifest must include an entry that includes the SHA1-Digest attribute with the hash value. The digest value MUST use the SHA1 secure hash function as defined by [FIPS-18-1]. If the manifest can be authenticated, then the hash for each file with and entry can be used to authenticate the file.

The device MUST support the SHA1 algorithm for secure hashes. Both DSA and RSA encryption algorithms MUST be supported for certificates and JAR signing.

PKI certificates needed to verify signatures can be included with the content by including them in the "META-INF" directory. Certificates must be in PKCS#7 format and be named CERT-nn.CRT, where the first value of nn is 00. For additional certificate files the nn value is incremented by 1, allowing values from 00 through 99.

Application Authentication

Content files are authenticated using the mechanisms described in the JAR [JAR] specification. The MANIFEST.MF is authenticated by verifying its hash against the SHA1-Digest-Manifest attribute in the signature file. If the attribute is not present then authentication fails and authentication is not possible. The MANIFEST.MF is authenticated by a single hash of its entire contents. The signature file is authenticated using the signature block file. The signature block file contains intermediate certificates that are needed to verify the signature to root certificates found on the device.

Per Application Policy

The Per Application Policy is granted only if the application and the policy are signed and successfully authenticated. The Per Application Policy MUST be included in the JAR and be authenticated with the same certificates used to authenticate the application components in the JAR. The Per Application Policy file MUST be named /META-INF/POLICY.PAP. For Java DTV applications, the mapping of the application policy to the Java Security Policy and the details of application packaging are found in Java DTV Application Packaging.

Per Application Policy Schema

The application policy (aka permission request file) defines how an application requests access to functions that are granted only to trusted applications. The policy is formatted using an XML Schema defined in the Application Policy v1.1 DTD. Application policy files should use the following DOCTYPE.

 <!DOCTYPE ApplicationPolicy PUBLIC
           "-//Sun Microsystems, Inc.//DTD Java DTV Application Policy 1.1//EN"
           "http://java.sun.com/dtd/dtv-applicationpolicy-1.1.dtd">
                
A sample policy might look like this Template. The extended functions that may be permitted by the application policy are:

Element Description Unsigned Signed Default
file Access to the File System no access true
applifecycle Control of applications not launched by this application false false
networkdevice Access to the network device false false
dripfeed Access to dripfeed controls false true
scarceresource Access to scarce resources none none
tuning Access to the tuning functions false false
smartcardaccess Access to the SmartCard APIs false false
serviceselect Access to select a Service false true
userproperty Access to user properties Read: false
Write: false
Always allowed: User Language, Parental Rating,
DefaultFontSize, Country Code
Read: true
Write: false
network Access to named network hosts none none
ixcaccess Access to the inter-application communication functions false false
persistentfilecredential Credentials providing access to another application's files none none

File Access

The file element requests access to files within the device's file system subject to the access protections given to the files by the application that owns them. The structure of the file system includes areas dedicated to each organization and each application within the organization.

For the Java DTV Runtime, the application sets the platform access modes for files it owns using com.sun.dtv.io.FileProperties. Application access to files is via java.io.File and related classes.

Application LifeCycle Access

The applifecycle element requests access to control other applications within the current service:

Network Device Access

The networkdevice element requests access to the network device that provides the application access to services outside of the device. Access to the Network Device is restricted:

For the Java DTV runtime, the Network Device is accessed using com.sun.dtv.net.NetworkDevice.

Dripfeed Access

The dripfeed element requests access to use dripfeed controls. Access to dripfeeds is restricted:

For the Java DTV Runtime, the dripfeed is accessed using com.sun.dtv.media.dripfeed.DripFeedControl.

Tuning Access

The tuning element requests access to Tuning functions. Access to Tuning is restricted:

For the Java DTV Runtime, the Tuner is accessed using com.sun.dtv.tuner.Tuner.

Scarce Resources

The scarceresource element requests access to named resources with the action specified. Access to scarce resources is restricted:

For the Java DTV Runtime, normal access to scarce resources including the network device and tuner(s) is via the elements networkdevice and tuning. If the application needs to be able to force resources to be released then it MUST request access to the resource with a scarceresource element with the resource name and the action "force".

SmartCard Access

The smartcard element requests access to SmartCard APDU functions. Access to SmartCard is restricted:

For the Java DTV Runtime, the SmartCard is accessed using Security and Trust Services API for J2ME(TM).

Service Selection Access

The serviceselect requests access to Service Selection functions are defined to allow some applications to select the next service to be presented. Access to Service Selection is restricted:

Access to the service is via Locator, the normal policy for access through the locate MUST be applied.

For the Java DTV Runtime, Services are selected using java.tv.service.selection.ServiceContext of the Java TV API.

User Property Access

The userproperty element requests access to User Properties that are defined to allow applications to customize themselves. Access to user properties is restricted:

For the Java DTV Runtime, access to user properties is via com.sun.dtv.platform package.

Network Access

The network element requests access to Network connections to hosts via the network device. Access to hosts is restricted:

For the Java DTV Runtime, network access is accomplished using the APIs of com.sun.dtv.net.NetworkDevice.

Inter-application communication (IXC) access

The ixcaccess element requests access to the inter-application communication functions. Access to ixc is restricted:

For the Java DTV Runtime, inter-application access is accomplished using the APIs of javax.microedition.xlet.ixc using the namespace defined for signed DTV applications.

Persistent File Credential Access

The persistentfilecredential element requests access to an application's (the grantor) own resources, commonly files, and grants access to another specific application (the grantee). The signed authorization to grant access is created and signed by the grantor but is delivered to the device by the grantee by embedding the file access information in the Per Application Policy.

The elements for the file access information included in the Per Application policy are:

Element Description
grantoridentifier The organization id of the owner of the resource.
expirationdate Access can be granted through the expiration date but not beyond. The date must be formatted as mm/dd/yyyy where mm, dd, yyyy are decimal numbers representing the month, day, and year; both month and day start from 1.
filename The pathname relative to the persistent root with the following syntax:
    filename = persistentfilename
             | persistentpath "/" persistentfilename
             | persistentpath "/" "*"
             | persistentpath "/" "-"
        
    persistentpath = name
             | persistentpath "/" name
        
    persistentfilename = name |
        name "." suffix
        
    name = 8*fchar ; length is limited to 8 characters
    
    suffix = 3*fchar ; length is limited to 3 characters
    
                            fchar = "a".."z" | "A".."Z" | "0".."9" | "_"
where:
  • "/" is the path separator.
  • "*" used at the end indicates all files contained in the directory.
  • "-" used at the end indicates all files in the directory and existing subdirectories recursively at the time the request is parsed.
The attributes of the filename are "read" and "write", their values MUST be either "true" or "false".
signature The file access information is concatenated as defined below. The binary stream is signed by the grantor and then Base64 encoded.
certchainfileid The identifier used to locate the certificates in the /META-INF directory used to authenticate the signature.

The file access information is concatenated for signing in the following order:

Fields The Binary Encoding
grantee.organization_id The 32 bit organization id of the grantee.
grantee.application_id The 16 bit application id of the grantee.
grantor.organization_id The 32 bit organization id of the grantor.
expiration date The characters in ASCII. 10 characters, for example "01/01/2008"
filenames and actions
foreach (filenames) {
   "true" or "false" for read
   "true" or "false" for write
   filename
In the same order as the elements appear in the XML
4 characters for "true"; 5 characters for "false"
the filename and all characters in ASCII.

Access is granted to the listed files only if: