Manifest Format

0. Archive signing

This specification does not specify the format of the archive file. Any format supporting hierarchical paths is acceptable. Files added to the archive for this specification will be kept in a directory as ordinary files in the archive.

Any URL identifiers in a manifest file will conform to the URL syntax described in RFC 1738, "Uniform Resource Locators." Additionally, hierarchical paths in a manifest will use '/' (forward-slash) as the separator, for consistency with the URL syntax of RFC 1738."

1. Reasons for this scheme.

2. Filenames in the archive

Archives are signed by creating a "META-INF/" directory at the top level of the path tree. A leading "/" is acceptable if other pathnames contain a leading "/" (ie, "/META-INF/").

There is exactly one manifest file in the archive, with pathname

  META-INF/MANIFEST.MF

Signature files have pathnames of the form

  META-INF/x.SF
for some string x containing only the characterse A-Z 0-9 and dash or underscore. x must not be more than 8 characters.

The encoding of non-ASCII characters in filenames (if they are supported) is defined by the archive format or some other convention, not by this specification. But filenames in the META-INF directory are restricted as above.

The names "META-INF", "MANIFEST.MF", and the filetype ".SF" should be generated as uppercase, but recognized in any case.

3. Name-Value pairs and sections

In most cases, information contained within the manifest file or signature files is represented as so-called "name: value" pairs inspired by the RFC822 standard.

Groups of name-value pairs are known as a "section". Sections are separated from other sections by empty lines.

Binary data of any form is represented as base64. Continuations are required for binary data which causes line length to exceed 72 bytes. Examples of binary data are digests and signatures.

Implementations shall support header values of up to 65535 bytes.

Specification:

  section: *header +newline
  nonempty-section: +header +newline
  newline: CR LF
         | LF
         | CR (not followed by LF)

; That 'not followed by LF' probably requires some minor
; ugliness in the parser. Sorry.

  header: alphanum *headerchar ":" SPACE *otherchar newline
          *continuation

  continuation: SPACE *otherchar newline

; RFC822 has +(SPACE | TAB), but this way continuation lines 
; never get mangled.

  alphanum: {"A"-"Z"} | {"a"-"z"} | {"0"-"9"}

  headerchar: alphanum | "-" | "_"

  otherchar: any Unicode character except NUL, CR and LF

; Also: To prevent mangling of files sent via straight e-mail, no 
; header will start with the four letters "From".

; When version numbering is used:

  number: {"0"-"9"}+

; The number needn't be, e.g. 1.11 is considered to be later
; than 1.9. Both major and minor versions must be 3 digits or less.

4. Manifest file.

The manifest file consists of a list of files present within the archive itself. Not all files in the archive need to be listed in the manifest, but all files which are to be signed must be listed. The manifest file itself must not be listed.

A preliminary section appears at the top of the file containing, at minimum, this standard's version number.

  Manifest-Version: 1.0
Optionally, a version required for use may be specified:
  Required-Version: 1.0
If Version: is higher than Required-Version, extensions may be used.

The manifest file consists of sections which are entries for various files in the archive.

Many of the headers themselves are not covered by this specification. The following are required:

  Name: dirpath/whatever.class
  Digest-Algorithms: (list of algorithms)
  (algorithm)-Digest: (base-64 representation of digest)

The "Name:" header shall contain a relative path to the file being signed within the archive, OR an absolute URL referencing data outside the archive.

Example manifest file:

  Manifest-Version: 1.0

  Name: common/class1.class
  Digest-Algorithms: MD5
  MD5-Digest: (base64 representation of MD5 digest)

  Name: common/class2.class
  Digest-Algorithms: MD5, SHA
  MD5-Digest: (base64 representation of MD5 digest)
  SHA-Digest: (base64 representation of SHA digest)

Specification:

  manifest-file: "Manifest-Version: 1.0" newline
                 manifest-start
                 *manifest-entry

  manifest-start: section

  ; Optional header is
  ;   Required-Version: number "." number
  ;
  ; Required-Version indicates that only tools of the given version
  ; or later can be used to manipulate the file.

; The value of Digest-Algorithms is a comma-separated-list:

  comma-separated-list: +headerchar "," *whitespace comma-separated-list
                      | +headerchar

5. Signature instructions

Each signer is represented by a signature file.

A preliminary section appears at the top of the file containing, at minimum, this standard's version number.

  Signature-Version: 1.0
Information supplied by the signer but not specific to any particular pathname should be included in this preliminary header.

The major part of the file is similar form to the manifest file. The purpose here is to allow "policy" to be embedded in headers supplied by the signer rather than the manifest owner (who is normally the person who generated the archive.)

Signature files consist of sections which are essentially lists of names, all of which must be present in the manifest file. Extra headers may be included here. A digest is also present, but this is a digest of the entry in the manifest file.

Paths or URL's appearing in the manifest file but not in the signature file are not used in calculation. This allows subsets of the archive to be signed.

Only the Name: is required.

Validating a file:

The signature is first verified when the manifest is first parsed. This verification can be remembered, for efficiency. This only validates the signature directions themselves, not the actual archive files.

To validate a file, a digest value in the signature file is compared against a digest calculated against the corresponding entry in the manifest file. Then, a digest value in the manifest file is compared against a digest calculated against the actual data referenced in the "Name:" header -- relative path or URL.

 Example signature file:

  Signature-Version: 1.0

  Name: common/class1.class
  Digest-Algorithms: MD5
  MD5-Digest: (base64 representation of MD5 digest)

  Name: common/class2.class
  Digest-Algorithms: MD5
  MD5-Digest: (base64 representation of MD5 digest)

Specification:

  signature-file: "Signature-Version: 1.0" newline
                  signature-start
                  *signature-entry
                  signature-end

  signature-start: section

; Optional header is
;   Required-Version: number "." number
; This has the same meaning as in manifest-start.
; The only required header is Name. Its format is the same
; as in a manifest-entry.

The Magic Keyword

Another requirement to validate the signature on a given manifest entry is that the verifier understand the value or values of the Magic key-pair value in that entry's manifest entry.

The Magic key is optional but it is required that a parser understand the value of an entry's Magic key if it is verifying that entry's signature.

The value or values of the key Magic are a set of comma-separated context-specific strings. The spaces before and after the commas are ignored. Case is ignored. The exact meaning of the magic keywords is application specific. These keywords indicate how to compute the hash value contained in the manifest entry, and are therefore crucial to the proper verification of the signature. The keywords may be used for dynamic or embedded content, multiple hashes for multilingual documents, etc.

Here are two examples of the potential use of Magic:

	Name: http://www.scripts.com/index#script1
	Digest-Algorithms: SHA
	SHA-Digest: (base64 representation of SHA hash)
	Magic: JavaScript, Dynamic
	Name: http://www.tourist.com/guide.html
	Digest-Algorithms: SHA
	SHA-Digest: (base64 representation of SHA hash)
	SHA-Digest-French: (base64 representation of SHA hash)
	SHA-Digest-German: (base64 representation of SHA hash)
	Magic: Multilingual

In the first example, these Magic values may indicate that the result of an http query is the script embedded in the document, as opposed to the document itself, and also that the script is generated dynamically. These two pieces of information indicate how to compute the hash value against which to compare the Manifest's hash value, thus comparing a valid signature.

In the second example, the Magic value indicates that the document retrieved may have been content-negotiated for a specific language, and that the hash to verify against is dependent on which language the document retrieved is written in.

6. Digital Signatures

A digital signature in the specification is a signed version of the ".SF" (signature instructions) file. These are binary files not intended to be interpreted by humans.

Digital signature files have the same filename as the .SF file but different extension. The extension varies depending on the type of digital signature.

  .RSA      (PKCS7 signature, MD5 + RSA)
  .DSA      (PKCS7 signature, DSA)
  .PGP      (Pretty Good Privacy Signature)
For those formats that do not support external signed data, the file shall consist of a signed copy of the .SF file. Thus some data may be duplicated and a verifier ought to compare the two files.

Formats that support external data either reference the ".SF" file, or perform calculations on it with implicit reference.

Each .SF file may have multiple digital signatures, but those signatures ought to be generated by the same legal entity.

Filetypes may be 1 to 3 "alphanum" characters. Filetypes unrecognized must obviously be ignored.

7. Notes

Before parsing:

Headers:

Versions:

Ordering:

Line length:

Errors:

Limitations:

Signers:

Algorithms:

7. Acknowledgements

The authors of this specification are:

Thomas Dell (tdell@netscape.com)
Netscape Corporation

David Hopwood (david.hopwood@lady-margaret-hall.oxford.ac.uk)
Oxford University

Dave Brown (brown@eng.sun.com)
Benjamin Renaud (br@eng.sun.com)
David Connelly (dac@eng.sun.com)
Sun Microsystems, Inc.


Copyright © 1996 Netscape Corporation All rights reserved.
Copyright © 1996 Sun Microsystems, Inc.
Distribution: Unlimited.

java-security@java.sun.com