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) &copy; 1993, 2017, Oracle
1017 and/or its affiliates. All rights reserved.*