1 ---
2 # Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 #
5 # This code is free software; you can redistribute it and/or modify it
6 # under the terms of the GNU General Public License version 2 only, as
7 # published by the Free Software Foundation.
8 #
9 # This code is distributed in the hope that it will be useful, but WITHOUT
10 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 # version 2 for more details (a copy is included in the LICENSE file that
13 # accompanied this code).
14 #
15 # You should have received a copy of the GNU General Public License version
16 # 2 along with this work; if not, write to the Free Software Foundation,
17 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 #
19 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 # or visit www.oracle.com if you need additional information or have any
21 # questions.
22
23 title: 'JAR File Specification'
24 ---
25
26 -------------------------------------------------------------------------------
27
28 Contents
29 --------
30
31 - [Introduction](#Intro)
32 - [Modular JAR files](#Modular)
33 - [Multi-release JAR files](#Multi-release)
34 - [Modular multi-release JAR files](#Modular-multi-release)
35 - [The META-INF directory](#The_META-INF_directory)
36 - [Name-Value pairs and Sections](#Name-Value_pairs_and_Sections)
37 - [JAR Manifest](#JAR_Manifest)
38 - [Overview](#Manifest-Overview)
39 - [Manifest Specification](#Manifest_Specification)
40 - [Main Attributes](#Main_Attributes)
41 - [Per-Entry Attributes](#Per-Entry_Attributes)
42 - [Signed JAR file](#Signed_JAR_File)
43 - [Overview](#SignedJar-Overview)
44 - [Signature File](#Signature_File)
45 - [Signature validation](#Signature_Validation)
46 - [The Magic Attribute](#The_Magic_Attribute)
47 - [Digital Signatures](#Digital_Signatures)
48 - [Notes on Manifest and Signature
49 Files](#Notes_on_Manifest_and_Signature_Files)
50 - [JAR Index](#JAR_Index)
51 - [Overview](#Overview)
52 - [Index File Specification](#Index_File_Specification)
53 - [Backward Compatibility](#Backward_Compatibility)
54 - [Service Provider](#Service_Provider)
55 - [Overview](#Service_Provider_Overview)
56 - [Provider Configuration File](#Provider_Configuration_File)
57 - [Example](#Example)
58 - [Class-Path attribute](#classpath)
59 - [Package Sealing](#sealing)
60 - [API Details](#API_Details)
61 - [See Also](#See_Also)
62
63 []{#Intro}Introduction
64 ----------------------
65
66 JAR file is a file format based on the popular ZIP file format and is
67 used for aggregating many files into one. A JAR file is essentially a
68 zip file that contains an optional META-INF directory. A JAR file can be
69 created by the command-line [jar](https://docs.oracle.com/javase/9/tools/jar.htm#JSWOR614) tool, or
70 by using the [`java.util.jar`](../../api/java/util/jar/package-summary.html) API in the Java platform. There is no
71 restriction on the name of a JAR file, it can be any legal file name on
72 a particular platform.
73
74 []{#Modular}Modular JAR files
75 -----------------------------
76
77 A modular JAR file is a JAR file that has a module descriptor,
78 `module-info.class`, in the top-level directory (or root) directory. The
79 module descriptor is the binary form of a module declaration. (Note the section
80 on [multi-release JAR files](#Multi-release) further refines the definition of
81 modular JAR files.)
82
83 A modular JAR file deployed on the module path, as opposed to the class path, is
84 an *explicit* module. Dependences and service providers are declared in the
85 module descriptor. The [JAR Manifest](#JAR_Manifest) is ignored as is any
86 service configuration under the [`META-INF`](#The_META-INF_directory) directory.
87 However, if the modular JAR file is deployed on the class path then it behaves
88 as if a non-modular JAR file and the JAR Manifest and configuration under
89 the `META-INF` directory are not ignored.
90
91 A non-modular JAR file deployed on the module path is an *automatic module*,
92 where a module declaration is synthesized from the JAR file name and
93 its contents. For further details see the specification on the method
94 [java.lang.module.ModuleFinder.of](../../../api/java/lang/module/ModuleFinder.html#of-java.nio.file.Path...-).
95
96 []{#Multi-release}Multi-release JAR files
97 -----------------------------------------
98
99 A multi-release JAR file allows for a single JAR file to support multiple
100 major versions of Java platform releases. For example, a multi-release JAR file
101 can depend on both the Java 8 and Java 9 major platform releases, where some
102 class files depend on APIs in Java 8 and other class files depend on APIs in
103 Java 9.
104 This enables library and framework developers to decouple the use of APIs in a
105 specific major version of a Java platform release from the requirement that all
106 their users migrate to that major version. Library and framework developers can
107 gradually migrate to and support new Java features while still supporting the
108 old features.
109
110 A multi-release JAR file is identified by the main attribute:
111
112 Multi-Release: true
113
114 declared in the main section of the [JAR Manifest](#JAR_Manifest).
115
116 Classes and resource files dependent on a major version, 9 or greater, of a
117 Java platform release may be located under a *versioned directory* instead of
118 under the top-level (or root) directory. The versioned directory
119 is located under the [the META-INF directory](#The_META-INF_directory) and is
120 of the form:
121
122 META-INF/versions/N
123
124 where N is the string representation of the major version number of a Java
125 platform release. Specifically `N` must conform to the specification:
126
127 -------------------------------- --------------------------------------------------------------------------------
128 *N:* *`{1-9}` `{0-9}`\**
129 -------------------------------- --------------------------------------------------------------------------------
130
131 Any versioned directory whose value of `N` is less than `9` is ignored as is
132 a string representation of `N` that does not conform to the above specification.
133
134 A class file under a versioned directory, of version `N` say, in a multi-release
135 JAR must have a class file version less than or equal to the class file
136 version associated with `N`th major version of a Java platform release.
137 If the class of the class file is public or protected then that class must
138 *preside over* a class of the same fully qualified name and access modifier
139 whose class file is present under the top-level directory. By logical extension
140 this applies to a class of a class file, if present, under a versioned directory
141 whose version is less than `N`.
142
143 If a multi-release JAR file is deployed on the class path or module path
144 (as an automatic module or an explicit [multi-release module](#Modular-multi-release))
145 of major version `N` of a Java platform release runtime, then a class loader
146 loading classes from that JAR file will first search for class files under the
147 `N`th versioned directory, then prior versioned directories in descending order
148 (if present), down to a lower major version bound of `9`, and finally under the
149 top-level directory.
150
151 The public API exported by the classes in a multi-release JAR file must be
152 *exactly* the same across versions, hence at a minimum why versioned public or
153 protected classes for class files under a versioned directory must preside over
154 classes for class files under the top-level directory. It is difficult and
155 costly to perform extensive API verification checks as such tooling, such as the
156 `jar` tool, is not required to perform extensive verification and a Java runtime
157 is not required to perform any verification. A future release of this
158 specification may relax the exact same API constraint to support careful
159 evolution.
160
161 Resources under the `META-INF` directory cannot be versioned (such as for
162 service configuration).
163
164 A multi-release JAR file can be signed.
165
166 Multi-release JAR files are not supported by the boot class loader of a Java
167 runtime. If a multi-release JAR file is appended to the boot class path (with
168 the `-Xbootclasspath/a` option) then the JAR is treated as if it is an ordinary
169 JAR file.
170
171 ### []{#Modular-multi-release}Modular multi-release JAR files
172
173 A modular multi-release JAR file is a multi-release JAR file that has a
174 module descriptor, `module-info.class`, in the top-level directory (as for
175 a [modular](#Modular) JAR file), or directly in a versioned directory.
176
177 A public or protected class in a non-exported package (that is not declared as
178 exported in the module descriptor) need not preside over a class of the same
179 fully qualified name and access modifier whose class file is present under
180 the top-level directory.
181
182 A module descriptor is generally treated no differently to any other class or
183 resource file. A module descriptor may be present under a versioned area but
184 not present under the top-level directory. This ensures, for example, only Java
185 8 versioned classes can be present under the top-level directory while Java 9
186 versioned classes (including, or perhaps only, the module descriptor) can be
187 present under the `9` versioned directory.
188
189 Any versioned module descriptor that presides over a lesser versioned module
190 descriptor or that at the top-level, `M` say, must be identical to `M`, with two
191 exceptions:
192
193 1. the presiding versioned descriptor can have different non-`transitive`
194 `requires` clauses of `java.*` and `jdk.*` modules; and
195 2. the presiding versioned descriptor can have different `uses` clauses, even of
196 service types defined outside of `java.*` and `jdk.*` modules.
197
198 Tooling, such as the `jar` tool, should perform such verification of versioned
199 module descriptors but a Java runtime is not required to perform any
200 verification.
201
202 []{#The_META-INF_directory}The META-INF directory
203 -------------------------------------------------
204
205 The following files/directories in the META-INF directory are recognized
206 and interpreted by the Java 2 Platform to configure applications, class
207 loaders and services:
208
209 - `MANIFEST.MF`
210
211 The manifest file that is used to define package related data.
212
213 - `INDEX.LIST`
214
215 This file is generated by the new "`-i"` option of the jar tool, which
216 contains location information for packages defined in an application.
217 It is part of the JarIndex implementation and used by class loaders to
218 speed up their class loading process.
219
220 - `x.SF`
221
222 The signature file for the JAR file. 'x' stands for the base file name.
223
224 - `x.DSA`
225
226 The signature block file associated with the signature file with the
227 same base file name. This file stores the digital signature of the
228 corresponding signature file.
229
230 - `services/`
231
232 This directory stores all the service provider configuration files.
233
234 - `versions/`
235
236 This directory contains underneath it versioned class and resource files
237 for a [multi-release](#Multi-release) JAR file.
238
239 []{#Name-Value_pairs_and_Sections}Name-Value pairs and Sections
240 ---------------------------------------------------------------
241
242 Before we go to the details of the contents of the individual
243 configuration files, some format convention needs to be defined. In most
244 cases, information contained within the manifest file and signature
245 files is represented as so-called "name: value" pairs inspired by the
246 RFC822 standard. We also call these pairs headers or attributes.
247
248 Groups of name-value pairs are known as a "section". Sections are
249 separated from other sections by empty lines.
250
251 Binary data of any form is represented as base64. Continuations are
252 required for binary data which causes line length to exceed 72 bytes.
253 Examples of binary data are digests and signatures.
254
255 Implementations shall support header values of up to 65535 bytes.
256
257 All the specifications in this document use the same grammar in which
258 terminal symbols are shown in fixed width font and non-terminal symbols
259 are shown in italic type face.
260
261 ### []{#Section-Specification}Specification:
262
263 ------------------------ ------------------------------------------------------
264 *section:* *\*header +newline*
265 *nonempty-section:* *+header +newline*
266 *newline:* `CR LF | LF | CR` \(*not followed by* `LF`\)
267 *header:* *name* `:` *value*
268 *name:* *alphanum \*headerchar*
269 *value:* SPACE \**otherchar newline \*continuation*
270 *continuation:* SPACE *\*otherchar newline*
271 *alphanum:* {`A-Z`} | {`a-z`} | {`0-9`}
272 *headerchar:* *alphanum* | `-` | `_`
273 *otherchar:* *any UTF-8 character except* `NUL, CR` *and* `LF`
274 ------------------------ ------------------------------------------------------
275
276
277 * Note: To prevent mangling of files sent via straight e-mail, no header will start with the four letters "From".
278
279
280
281 Non-terminal symbols defined in the above specification will be
282 referenced in the following specifications.
283
284 []{#JAR_Manifest}JAR Manifest
285 -----------------------------
286
287 ### []{#Manifest-Overview}Overview
288
289 A JAR file manifest consists of a main section followed by a list of
290 sections for individual JAR file entries, each separated by a newline.
291 Both the main section and individual sections follow the section syntax
292 specified above. They each have their own specific restrictions and
293 rules.
294
295 * The main section contains security and configuration information about
296 the JAR file itself, as well as the application. It also defines main
297 attributes that apply to every individual manifest entry. No attribute
298 in this section can have its name equal to "`Name`". This section is
299 terminated by an empty line.
300
301 * The individual sections define various attributes for packages or files
302 contained in this JAR file. Not all files in the JAR file need to be
303 listed in the manifest as entries, but all files which are to be signed
304 must be listed. The manifest file itself must not be listed. Each
305 section must start with an attribute with the name as "`Name`", and the
306 value must be a relative path to the file, or an absolute URL
307 referencing data outside the archive.
308
309 * If there are multiple individual sections for the same file entry, the
310 attributes in these sections are merged. If a certain attribute have
311 different values in different sections, the last one is recognized.
312
313 * Attributes which are not understood are ignored. Such attributes may
314 include implementation specific information used by applications.
315
316 ### []{#Manifest_Specification}Manifest Specification:
317
318 -------------------------------- --------------------------------------------------------------------------------
319 *manifest-file:* *main-section newline \*individual-section*
320 *main-section:* *version-info newline \*main-attribute*
321 *version-info:* `Manifest-Version :` *version-number*
322 *version-number:* *digit+\{*`.`*digit+\}\**
323 *main-attribute:* *(any legitimate main attribute) newline*
324 *individual-section:* `Name :` *value* *newline \*perentry-attribute*
325 *perentry-attribute:* *(any legitimate perentry attribute) newline*
326 *newline:* `CR LF | LF | CR` (*not followed by* `LF`)
327 *digit:* `{0-9}`
328 -------------------------------- --------------------------------------------------------------------------------
329
330 In the above specification, attributes that can appear in the main
331 section are referred to as main attributes, whereas attributes that can
332 appear in individual sections are referred to as per-entry attributes.
333 Certain attributes can appear both in the main section and the
334 individual sections, in which case the per-entry attribute value
335 overrides the main attribute value for the specified entry. The two
336 types of attributes are defined as follows.
337
338
339 ### []{#Main_Attributes}Main Attributes
340
341 Main attributes are the attributes that are present in the main section
342 of the manifest. They fall into the following different groups:
343
344 - general main attributes
345 - Manifest-Version: Defines the manifest file version. The value
346 is a legitimate version number, as described in the above spec.
347 - Created-By: Defines the version and the vendor of the java
348 implementation on top of which this manifest file is generated.
349 This attribute is generated by the `jar` tool.
350 - Signature-Version: Defines the signature version of the jar
351 file. The value should be a valid *version-number* string.
352 - Class-Path: The value of this attribute specifies the relative
353 URLs of the libraries that this application needs. URLs are
354 separated by one or more spaces. The application class loader
355 uses the value of this attribute to construct its internal
356 search path. See [Class-Path Attribute](#classpath) section for
357 details.
358 - Multi-Release: This attribute defines whether this JAR file is a
359 [multi-release](#Modular-multi-release) JAR file. If the value is "true"
360 , case is ignored, then the JAR file will be processed by the Java
361 runtime and tooling as a multi-release JAR file. Otherwise, if the
362 value is anything other than "true" then this attribute is ignored.
363 - attribute defined for stand-alone applications: This attribute is
364 used by stand-alone applications that are bundled into executable
365 jar files which can be invoked by the java runtime directly by
366 running "`java -jar x.jar`".
367 - Main-Class: The value of this attribute is the class name of the
368 main application class which the launcher will load at startup
369 time. The value must *not* have the `.class` extension appended
370 to the class name.
371 - Launcher-Agent-Class: If this attribute is present then its
372 value is the class name of a *java agent* that is started before
373 the application main method is invoked. This attribute can be
374 used for cases where a java agent is packaged in the same
375 executable JAR file as the application. The agent class defines
376 a public static method name `agentmain` in one of the two forms
377 specified in the `java.lang.instrument` package description.
378 Additional attributes (such as `Can-Retransform-Classes`) can be
379 used to indicate capabilities needed by the agent.
380 - attributes defined for package
381 [versioning](../versioning/index.html) and [sealing](#sealing)
382 information: The value of these attributes apply to all the packages
383 in the JAR file, but can be overridden by per-entry attributes.
384 - Implementation-Title: The value is a string that defines the
385 title of the extension implementation.
386 - Implementation-Version: The value is a string that defines the
387 version of the extension implementation.
388 - Implementation-Vendor: The value is a string that defines the
389 organization that maintains the extension implementation.
390 - Specification-Title: The value is a string that defines the
391 title of the extension specification.
392 - Specification-Version: The value is a string that defines the
393 version of the extension specification.
394 - Specification-Vendor: The value is a string that defines the
395 organization that maintains the extension specification.
396 - Sealed: This attribute defines whether this JAR file is sealed
397 or not. The value can be either "true" or "false", case is
398 ignored. If it is set to "true", then all the packages in the
399 JAR file are defaulted to be sealed, unless they are defined
400 otherwise individually.
401
402 ### []{#Per-Entry_Attributes}Per-Entry Attributes
403
404 Per-entry attributes apply only to the individual JAR file entry to
405 which the manifest entry is associated with. If the same attribute also
406 appeared in the main section, then the value of the per-entry attribute
407 overwrites the main attribute's value. For example, if JAR file a.jar
408 has the following manifest content:
409
410 Manifest-Version: 1.0
411 Created-By: 1.8 (Oracle Inc.)
412 Sealed: true
413 Name: foo/bar/
414 Sealed: false
415
416 It means that all the packages archived in a.jar are sealed, except that
417 package foo.bar is not.
418
419 The per-entry attributes fall into the following groups:
420
421 - attributes defined for file contents:
422 - Content-Type: This attribute can be used to specify the MIME
423 type and subtype of data for a specific file entry in the
424 JAR file. The value should be a string in the form of
425 *type/subtype.* For example "image/bmp" is an image type with a
426 subtype of bmp (representing bitmap). This would indicate the
427 file entry as an image with the data stored as a bitmap. RFC
428 [1521](http://www.ietf.org/rfc/rfc1521.txt) and
429 [1522](http://www.ietf.org/rfc/rfc1522.txt) discuss and define
430 the MIME types definition.
431 - attributes defined for package versioning and sealing information:
432 These are the same set of attributes defined above as main
433 attributes that defines the extension package versioning and sealing
434 information. When used as per-entry attributes, these attributes
435 overwrites the main attributes but only apply to the individual file
436 specified by the manifest entry.
437 - attribute defined for beans objects:
438 - Java-Bean: Defines whether the specific jar file entry is a Java
439 Beans object or not. The value should be either "true" or
440 "false", case is ignored.
441 - attributes defined for signing: These attributes are used for
442 signing and verifying purposes. More details here.
443 - x-Digest-y: The name of this attribute specifies the name of the
444 digest algorithm used to compute the digest value for the
445 corresponding jar file entry. The value of this attribute stores
446 the actual digest value. The prefix 'x' specifies the algorithm
447 name and the optional suffix 'y' indicates to which language
448 the digest value should be verified against.
449 - Magic: This is an optional attribute that can be used by
450 applications to indicate how verifier should compute the digest
451 value contained in the manifest entry. The value of this
452 attribute is a set of comma separated context specific strings.
453 Detailed description is here.
454
455 []{#Signed_JAR_File}Signed JAR File
456 -----------------------------------
457
458 ### []{#SignedJar-Overview}Overview
459
460 A JAR file can be signed by using the command line
461 [jarsigner](http://docs.oracle.com/javase/9/tools/jarsigner.htm#JSWOR-GUID-925E7A1B-B3F3-44D2-8B49-0B3FA2C54864) tool or directly
462 through the `java.security` API. Every file entry, including
463 non-signature related files in the `META-INF` directory, will be signed
464 if the JAR file is signed by the jarsigner tool. The signature related
465 files are:
466
467 - `META-INF/MANIFEST.MF`
468 - `META-INF/*.SF`
469 - `META-INF/*.DSA`
470 - `META-INF/*.RSA`
471 - `META-INF/SIG-*`
472
473 Note that if such files are located in `META-INF` subdirectories, they
474 are not considered signature-related. Case-insensitive versions of these
475 filenames are reserved and will also not be signed.
476
477 Subsets of a JAR file can be signed by using the `java.security` API. A
478 signed JAR file is exactly the same as the original JAR file, except
479 that its manifest is updated and two additional files are added to the
480 `META-INF` directory: a signature file and a signature block file. When
481 jarsigner is not used, the signing program has to construct both the
482 signature file and the signature block file.
483
484 For every file entry signed in the signed JAR file, an individual
485 manifest entry is created for it as long as it does not already exist in
486 the manifest. Each manifest entry lists one or more digest attributes
487 and an optional [Magic attribute](#The_Magic_Attribute).
488
489 ### []{#Signature_File}Signature File
490
491 Each signer is represented by a signature file with extension `.SF`. The
492 major part of the file is similar to the manifest file. It consists of a
493 main section which includes information supplied by the signer but not
494 specific to any particular jar file entry. In addition to the
495 `Signature-Version` and `Created-By` attributes (see [Main
496 Attributes](#Main_Attributes)), the main section can also include the
497 following security attributes:
498
499 - x-Digest-Manifest-Main-Attributes (where x is the standard name of a
500 `java.security.MessageDigest` algorithm): The value of this
501 attribute is the digest value of the main attributes of the
502 manifest.
503 - x-Digest-Manifest (where x is the standard name of a
504 `java.security.MessageDigest` algorithm): The value of this
505 attribute is the digest value of the entire manifest.
506
507 The main section is followed by a list of individual entries whose names
508 must also be present in the manifest file. Each individual entry must
509 contain at least the digest of its corresponding entry in the manifest
510 file.
511
512 Paths or URLs appearing in the manifest file but not in the signature
513 file are not used in the calculation.
514
515 ### []{#Signature_Validation}Signature Validation
516
517 A successful JAR file verification occurs if the signature(s) are valid,
518 and none of the files that were in the JAR file when the signatures were
519 generated have been changed since then. JAR file verification involves
520 the following steps:
521
522 1. Verify the signature over the signature file when the manifest is
523 first parsed. For efficiency, this verification can be remembered.
524 Note that this verification only validates the signature directions
525 themselves, not the actual archive files.
526
527 2. If an `x-Digest-Manifest` attribute exists in the signature file,
528 verify the value against a digest calculated over the entire
529 manifest. If more than one `x-Digest-Manifest` attribute exists in
530 the signature file, verify that at least one of them matches the
531 calculated digest value.
532
533 3. If an `x-Digest-Manifest` attribute does not exist in the signature
534 file or none of the digest values calculated in the previous step
535 match, then a less optimized verification is performed:
536
537 1. If an `x-Digest-Manifest-Main-Attributes` entry exists in the
538 signature file, verify the value against a digest calculated
539 over the main attributes in the manifest file. If this
540 calculation fails, then JAR file verification fails. This
541 decision can be remembered for efficiency. If an
542 `x-Digest-Manifest-Main-Attributes` entry does not exist in the
543 signature file, its nonexistence does not affect JAR file
544 verification and the manifest main attributes are not verified.
545
546 2. Verify the digest value in each source file information section
547 in the signature file against a digest value calculated against
548 the corresponding entry in the manifest file. If any of the
549 digest values don't match, then JAR file verification fails.
550
551 One reason the digest value of the manifest file that is stored in
552 the `x-Digest-Manifest` attribute may not equal the digest value of
553 the current manifest file is that one or more files were added to
554 the JAR file (using the jar tool) after the signature (and thus the
555 signature file) was generated. When the jar tool is used to add
556 files, the manifest file is changed (sections are added to it for
557 the new files), but the signature file is not. A verification is
558 still considered successful if none of the files that were in the
559 JAR file when the signature was generated have been changed since
560 then, which is the case if the digest values in the non-header
561 sections of the signature file equal the digest values of the
562 corresponding sections in the manifest file.
563
564 4. For each entry in the manifest, verify the digest value in the
565 manifest file against a digest calculated over the actual data
566 referenced in the "Name:" attribute, which specifies either a
567 relative file path or URL. If any of the digest values don't match,
568 then JAR file verification fails.
569
570 Example manifest file:
571
572 Manifest-Version: 1.0
573 Created-By: 1.8.0 (Oracle Inc.)
574
575 Name: common/class1.class
576 SHA-256-Digest: (base64 representation of SHA-256 digest)
577
578 Name: common/class2.class
579 SHA1-Digest: (base64 representation of SHA1 digest)
580 SHA-256-Digest: (base64 representation of SHA-256 digest)
581
582 The corresponding signature file would be:
583
584 Signature-Version: 1.0
585 SHA-256-Digest-Manifest: (base64 representation of SHA-256 digest)
586 SHA-256-Digest-Manifest-Main-Attributes: (base64 representation of SHA-256 digest)
587
588 Name: common/class1.class
589 SHA-256-Digest: (base64 representation of SHA-256 digest)
590
591 Name: common/class2.class
592 SHA-256-Digest: (base64 representation of SHA-256 digest)
593
594 ### []{#The_Magic_Attribute}The Magic Attribute
595
596 Another requirement to validate the signature on a given manifest entry
597 is that the verifier understand the value or values of the Magic
598 key-pair value in that entry's manifest entry.
599
600 The Magic attribute is optional but it is required that a parser
601 understand the value of an entry's Magic key if it is verifying that
602 entry's signature.
603
604 The value or values of the Magic attribute are a set of comma-separated
605 context-specific strings. The spaces before and after the commas are
606 ignored. Case is ignored. The exact meaning of the magic attributes is
607 application specific. These values indicate how to compute the hash
608 value contained in the manifest entry, and are therefore crucial to the
609 proper verification of the signature. The keywords may be used for
610 dynamic or embedded content, multiple hashes for multilingual documents,
611 etc.
612
613 Here are two examples of the potential use of Magic attribute in the
614 manifest file:
615
616 Name: http://www.example-scripts.com/index#script1
617 SHA-256-Digest: (base64 representation of SHA-256 hash)
618 Magic: JavaScript, Dynamic
619
620 Name: http://www.example-tourist.com/guide.html
621 SHA-256-Digest: (base64 representation of SHA-256 hash)
622 SHA-256-Digest-French: (base64 representation of SHA-256 hash)
623 SHA-256-Digest-German: (base64 representation of SHA-256 hash)
624 Magic: Multilingual
625
626 In the first example, these Magic values may indicate that the result of
627 an http query is the script embedded in the document, as opposed to the
628 document itself, and also that the script is generated dynamically.
629 These two pieces of information indicate how to compute the hash value
630 against which to compare the manifest's digest value, thus comparing a
631 valid signature.
632
633 In the second example, the Magic value indicates that the document
634 retrieved may have been content-negotiated for a specific language, and
635 that the digest to verify against is dependent on which language the
636 document retrieved is written in.
637
638 []{#Digital_Signatures}Digital Signatures
639 -----------------------------------------
640
641 A digital signature is a signed version of the `.SF` signature file.
642 These are binary files not intended to be interpreted by humans.
643
644 Digital signature files have the same filenames as the .SF files but
645 different extensions. The extension varies depending on the type of
646 digital signature.
647
648 - `.RSA` (PKCS7 signature, SHA-256 + RSA)
649 - `.DSA` (PKCS7 signature, DSA)
650
651 Digital signature files for signature algorithms not listed above must
652 reside in the `META-INF` directory and have the prefix "`SIG-`". The
653 corresonding signature file (`.SF` file) must also have the same prefix.
654
655 For those formats that do not support external signed data, the file
656 shall consist of a signed copy of the `.SF` file. Thus some data may be
657 duplicated and a verifier should compare the two files.
658
659 Formats that support external data either reference the `.SF` file, or
660 perform calculations on it with implicit reference.
661
662 Each `.SF` file may have multiple digital signatures, but those
663 signatures should be generated by the same legal entity.
664
665 File name extensions may be 1 to 3 *alphanum* characters. Unrecognized
666 extensions are ignored.
667
668 []{#Notes_on_Manifest_and_Signature_Files}Notes on Manifest and Signature Files
669 -------------------------------------------------------------------------------
670
671 Following is a list of additional restrictions and rules that apply to
672 manifest and signature files.
673
674 - Before parsing:
675 - If the last character of the file is an EOF character (code 26),
676 the EOF is treated as whitespace. Two newlines are appended (one
677 for editors that don't put a newline at the end of the last
678 line, and one so that the grammar doesn't have to special-case
679 the last entry, which may not have a blank line after it).
680 - Attributes:
681 - In all cases for all sections, attributes which are not
682 understood are ignored.
683 - Attribute names are case insensitive. Programs which generate
684 manifest and signature files should use the cases shown in this
685 specification however.
686 - Attribute names cannot be repeated within a section.
687 - Versions:
688 - Manifest-Version and Signature-Version must be first, and in
689 exactly that case (so that they can be recognized easily as
690 magic strings). Other than that, the order of attributes within
691 a main section is not significant.
692 - Ordering:
693 - The order of individual manifest entries is not significant.
694 - The order of individual signature entries is not significant,
695 except that the digests that get signed are in that order.
696 - Line length:
697 - No line may be longer than 72 bytes (not characters), in its
698 UTF8-encoded form. If a value would make the initial line longer
699 than this, it should be continued on extra lines (each starting
700 with a single SPACE).
701 - Errors:
702 - If a file cannot be parsed according to this spec, a warning
703 should be output, and none of the signatures should be trusted.
704 - Limitations:
705 - Because header names cannot be continued, the maximum length of
706 a header name is 70 bytes (there must be a colon and a SPACE
707 after the name).
708 - NUL, CR, and LF can't be embedded in header values, and NUL, CR,
709 LF and ":" can't be embedded in header names.
710 - Implementations should support 65535-byte (not character) header
711 values, and 65535 headers per file. They might run out of
712 memory, but there should not be hard-coded limits below these
713 values.
714 - Signers:
715 - It is technically possible that different entities may use
716 different signing algorithms to share a single signature file.
717 This violates the standard, and the extra signature may be
718 ignored.
719 - Algorithms:
720 - No digest algorithm or signature algorithm is mandated by this
721 standard. However, at least one of MD5 and SHA1 digest algorithm
722 must be supported.
723
724 []{#JAR_Index}JAR Index
725 -----------------------
726
727 ### []{#Overview}Overview
728
729 Since 1.3, JarIndex is introduced to optimize the class searching
730 process of class loaders for network applications, especially applets.
731 Originally, an applet class loader uses a simple linear search algorithm
732 to search each element on its internal search path, which is constructed
733 from the "ARCHIVE" tag or the "Class-Path" main attribute. The class
734 loader downloads and opens each element in its search path, until the
735 class or resource is found. If the class loader tries to find a
736 nonexistent resource, then all the jar files within the application or
737 applet will have to be downloaded. For large network applications and
738 applets this could result in slow startup, sluggish response and wasted
739 network bandwidth. The JarIndex mechanism collects the contents of all
740 the jar files defined in an applet and stores the information in an
741 index file in the first jar file on the applet's class path. After the
742 first jar file is downloaded, the applet class loader will use the
743 collected content information for efficient downloading of jar files.
744
745 The existing `jar` tool is enhanced to be able to examine a list of jar
746 files and generate directory information as to which classes and
747 resources reside in which jar file. This directory information is stored
748 in a simple text file named `INDEX.LIST` in the `META-INF` directory of
749 the root jar file. When the classloader loads the root jar file, it
750 reads the `INDEX.LIST` file and uses it to construct a hash table of
751 mappings from file and package names to lists of jar file names. In
752 order to find a class or a resource, the class loader queries the
753 hashtable to find the proper jar file and then downloads it if
754 necessary.
755
756 Once the class loader finds a `INDEX.LIST` file in a particular jar
757 file, it always trusts the information listed in it. If a mapping is
758 found for a particular class, but the class loader fails to find it by
759 following the link, an unspecified Error or RuntimeException is thrown.
760 When this occurs, the application developer should rerun the `jar` tool
761 on the extension to get the right information into the index file.
762
763 To prevent adding too much space overhead to the application and to
764 speed up the construction of the in-memory hash table, the INDEX.LIST
765 file is kept as small as possible. For classes with non-null package
766 names, mappings are recorded at the package level. Normally one package
767 name is mapped to one jar file, but if a particular package spans more
768 than one jar file, then the mapped value of this package will be a list
769 of jar files. For resource files with non-empty directory prefixes,
770 mappings are also recorded at the directory level. Only for classes
771 with null package name, and resource files which reside in the root
772 directory, will the mapping be recorded at the individual file level.
773
774 ### []{#Index_File_Specification}Index File Specification
775
776 The `INDEX.LIST` file contains one or more sections each separated by a
777 single blank line. Each section defines the content of a particular jar
778 file, with a header defining the jar file path name, followed by a list
779 of package or file names, one per line. All the jar file paths are
780 relative to the code base of the root jar file. These path names are
781 resolved in the same way as the current extension mechanism does for
782 bundled extensions.
783
784 The UTF-8 encoding is used to support non ASCII characters in file or
785 package names in the index file.
786
787
788 #### Specification
789
790 ------------------ ---------------------------------------------------------------------
791 *index file:* *version-info blankline section\**
792 *version-info:* `JarIndex-Version:` *version-number*
793 *version-number:* *digit+{.digit+}\**
794 *section:* *body blankline*
795 *body:* *header name\**
796 *header:* *char+*`.jar` *newline*
797 *name:* *char+ newline*
798 *char:* *any valid Unicode character except* `NULL, CR` *and*`LF`
799 *blankline:* *newline newline*
800 *newline:* `CR LF | LF | CR` (*not followed by* `LF`)
801 *digit:* {`0-9`}
802 ------------------ ---------------------------------------------------------------------
803
804
805
806 The `INDEX.LIST` file is generated by running `jar -i.` See the
807 [jar](https://docs.oracle.com/javase/9/tools/jar.htm#JSWOR614) man page for more details.
808
809 ### []{#Backward_Compatibility}Backward Compatibility
810
811 The new class loading scheme is totally backward compatible with
812 applications developed on top of the current extension mechanism. When
813 the class loader loads the first jar file and an `INDEX.LIST` file is
814 found in the `META-INF` directory, it would construct the index hash
815 table and use the new loading scheme for the extension. Otherwise, the
816 class loader will simply use the original linear search algorithm.
817
818 []{#Service_Provider}Service Provider
819 -------------------------------------
820
821 ### []{#Service_Provider_Overview}Overview
822
823 Files in the `META-INF/services` directory are service provider
824 configuration files. A service is a well-known set of interfaces and
825 (usually abstract) classes. A service provider is a specific
826 implementation of a service. The classes in a provider typically
827 implement the interfaces and subclass the classes defined in the service
828 itself. Service providers may be installed in an implementation of the
829 Java platform in the form of extensions, that is, jar files placed into
830 any of the usual extension directories. Providers may also be made
831 available by adding them to the applet or application class path or by
832 some other platform-specific means.
833
834 A service is represented by an abstract class. A provider of a given
835 service contains one or more concrete classes that extend this service
836 class with data and code specific to the provider. This provider class
837 will typically not be the entire provider itself but rather a proxy that
838 contains enough information to decide whether the provider is able to
839 satisfy a particular request together with code that can create the
840 actual provider on demand. The details of provider classes tend to be
841 highly service-specific; no single class or interface could possibly
842 unify them, so no such class has been defined. The only requirement
843 enforced here is that provider classes must have a zero-argument
844 constructor so that they may be instantiated during lookup.
845
846 ### []{#Provider_Configuration_File}Provider-Configuration File
847
848 A service provider identifies itself by placing a provider-configuration
849 file in the resource directory `META-INF/services`. The file's name
850 should consist of the fully-qualified name of the abstract service
851 class. The file should contain a newline-separated list of unique
852 concrete provider-class names. Space and tab characters, as well as
853 blank lines, are ignored. The comment character is '\#' (0x23); on each
854 line all characters following the first comment character are ignored.
855 The file must be encoded in UTF-8.
856
857 ### []{#Example}Example
858
859 Suppose we have a service class named java.io.spi.CharCodec. It has two
860 abstract methods:
861
862 - `public abstract CharEncoder getEncoder(String encodingName);`
863 - `public abstract CharDecoder getDecoder(String encodingName);`
864
865 Each method returns an appropriate object or null if it cannot translate
866 the given encoding. Typical CharCodec providers will support more than
867 one encoding.
868
869 If sun.io.StandardCodec is a provider of the CharCodec service then its
870 jar file would contain the file
871 `META-INF/services/java.io.spi.CharCodec`. This file would contain the
872 single line:
873
874 sun.io.StandardCodec # Standard codecs for the platform
875
876 To locate an encoder for a given encoding name, the internal I/O code
877 would do something like this:
878
879 CharEncoder getEncoder(String encodingName) {
880 Iterator ps = Service.providers(CharCodec.class);
881 while (ps.hasNext()) {
882 CharCodec cc = (CharCodec)ps.next();
883 CharEncoder ce = cc.getEncoder(encodingName);
884 if (ce != null) return ce;
885 }
886 return null;
887 }
888
889 The provider-lookup mechanism always executes in the security context of
890 the caller. Trusted system code should typically invoke the methods in
891 this class from within a privileged security context.
892
893 []{#classpath}
894
895 Class-Path Attribute
896 --------------------
897
898 The manifest for an application can specify one or more relative URLs
899 referring to the JAR files and directories for other libraries that it
900 needs. These relative URLs will be treated relative to the code base
901 that the containing application was loaded from.
902
903 An application (or, more generally, JAR file) specifies the relative
904 URLs of the libraries that it needs via the manifest attribute
905 `Class-Path`. This attribute lists the URLs to search for
906 implementations of other libraries if they cannot be found on the host
907 Java Virtual Machine. These relative URLs may include JAR files
908 and directories for any libraries or resources needed by the
909 application. Relative URLs not ending with '/' are assumed to refer to
910 JAR files. For example,
911
912 ``` {style="MARGIN-LEFT: 40px"}
913 Class-Path: servlet.jar infobus.jar acme/beans.jar images/
914 ```
915
916 At most one `Class-Path` header may be specified in a JAR file's
917 manifest..
918
919 Currently, the URLs must be *relative* to the code base of the JAR file
920 for security reasons. Thus, remote optional packages will originate from
921 the same code base as the application.
922
923 Each relative URL is resolved against the code base that the containing
924 application or library was loaded from. If the resulting URL is invalid
925 or refers to a resource that cannot be found then it is ignored.
926
927 The resulting URLs are used to extend the class path for the
928 application, applet, or servlet by inserting the URLs in the class path
929 immediately following the URL of the containing JAR file. Any duplicate
930 URLs are omitted. For example, given the following class path:
931
932 ``` {style="MARGIN-LEFT: 40px"}
933 a.jar b.jar
934 ```
935
936 If `b.jar` contained the following `Class-Path` manifest attribute:
937
938 ``` {style="MARGIN-LEFT: 40px"}
939 Class-Path: x.jar a.jar
940 ```
941
942 Then the resulting application class path would be the following:
943
944 ``` {style="MARGIN-LEFT: 40px"}
945 a.jar b.jar x.jar
946 ```
947
948 Of course, if `x.jar` had dependencies of its own then these would be
949 added according to the same rules and so on for each subsequent URL. In
950 the actual implementation, JAR file dependencies are processed lazily so
951 that the JAR files are not actually opened until needed. []{#sealing}
952
953 Package Sealing
954 ---------------
955
956 JAR files and packages can be optionally *sealed*, so that an package
957 can enforce consistency within a version.
958
959 A package sealed within a JAR specifies that all classes defined in that
960 package must originate from the same JAR. Otherwise, a
961 `SecurityException` is thrown.
962
963 A sealed JAR specifies that all packages defined by that JAR are sealed
964 unless overridden specifically for a package.
965
966 A sealed package is specified via the manifest attribute, `Sealed`,
967 whose value is `true` or `false` (case irrelevant). For example,
968
969 Name: javax/servlet/internal/
970 Sealed: true
971
972
973 specifies that the `javax.servlet.internal` package is sealed, and that
974 all classes in that package must be loaded from the same JAR file.
975
976 If this attribute is missing, the package sealing attribute is that of
977 the containing JAR file.
978
979 A sealed JAR is specified via the same manifest header, `Sealed`, with
980 the value again of either `true` or `false`. For example,
981
982 Sealed: true
983
984
985 specifies that all packages in this archive are sealed unless explicitly
986 overridden for a particular package with the `Sealed` attribute in a
987 manifest entry.
988
989 If this attribute is missing, the JAR file is assumed to *not* be
990 sealed, for backwards compatibility. The system then defaults to
991 examining package headers for sealing information.
992
993 Package sealing is also important for security, because it restricts
994 access to package-protected members to only those classes defined in the
995 package that originated from the same JAR file.
996
997 The unnamed package is not sealable, so classes that are to be sealed
998 must be placed in their own packages.
999
1000 []{#API_Details}API Details
1001 ---------------------------
1002
1003 Package [java.util.jar](../../../api/java/util/jar/package-summary.html)
1004
1005 []{#See_Also}See Also
1006 ---------------------
1007
1008 Package
1009 [java.security](../../../api/java/security/package-summary.html)\
1010 Package [java.util.zip](../../../api/java/util/zip/package-summary.html)
1011
1012 ---------------------------------------
1013
1014 <meta charset="utf-8" />
1015
1016 *[Copyright](../../../legal/SMICopyright.html) © 1993, 2017, Oracle
1017 and/or its affiliates. All rights reserved.*