EPUB Open Container Format (OCF) 3.0

› 1.1 Purpose and Scope

This specification, EPUB Open Container Format (OCF) 3.0, defines a file format and processing model for encapsulating the set of related resources that comprise an EPUB® Publication — including any alternate renditions — into a single-file container. It also defines a standard method for obfuscating embedded fonts for those EPUB publications that require this functionality.

This specification is one of a family of related specifications that compose EPUB 3, the third major revision of an interchange and delivery format for digital publications based on XML and Web Standards. It is meant to be read and understood in concert with the other specifications that make up EPUB 3:

This specification supersedes Open Container Format (OCF) 2.0.1 [OCF2]. Refer to [EPUB3Changes] for information on differences between this specification and its predecessor.

› 1.2 Terminology

› 1.3 Conformance

› 3.1 Overview

An OCF Abstract Container defines a file system model for the contents of the container. The file system model uses a single common root directory for all of the contents of the container. All (non-remote) resources for embedded publications are located within the directory tree headed by the container’s root directory, although no specific file system structure is mandated for this. The file system model also includes a mandatory directory named META-INF that is a direct child of the root directory and which is used to store the following special files:

Complete conformance requirements for the various files in META-INF are found in META-INF.

› 3.2 File and Directory Structure

The virtual file system for the OCF Abstract Container must have a single common root directory for all of the contents of the container.

The OCF Abstract Container must include a directory named META-INF at the root level of the virtual file system. Requirements for the contents of this directory are described in META-INF.

The file name mimetype in the root directory is reserved for use by OCF ZIP Containers, as explained in OCF Physical Container: The ZIP Container .

All other files used by the publication rendition(s) within the OCF Abstract Container may be in any location descendant from the root directory except for mimetype at the root level or within the META-INF directory.

It is recommended that the contents of individual publications be stored within dedicated directories under the root to minimize potential file name collisions in the event that multiple renditions are used.

› 3.3 Relative IRIs for Referencing Other Components

Files within the OCF Abstract Container must reference each other via Relative IRI References ([RFC3987] and [RFC3986]). For example, if a file named chapter1.html references an image file named image1.jpg that is located in the same directory, then chapter1.html might contain the following as part of its content:

<img src="image1.jpg" alt="…" />
                

For Relative IRI References, the Base IRI [RFC3986] is determined by the relevant language specifications for the given file formats. For example, the CSS specification defines how relative IRI references work in the context of CSS style sheets and property declarations. Note that some language specifications reference RFCs that preceded RFC3987, in which case the earlier RFC applies for content in that particular language.

Unlike most language specifications, the Base IRIs for all files within the META-INF/ directory use the root folder for the Abstract Container as the default Base IRI. For example, if META-INF/container.xml has the following content:

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="OEBPS/Great Expectations.opf"
            media-type="application/oebps-package+xml" />	
    </rootfiles>
</container>
            

then the path OEBPS/Great Expectations.opf is relative to the root directory for the OCF Abstract Container and not relative to the META-INF/ directory.

› 3.4 File Names

The term File Name represents the name of any type of file, either a directory or an ordinary file within a directory within an OCF Abstract Container. For a given directory within the OCF Abstract Container, the Path Name is a string holding all directory names in the full path concatenated together with a “/” (ASCII 0x2F) character separating the directory names. For a given file within the Abstract Container, the Path Name is the string holding all directory names concatenated together with a “/” character separating the directory names, followed by a “/” character and then the name of the file. The File Name restrictions described below are designed to allow directory names and file names to be used without modification on most commonly used operating systems. This specification does not specify how an OCF Processor that is unable to represent OCF conforming File Names would compensate for this incompatibility.

The following statements apply to Conforming OCF Abstract Containers:

› 3.5 META-INF

All valid OCF Abstract Containers must include a directory called META-INF at the root level of the container file system. This directory contains the files specified below that describe the contents, metadata, signatures, encryption, rights and other information about the contained publication.

All files specified below must meet the conformance constraints for XML documents defined in XML Document Content Conformance [Publications30] .

Files other than the ones defined below may be included in the META-INF directory; OCF Processors must not fail when encountering such files.

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="OEBPS/My Crazy Life.opf"
            media-type="application/oebps-package+xml" />
    </rootfiles>
</container>
                    

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="OEBPS/My Crazy Life.opf"
            media-type="application/oebps-package+xml" />
        <rootfile full-path="PDF/My Crazy Life.pdf"
            media-type="application/pdf" />
    </rootfiles>
</container>
                    

<encryption
    xmlns ="urn:oasis:names:tc:opendocument:xmlns:container"
    xmlns:enc="http://www.w3.org/2001/04/xmlenc#"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <enc:EncryptedKey Id="EK">
        <enc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        <ds:KeyInfo>
            <ds:KeyName>John Smith</ds:KeyName>
        </ds:KeyInfo>
        <enc:CipherData>
            <enc:CipherValue>xyzabc</enc:CipherValue>
        </enc:CipherData>
    </enc:EncryptedKey>
    <enc:EncryptedData Id="ED1">
        <enc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#kw-aes128"/>
        <ds:KeyInfo>
            <ds:RetrievalMethod URI="#EK"
                Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey"/>
        </ds:KeyInfo>
        <enc:CipherData>
            <enc:CipherReference URI="image.jpeg"/>
        </enc:CipherData>
    </enc:EncryptedData>
</encryption>
                    

<signatures xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <Signature Id="sig" xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod 
                Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
            <Reference URI="#Manifest1">
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>j6lwx3rvEPO0vKtMup4NbeVu8nk=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>…</SignatureValue>
        <KeyInfo>
            <KeyValue>
                <DSAKeyValue>
                    <P>…</P><Q>…</Q><G>…</G><Y>…</Y> 
                </DSAKeyValue>
            </KeyValue>
        </KeyInfo>
        <Object>
            <Manifest Id="Manifest1">
                <Reference URI="OEBFPS/book.xml">                    
                    <Transforms>                                                
                        <Transform
                            Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>                        
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <DigestValue></DigestValue>
                </Reference>
                <Reference URI="OEBFPS/images/cover.jpeg">
                    <Transforms>                                                
                        <Transform
                            Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>                        
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <DigestValue></DigestValue>
                </Reference>
            </Manifest>
        </Object>
    </Signature> 
</signatures>
                    

› 4.1 Overview

This section is informative

An OCF ZIP Container is a physical single-file manifestation of an abstract container.

› 4.2 ZIP File Requirements

An OCF ZIP Container uses the ZIP format as specified by [ZIP APPNOTE], but with the following constraints and clarifications:

The following constraints apply to particular fields in the OCF ZIP Container archive:

› 4.3 OCF ZIP Container Media Type Identification

It is frequently necessary for applications to determine the media type of a file, which is usually accomplished by inspecting the file extension. OCF ZIP Containers should facilitate this form of rapid determination of their format by processing applications by using the .epub extension.

In order to translate a file extension into a media type, a processing agent typically will register the relationship between file extension and media type with the operating system. Applications that are interested in OCF ZIP Container files should register the media type application/epub+zip as corresponding to the file extension .epub.

File extensions do not provide a reliable means of identifying file formats, however. As a result, a more robust means of identifying files independent of their file names or extensions is also necessary. The method for such identification in ZIP archives is the inclusion of an uncompressed, unencrypted ASCII file named mimetype, where the contents of this file identify the media type of the Container. OCF ZIP Containers must consequently include a mimetype file as the first file in the Container, and the contents of this file must be the MIME type string application/epub+zip.

The contents of the mimetype file must not contain any leading padding or whitespace and the case of the MIME type string must be exactly as presented above. The mimetype file additionally must be neither compressed nor encrypted, and there must not be an extra field in its ZIP header.

When constructed with a conformant mimetype file, the ZIP Container offers convenient magic number support as described in RFC 2048 and the following will hold true:

› 5.1 Introduction

Since an OCF Zip Container is fundamentally a ZIP file, commonly available ZIP tools can be used to extract any unencrypted content stream from the package. On some systems, the contents of the ZIP file may appear like any other native container (e.g., a folder). While the ability to do this is quite useful, it can pose a problem for an Author who wishes to include a third-party font. Many commercial fonts allow embedding, but embedding a font implies making it an integral part of the publication, not providing the original font file along with the content. Since integrated ZIP support is so ubiquitous in modern operating systems, simply placing the font in the ZIP archive is insufficient to signify that the font is not intended to be reused in other contexts. This uncertainty can undermine the otherwise very useful font embedding capability that OPF/OPS provides.

In order to discourage reuse of the font, some font vendors may allow use of their fonts in EPUB publications if those fonts are bound in some way to the publication. That is, if the font file cannot be installed directly for use on an operating system with the built-in tools of that computing device, and it cannot be directly used by other EPUB publications. It is beyond the scope of this document to provide a digital rights management or enforcement system for font files. It will instead propose a method of obfuscation that will require additional work on the part of the final OCF recipient to gain general access to any included fonts. It is the hope of the IDPF that this will meet the requirements of most font vendors. No claim is made in this document or by the IDPF, however, that this constitutes encryption, nor does it guarantee that the font file will be secure from copyright infringement. The proposed mechanism will simply provide a stumbling block for those who are unaware of the license details of the supplied font. It will not prevent a determined user from gaining full access to the font. Given the original OCF Container, it is possible to apply the algorithms described in this document to extract the raw font file. Whether this satisfies the requirements of individual font licenses remains a question for the licensor and licensee.

› 5.2 Obfuscation Algorithm

The algorithm employed to obfuscate the font file consists of modifying the first 1040 bytes (~1KB) of the font file. In the unlikely event that the file is less than 1040 bytes, then the entire file will be modified. The key for the algorithm must be a 20 byte (160 bit) [SHA-1] digest of the publication's unique identifier. Details on generating this key are given in the section Generating the Obfuscation Key. To obfuscate the original data, the result of performing a logical exclusive or (XOR) on the first byte of the raw file and the first byte of the key is stored as the first byte of the embedded font file. This process is repeated with the next byte of source and key, until all bytes in the key have been used. At this point, the process continues starting with the first byte of the key and 21st byte of the source. Once 1040 bytes have been encoded in this way (or the end of the source is reached), any remaining data in the source is directly copied to the destination. In pseudo-code, this is the algorithm:

set source to font file
set destination to obfuscated file
set keyData to key for font
set outer to 0
while outer < 52 and not (source at EOF)
    set inner to 0
    while inner < 20 and not (source at EOF)
        read 1 byte from source     //Assumes read advances file position
        set sourceByte to result of read
        set keyByte to byte inner of keyData
        set obfuscatedByte to (sourceByte XOR keyByte)
        write obfuscatedByte to destination
        increment inner
    end while
    increment outer
end while
if not (source at EOF) then
    read source to EOF
    write result of read to destination
end if 
            

To get the original font data back, the process is simply reversed. That is, the source file becomes the obfuscated data and the destination file will contain the raw font data.

› 5.3 Generating the Obfuscation Key

To tie a font to a particular EPUB publication, it is necessary to bind to a unique property of that publication. Such a value is required by the EPUB Publications 3.0 specification, as detailed in Unique Identifier [Publications30] . Every compliant OPF file has a dc:identifier element which uniquely identifies the publication. The OPF 3.0 specification details finding this element by examining the unique-identifier attribute of the package file's package element. This element provides the required characteristic of being unique to a publication; it is not suitable for use directly as the obfuscation key, however (for instance, its length is not defined).

In order to create a suitable key that is tied to the publication, an SHA-1 digest of the unique identifier should be generated as specified by the Secure Hash Standard [SHA-1]. Before generating the digest, all whitespace characters as defined by the XML 1.0 specification [XML], section 2.3 are removed. Specifically the Unicode code points 0x20, 0x09, 0x0D and 0x0A must be stripped from the string before the digest is computed. This digest is then directly used as the key for the algorithm described in Obfuscation Algorithm.

› 5.4 Specifying Obfuscated Resources

All encrypted data in an OCF Abstract Container must have an entry in the encryption.xml file accompanying the publication (see Encryption – META-INF/encryption.xml), which includes fonts obfuscated using the method described here. For such obfuscated fonts, in the encryption.xml file, the EncryptionMethod element child of the EncryptedData must have an Algorithm attribute with the value http://www.idpf.org/2008/embedding. The presence of this attribute signals the use of the algorithm described in this specification. All resources that have been obfuscated using this approach must be listed in the CipherData element.

<encryption 
    xmlns="urn:oasis:names:tc:opendocument:xmlns:container" 
    xmlns:enc="http://www.w3.org/2001/04/xmlenc#">
    <enc:EncryptedData> 
        <enc:EncryptionMethod Algorithm="http://www.idpf.org/2008/embedding"/> 
        <enc:CipherData> 
            <enc:CipherReference URI="OEBPS/Fonts/BKANT.TTF"/>  
        </enc:CipherData> 
    </enc:EncryptedData>  
</encryption> 

                

To prevent trivial copying of the embedded font to other publications, the explicit key must not be provided in the encryption.xml file. Reading systems that implement this specification must derive the key from the package's unique identifier.