| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Checksum Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="checksum">Checksum</h2> |
| <h3>Description</h3> |
| <p>Generates checksum for files. This task can also be used to perform checksum verifications.</p> |
| |
| <p>Note that many popular message digest functions—including MD5 and SHA-1—have been |
| broken recently. If you are going to use the task to create checksums used in an environment where |
| security is important, please take some time to investigate the algorithms offered by your JCE |
| provider. Note also that some JCE providers like the one by <a href="https://www.bouncycastle.org/" |
| target="_top">The Legion of the Bouncy Castle</a>, |
| the <a href="https://www.gnu.org/software/gnu-crypto/" target="_top">GNU Crypto project</a> |
| or <a href="https://jce.iaik.tugraz.at/sic/Products" target="_top">the Technical University Graz</a> |
| offer more digest algorithms than those built-in into your JDK.</p> |
| |
| <p>Warning: the case of the extension is that of the algorithm used. If you ask |
| for <samp>SHA1</samp>, you get a <samp>.SHA1</samp> extension; if you ask for <samp>sha1</samp>, you |
| get a file ending in <samp>.sha1</samp>. The Java Crypto Engines are case-insensitive in matching |
| algorithms, so choose a name to match your desired output extension, or set the <var>fileext</var> |
| attribute. The names of common hashing algorithms can be located on |
| the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest" |
| target="_top">Cryptography Architecture Standard Algorithm Name Documentation</a></p> |
| |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td>The file to generate checksum for.</td> |
| <td>Yes, unless at least one nested (filesystem-only) resource collection is specified.</td> |
| </tr> |
| <tr> |
| <td>todir</td> |
| <td>The root directory where checksums should be written.</td> |
| <td>No; by default, checksum files will be written to the same directory as the original |
| files. <em>since Apache Ant 1.6</em> |
| </td> |
| </tr> |
| <tr> |
| <td>algorithm</td> |
| <td>Specifies the algorithm to be used to compute the checksum. Please check |
| the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest" |
| target="_top">documentation</a> for available algorithm names, like <q>SHA-1</q> |
| or <q>SHA-512</q>. |
| </td> |
| <td>No; defaults to <q>MD5</q></td> |
| </tr> |
| <tr> |
| <td>provider</td> |
| <td>Specifies the provider of the algorithm.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>fileext</td> |
| <td>The generated checksum file's name will be the original filename with the <var>fileext</var> |
| added to it. |
| </td> |
| <td>No; defaults to a <q>.</q> and the algorithm name being used</td> |
| </tr> |
| <tr> |
| <td>property</td> |
| <td>This attribute can mean two different things, it depends on the presence of |
| the <var>verifyproperty</var> attribute.<br/><strong>If you don't set</strong> |
| the <var>verifyproperty</var> attribute, property specifies the name of the property to be set |
| with the generated checksum value.<br/><strong>If you set</strong> |
| the <var>verifyproperty</var> attribute, property specifies the checksum you expect to be |
| generated (the checksum itself, not a name of a property containing the checksum).<br/> This |
| cannot be specified when <var>fileext</var> is being used or when the number of files for |
| which checksums are to be generated is greater than 1. |
| </td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>pattern</td> |
| <td>Specifies the pattern to use as a pattern suitable |
| for <a href="https://docs.oracle.com/javase/8/docs/api/java/text/MessageFormat.html" |
| target="_top">MessageFormat</a> where <code>{0}</code> is replaced with the checksum |
| and <code>{1}</code> with the file name. <em>Since Ant 1.7.0</em><br/><em>Since Ant |
| 1.8.2</em> <code>{2}</code> is replaced by the path of the file relative to the checksum file |
| being written, <code>{3}</code> with the path of the file relative to the |
| project's <var>basedir</var> and <code>{4}</code> with the absolute path of the file.</td> |
| <td>No; default is <q>{0}</q></td> |
| </tr> |
| <tr> |
| <td>format</td> |
| <td>Specifies the pattern to use as one of a well-known format. Supported values are |
| <table> |
| <tr> |
| <th scope="col">name</th> |
| <th scope="col">pattern</th> |
| <th scope="col">description</th> |
| </tr> |
| <tr> |
| <td>CHECKSUM</td> |
| <td><code>{0}</code></td> |
| <td>only the checksum itself</td> |
| </tr> |
| <tr> |
| <td>MD5SUM</td> |
| <td><code>{0} *{1}</code></td> |
| <td>the format of GNU textutils <code>md5sum</code></td> |
| </tr> |
| <tr> |
| <td>SVF</td> |
| <td><code>MD5 ({1}) = {0}</code></td> |
| <td>the format of BSD <code>md5</code> command</td> |
| </tr> |
| </table> |
| <em>Since Ant 1.7.0</em></td> |
| <td>No; default is <q>CHECKSUM</q></td> |
| </tr> |
| <tr> |
| <td>totalproperty</td> |
| <td>If specified, this attribute specifies the name of the property that will hold a checksum of |
| all the checksums and file paths. The individual checksums and the relative paths to the files |
| within the resource collections in which they are defined will be used to compute this |
| checksum. (The file separators in the paths will be converted to <q>/</q> before computation |
| to ensure platform portability). <em>since Ant 1.6</em></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>forceoverwrite</td> |
| <td>Overwrite existing files even if the destination files are newer.</td> |
| <td>No; defaults to <q>no</q></td> |
| </tr> |
| <tr> |
| <td>verifyproperty</td> |
| <td>Specifies the name of the property to be set with <q>true</q> or <q>false</q> depending upon |
| whether the generated checksum matches the existing checksum. When this is set, the generated |
| checksum is not written to a file or property, but rather, the content of the file or property |
| is used to check against the generated checksum.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>readbuffersize</td> |
| <td>The size of the buffer (in bytes) to use when reading a file.</td> |
| <td>No; defaults to <q>8192</q>—you may get a better performance on big files if you |
| increase this value</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| |
| <h4>resource collections</h4> |
| <p><a href="../Types/resources.html#collection">Resource collections</a> are used to select files |
| for which checksums should be generated.</p> |
| |
| <h3>Examples</h3> |
| |
| <p><strong>Example 1</strong></p> |
| <p>Generate a MD5 checksum for <samp>foo.bar</samp> and store the checksum in the destination |
| file <samp>foo.bar.MD5</samp>. <samp>foo.bar.MD5</samp> is overwritten only if <samp>foo.bar</samp> |
| is newer than itself.</p> |
| <pre><checksum file="foo.bar"/></pre> |
| |
| <p><strong>Example 2</strong></p> |
| <p>Generate a MD5 checksum for <samp>foo.bar</samp> and store the checksum |
| in <samp>foo.bar.MD5</samp>. If <samp>foo.bar.MD5</samp> already exists, it is overwritten.</p> |
| <pre><checksum file="foo.bar" forceOverwrite="yes"/></pre> |
| |
| <p><strong>Example 3</strong></p> |
| <p>Generate a MD5 checksum for <samp>foo.bar</samp> and store it in the project |
| property <code>foobarMD5</code>.</p> |
| <pre><checksum file="foo.bar" property="foobarMD5"/></pre> |
| |
| <p><strong>Example 4</strong></p> |
| <p>Generate a MD5 checksum for <samp>foo.bar</samp>, compare it against <samp>foo.bar.MD5</samp> and |
| set <code>isMD5ok</code> to either <q>true</q> or <q>false</q>, depending upon the result.</p> |
| <pre><checksum file="foo.bar" verifyProperty="isMD5ok"/></pre> |
| |
| <p><strong>Example 5</strong></p> |
| <p>Generate a SHA-512 checksum for <samp>foo.bar</samp> and store the checksum in the destination |
| file <samp>foo.bar.asc</samp>. <samp>foo.bar.asc</samp> is overwritten only if <samp>foo.bar</samp> |
| is newer than itself.</p> |
| <pre><checksum file="foo.bar" algorithm="SHA-512" fileext="asc"/></pre> |
| |
| <p><strong>Example 6</strong></p> |
| <p>Generate a MD5 checksum for <samp>foo.bar</samp>, compare it against the value of the |
| property <code>md5</code>, and set <code>isEqual</code> to either <q>true</q> or <q>false</q>, |
| depending upon the result.</p> |
| <pre><checksum file="foo.bar" property="${md5}" verifyProperty="isEqual"/></pre> |
| |
| <p><strong>Example 7</strong></p> |
| <p>Just like Example 1, but generates a <samp>.MD5</samp> file for every file that begins with the |
| name <samp>foo</samp>.</p> |
| <pre> |
| <checksum> |
| <fileset dir="."> |
| <include name="foo*"/> |
| </fileset> |
| </checksum></pre> |
| |
| <p><strong>Example 8</strong></p> |
| <p>Just like Example 4, but only sets <code>isChecksumEqual</code> to <q>true</q>, if the checksum |
| matches—it will never be set to <q>false</q>. This example demonstrates use with |
| the <code>condition</code> task.</p> |
| <pre> |
| <condition property="isChecksumEqual"> |
| <checksum> |
| <fileset dir="."> |
| <include name="foo.bar"/> |
| </fileset> |
| </checksum> |
| </condition></pre> |
| |
| <h3>Note</h3> |
| <p>When working with more than one file, if condition and/or <var>verifyproperty</var> is used, the |
| result will be true only if the checksums matched correctly for all files being considered.</p> |
| |
| </body> |
| </html> |