3.5.2.1 Container File (container.xml)

The required container.xml file in the META-INF directory identifies the EPUB Packages in the OCF Abstract Container.

The contents of this file must be valid to the schema in Schema for container.xml after removing all elements and attributes from other namespaces (including all attributes and contents of such elements).

Each rootfile element must identify the location of a Package Document representing one Rendition of the EPUB Publication.

An OCF Processor must consider the first rootfile element within the rootfiles element to represent the Default Rendition for the contained EPUB Publication. Reading Systems are required to present the Default Rendition, but may present other Renditions in the container.

<?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>
                    

The optional links element identifies resources necessary for the processing of the OCF ZIP Container. Each of its child link elements must include an href attribute whose value identifies the location of a resource. Each link element also must include a rel attribute whose value identifies the relationship of the resource, and may include a media-type attribute whose value must be a media type [RFC2046] that specifies the type and format of the resource referenced by the link.

The value of the rootfile element full-path attribute and the link element href attribute must contain a path component [RFC3986] which must take the form of a path-rootless [RFC3986] only. The path components are relative to the Root Directory.

OCF Processors must ignore foreign elements and attributes within a container.xml file.

  3.5.2.2 Encryption File (encryption.xml)

The optional encryption.xml file in the META-INF directory holds all encryption information on the contents of the container. If any resource within the container is encrypted, encryption.xml must be present to indicate that the resource is encrypted and provide information on how it is encrypted.

This file is an XML document whose root element is encryption. The encryption element contains child elements of type EncryptedKey and EncryptedData as defined by [XML ENC Core]. An EncryptedKey element describes each encryption key used in the container, while an EncryptedData element describes each encrypted file. Each EncryptedData element refers to an EncryptedKey element, as described in XML Encryption.

The contents of the encryption.xml file must be valid to the schema in Schema for encryption.xml.

OCF encrypts individual files independently, trading off some security for improved performance, allowing the container contents to be incrementally decrypted. Encryption in this way exposes the directory structure and file naming of the whole package.

OCF uses XML Encryption [XML ENC Core] to provide a framework for encryption, allowing a variety of algorithms to be used. XML Encryption specifies a process for encrypting arbitrary data and representing the result in XML. Even though an OCF Abstract Container might contain non-XML data, XML Encryption can be used to encrypt all data in an OCF Abstract Container. OCF encryption supports only the encryption of entire files within the container, not parts of files. The encryption.xml file, if present, must not be encrypted.

Encrypted data replaces unencrypted data in an OCF Abstract Container. For example, if an image named photo.jpeg is encrypted, the contents of the photo.jpeg resource should be replaced by its encrypted contents. Within the ZIP directory, encrypted files should be stored rather than Deflate-compressed.

Note that some situations require obfuscating the storage of embedded resources referenced by a Rendition to tie them to the "parent" EPUB Publication and make them more difficult to extract for unrestricted use (e.g., fonts). Although obfuscation is not encryption, the encryption.xml file is used in conjunction with the IDPF resource obfuscation algorithm to identify resources that need to be de-obfuscated before they can be used.

The following files must not be encrypted, regardless of whether default or specific encryption is requested:

Signed resources may subsequently be encrypted using the Decryption Transform for XML Signature [XML SIG Decrypt]. This feature enables an application such as an OCF agent to distinguish data that was encrypted before signing from data that was encrypted after signing. Only data that was encrypted after signing must be decrypted before computing the digest used to validate the signature.

<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>
                    

Order of Compression and Encryption

When stored in a ZIP container, streams of data with Non-Codec content types should be compressed before they are encrypted, and Deflate compression must be used. This practice ensures that file entries stored in the ZIP container have a smaller size.

Streams of data with Codec content types should not be compressed before they are encrypted. In such cases, additional compression would introduce unnecessary processing overhead at production time (especially with large resource files), and would impact audio/video playback performance at consumption time. In some cases, the combination of compression with some encryption schemes might even compromise the ability of Reading Systems to handle partial content requests (e.g. HTTP byte ranges), due to the technical impossibility to determine the length of the full resource ahead of media playback (e.g. HTTP Content-Length header).

Streams of data that are compressed before they are encrypted should provide additional EncryptionProperties metadata to specify the size of the initial resource (i.e., before compression and encryption), as per the Compression XML element defined below. Streams of data that are not compressed before they are encrypted may provide the additional EncryptionProperties metadata to specify the size of the initial resource (i.e., before 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>

  3.5.2.3 Manifest File (manifest.xml)

The optional manifest.xml file in the META-INF directory provides a manifest of files in the Container.

The OCF specification does not mandate a format for the manifest.

Note that the manifest element contained within a Package Document specifies the one and only manifest used for processing a given Rendition. Ancillary manifest information contained in the ZIP archive or in the optional manifest.xml file must not be used for processing the Rendition.

  3.5.2.4 Metadata File (metadata.xml)

The optional META-INF/metadata.xml file in the META-INF directory, if present, must be used for container-level metadata.

If the metadata.xml file is present, its contents should be only namespace-qualified elements [XMLNS]. The file should contain the root element metadata in the namespace http://www.idpf.org/2013/metadata, but other root elements are allowed for backwards compatibility. Reading Systems should ignore metadata.xml files with unrecognized root elements.

This version of the OCF specification does not define metadata for use in the metadata.xml file. Container-level metadata may be defined in future versions of this specification and in IDPF-defined EPUB extension specifications.

  3.5.2.5 Rights Management File (rights.xml)

The optional rights.xml file in the META-INF directory is reserved for digital rights management (DRM) information for trusted exchange of EPUB Publications among rights holders, intermediaries, and users.

This version of the OCF specification does not require a specific format for DRM information, but a future version might. The contents of the rights.xml should be only namespace-qualified elements [XMLNS] to avoid collision with a future format.

When the rights.xml file is not present, no part of the container is rights governed at the container level. Rights expressions might exist within the contained Renditions.

If the rights.xml file is not present, no part of the OCF Abstract Container is rights governed.

  3.5.2.6 Digital Signatures File (signatures.xml)

The optional signatures.xml file in the META-INF directory holds digital signatures for the container and its contents. The contents of this file must be valid to the schema in Schema for signatures.xml.

The root element of the signatures.xml file is the signatures element. This element contains child elements of type Signature, as defined by [XML DSIG Core]. Signatures can be applied to an EPUB Publication as a whole or to its parts, and can specify the signing of any kind of data (i.e., not just XML).

When the signatures.xml file is not present, no part of the container is digitally signed at the container level. Digital signing might exist within the EPUB Publication.

When a data signature is created for the container, the signature should be added as the last child Signature element of the signatures element.

Any or all files in the container can be signed in their entirety with the exception of the signatures.xml file since that file will contain the computed signature information. Whether and how the signatures.xml file is signed depends on the objective of the signer.

If the signer wants to allow signatures to be added or removed from the container without invalidating the signer’s signature, the signatures.xml file should not be signed.

If the signer wants any addition or removal of a signature to invalidate the signer’s signature, the Enveloped Signature transform defined in Section 6.6.4 of [XML DSIG Core] can be used to sign the entire preexisting signature file excluding the Signature being created. This transform would sign all previous signatures, and it would become invalid if a subsequent signature was added to the package.

The [XML DSIG Core] specification does not associate any semantics with a signature; an agent might include semantic information, for example, by adding information to the Signature element that describes the signature. The [XML DSIG Core] specification describes how additional information can be added to a signature, such as by use the SignatureProperties element.

<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>