1.1 Purpose and Scope

This section is informative

This specification, EPUB Open Container Format (OCF) 3.1, defines a file format and processing model for encapsulating the set of related resources that comprise an EPUB® Publication into a single-file container, the EPUB Container.

This specification defines the rules for structuring the file collection in the abstract (the "abstract container") and the rules for the representation of this abstract container within a ZIP archive (the "ZIP container"). The rules for ZIP containers build upon the ZIP technologies used by [ODF]. OCF also defines a standard method for obfuscating embedded resources, such as fonts, for those EPUB Publications that require this functionality.

This specification is one of a family of specifications that compose [EPUB 3.1], 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.1.

Refer to [EPUB3 Changes] for more information on the differences between this specification and its predecessor.

  1.2 Terminology

Terms with meanings specific to EPUB 3.1 are capitalized in this document (e.g., "Author", "Reading System"). A complete list of these terms and definitions is provided in [EPUB 3.1].

Only the first instance of a term in a section is linked to its definition.

In addition, the following terminology is defined for use in this specification:

  1.3 Typographic Conventions

The following typographic conventions are used in this specification:

Informative markup examples are in light gray boxes.

  1.4 Conformance Statements

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].

All sections and appendixes of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendixes applies to all child content and subsections they contain.

All examples in this specification are informative.

  2.1 Container Conformance

  2.2 Reading System Conformance

An EPUB Reading System must meet all of the following criteria:

  3.1 Introduction

This section is informative

The OCF Abstract Container file system model uses a single common Root Directory for all of the contents. All Local Resources for the EPUB Publication are located within the directory tree headed by the Root Directory, but no specific file system structure for them is mandated by this specification.

The file system model also includes a mandatory directory named META-INF that is a direct child of the Root Directory and is used to store the following special files:

Conformance requirements for the various files in the META-INF directory are defined in META-INF Directory.

  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 that is a direct child of the container's root directory. Requirements for the contents of this directory are described in META-INF Directory.

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

All other files within the OCF Abstract Container may be in any location descendant from the Root Directory, provided they are not within the META-INF directory.

It is recommended that the contents of the EPUB Publication be stored within its own dedicated directory under the Root Directory.

  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]).

<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, [CSS 2.1] defines how relative IRI references work in the context of CSS style sheets and property declarations.

Unlike most language specifications, the Base IRIs for all files within the META-INF directory use the Root Directory of the OCF 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="EPUB/Great_Expectations.opf"
            media-type="application/oebps-package+xml" />	
    </rootfiles>
</container>
            

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

All relative IRI references must resolve to resources within the OCF Abstract Container (i.e., at or below the Root Directory).

  3.4 File Names

The Root Directory restrictions described in this section are designed to allow Path 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 File and Path Names would compensate for this incompatibility.

In the context of an OCF Abstract Container, File and Path Names are case sensitive and must meet all of the following criteria:

  3.5 META-INF Directory

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="EPUB/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="SVG/Sandman.opf"
            media-type="application/oebps-package+xml" />
        <rootfile full-path="XHTML/Sandman.opf"
            media-type="application/oebps-package+xml" />
    </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>
                    

<encryption xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <enc:EncryptedData xmlns:enc="http://www.w3.org/2001/04/xmlenc#">
        ...
        <enc:CipherData>
            <enc:CipherReference URI="OEPBS/video.mp4"/>
        </enc:CipherData>
        <enc:EncryptionProperties>
            <enc:EncryptionProperty xmlns:ns="http://www.idpf.org/2016/encryption#compression">
                <ns:Compression Method="8" OriginalLength="3500000"/>
            </enc:EncryptionProperty>
        </enc:EncryptionProperties>
        ...
    </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="EPUB/book.xhtml">                    
                    <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="EPUB/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 Introduction

This section is informative

An OCF ZIP Container is a physical single-file manifestation of an OCF Abstract Container. The Container is used:

  4.2 ZIP File Requirements

An OCF ZIP Container uses the ZIP format as specified by [ZIP APPNOTE 6.3.3], 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

OCF ZIP Containers must include a mimetype file as the first file in the Container. The contents of this file must be the MIME media type [RFC2046] string application/epub+zip encoded in US-ASCII [US-ASCII].

The contents of the mimetype file must not contain any leading padding or whitespace, must not begin with the Unicode signature (or Byte Order Mark), and the case of the media type string must be exactly as presented above. The mimetype file additionally must not be compressed or encrypted, and there must not be an extra field in its ZIP header.

  5.1 Introduction

This section is informative

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. Moreover, the nature of ZIP files means that their contents might appear like any other native container on some systems (e.g., a folder).

While this simplicity of ZIP files is quite useful, it also poses a problem when ease of extraction of resources is not a desired side-effect of not encrypting them. An Author who wishes to include a third-party font, for example, typically does not want that font extracted and re-used by others. More critically, many commercial fonts allow embedding, but embedding a font implies making it an integral part of the EPUB Publication, not just providing the original font file along with the content.

Since integrated ZIP support is so ubiquitous in modern operating systems, simply placing a font in the ZIP archive is insufficient to signify that it is not intended to be reused in other contexts. This uncertainty can undermine the otherwise very useful font embedding capability of EPUB Publications.

In order to discourage reuse of the font, some font vendors might only allow use of their fonts in EPUB Publications if those fonts are bound in some way to the EPUB 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 specification to provide a digital rights management or enforcement system for such resources. This section instead defines a method of obfuscation that will require additional work on the part of the final OCF recipient to gain general access to any obfuscated resources.

Note that no claim is made in this specification, or by the IDPF, that this constitutes encryption, nor does it guarantee that the resource will be secure from copyright infringement. It is the hope of the IDPF, however, that this algorithm will meet the requirements of most vendors who require some assurance that their resources cannot simply be extracted by unzipping the Container.

In the case of fonts, the primary use case for obfuscation, the defined mechanism will simply provide a stumbling block for those who are unaware of the license details. It will not prevent a determined user from gaining full access to the font. Given an OCF Container, it is possible to apply the algorithms defined to extract the raw font file. Whether this method of obfuscation satisfies the requirements of individual font licenses remains a question for the licensor and licensee.

  5.2 Obfuscation Key

The key used in the obfuscation algorithm is derived from the Unique Identifier of the Default Rendition.

All whitespace characters, as defined by the XML 1.0 specification [XML], section 2.3, must be removed from this identifier — specifically, the Unicode code points U+0020, U+0009, U+000D and U+000A.

A SHA-1 digest of the UTF-8 representation of the resulting string should be generated as specified by the Secure Hash Standard [SHA-1]. This digest is then directly used as the key for the algorithm.

  5.3 Obfuscation Algorithm

The algorithm employed to obfuscate resource consists of modifying the first 1040 bytes (~1KB) of the file. In the unlikely event that the file is less than 1040 bytes, then the entire file will be modified.

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 obfuscation key is stored as the first byte of the embedded resource.

This process is repeated with the next byte of source and key, and continues 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.

Obfuscation of resources must occur before they are compressed and added to the OCF Container. Note that as obfuscation is not encryption, this requirement is not a violation of the one in Encryption File (encryption.xml) to compress resources before encrypting them.

set ocf to OCF container file
set source to file
set destination to obfuscated file
set keyData to key for file
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
Deflate destination
store destination as source in ocf
            

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

  5.4 Specifying Obfuscated Resources

Although not technically encrypted data, all obfuscated resources must have an entry in the encryption.xml file accompanying the EPUB Publication (see Encryption File (encryption.xml)).

An EncryptionMethod element must be included for each obfuscated resource. Each must include a child EncryptedData element whose Algorithm attribute is set to the value http://www.idpf.org/2008/embedding. The presence of this attribute signals the use of the algorithm described in this specification. The path to the obfuscated resource must be listed in the CipherReference child of 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="EPUB/Fonts/BKANT.TTF"/>  
        </enc:CipherData> 
    </enc:EncryptedData>  
</encryption> 

                

To prevent trivial copying of the embedded resource to other EPUB Publications, the obfuscation key must not be provided in the encryption.xml file.