1 // Copyright 2019, 2020 OCI Contributors 2 // Copyright 2017 Docker, Inc. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // https://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 16 // Package digest provides a generalized type to opaquely represent message 17 // digests and their operations within the registry. The Digest type is 18 // designed to serve as a flexible identifier in a content-addressable system. 19 // More importantly, it provides tools and wrappers to work with 20 // hash.Hash-based digests with little effort. 21 // 22 // Basics 23 // 24 // The format of a digest is simply a string with two parts, dubbed the 25 // "algorithm" and the "digest", separated by a colon: 26 // 27 // <algorithm>:<digest> 28 // 29 // An example of a sha256 digest representation follows: 30 // 31 // sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc 32 // 33 // The "algorithm" portion defines both the hashing algorithm used to calculate 34 // the digest and the encoding of the resulting digest, which defaults to "hex" 35 // if not otherwise specified. Currently, all supported algorithms have their 36 // digests encoded in hex strings. 37 // 38 // In the example above, the string "sha256" is the algorithm and the hex bytes 39 // are the "digest". 40 // 41 // Because the Digest type is simply a string, once a valid Digest is 42 // obtained, comparisons are cheap, quick and simple to express with the 43 // standard equality operator. 44 // 45 // Verification 46 // 47 // The main benefit of using the Digest type is simple verification against a 48 // given digest. The Verifier interface, modeled after the stdlib hash.Hash 49 // interface, provides a common write sink for digest verification. After 50 // writing is complete, calling the Verifier.Verified method will indicate 51 // whether or not the stream of bytes matches the target digest. 52 // 53 // Missing Features 54 // 55 // In addition to the above, we intend to add the following features to this 56 // package: 57 // 58 // 1. A Digester type that supports write sink digest calculation. 59 // 60 // 2. Suspend and resume of ongoing digest calculations to support efficient digest verification in the registry. 61 // 62 package digest 63