Google Cloud Storage C++ Client  1.32.1
A C++ Client Library for Google Cloud Storage
hashing_options.h
Go to the documentation of this file.
1 // Copyright 2018 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_HASHING_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_HASHING_OPTIONS_H
17 
18 #include "google/cloud/storage/internal/complex_option.h"
19 #include "google/cloud/storage/version.h"
20 #include <string>
21 
22 namespace google {
23 namespace cloud {
24 namespace storage {
25 inline namespace STORAGE_CLIENT_NS {
26 /**
27  * Provide a pre-computed MD5 hash value.
28  *
29  * The application may be able to obtain a MD5 hash in some out-of-band way.
30  * For example, if the object was downloaded from some other cloud storage
31  * service, or because the application already queried the GCS object metadata.
32  * In these cases, providing the value to the client library improves the
33  * end-to-end data integrity verification.
34  *
35  * @see
36  * https://sigops.org/s/conferences/hotos/2021/papers/hotos21-s01-hochschild.pdf
37  */
39  : public internal::ComplexOption<MD5HashValue, std::string> {
40  using ComplexOption<MD5HashValue, std::string>::ComplexOption;
41  // GCC <= 7.0 does not use the inherited default constructor, redeclare it
42  // explicitly
43  MD5HashValue() = default;
44  static char const* name() { return "md5-hash-value"; }
45 };
46 
47 /**
48  * Compute the MD5 Hash of a string in the format preferred by GCS.
49  */
50 std::string ComputeMD5Hash(std::string const& payload);
51 
52 /**
53  * Disable or enable MD5 Hashing computations.
54  *
55  * By default MD5 hashes are disabled. To enable them use the
56  * `EnableMD5Hash()` helper function.
57  *
58  * @warning MD5 hashes are disabled by default, as they are computationally
59  * expensive, and CRC32C checksums provide enough data integrity protection
60  * for most applications. Disabling CRC32C checksums while MD5 hashes remain
61  * disabled exposes your application to data corruption. We recommend that all
62  * uploads to GCS and downloads from GCS use CRC32C checksums.
63  */
64 struct DisableMD5Hash : public internal::ComplexOption<DisableMD5Hash, bool> {
65  using ComplexOption<DisableMD5Hash, bool>::ComplexOption;
66  // GCC <= 7.0 does not use the inherited default constructor, redeclare it
67  // explicitly
69  static char const* name() { return "disable-md5-hash"; }
70 };
71 
72 /**
73  * Enable MD5 hashes in upload and download operations.
74  *
75  * Use this function where the option `DisableMD5Hash` is expected to enable MD5
76  * hashes.
77  */
78 inline DisableMD5Hash EnableMD5Hash() { return DisableMD5Hash(false); }
79 
80 /**
81  * Provide a pre-computed CRC32C checksum value.
82  *
83  * The application may be able to obtain a CRC32C checksum in some out-of-band
84  * way. For example, if the object was downloaded from some other cloud storage
85  * service, or because the application already queried the GCS object metadata.
86  * In these cases, providing the value to the client library improves the
87  * end-to-end data integrity verification.
88  *
89  * @see
90  * https://sigops.org/s/conferences/hotos/2021/papers/hotos21-s01-hochschild.pdf
91  */
93  : public internal::ComplexOption<Crc32cChecksumValue, std::string> {
94  using ComplexOption<Crc32cChecksumValue, std::string>::ComplexOption;
95  // GCC <= 7.0 does not use the inherited default constructor, redeclare it
96  // explicitly
97  Crc32cChecksumValue() = default;
98  static char const* name() { return "crc32c-checksum"; }
99 };
100 
101 /**
102  * Compute the CRC32C checksum of a string in the format preferred by GCS.
103  */
104 std::string ComputeCrc32cChecksum(std::string const& payload);
105 
106 /**
107  * Disable CRC32C checksum computations.
108  *
109  * By default the GCS client library computes CRC32C checksums in all upload and
110  * download operations. The application can use this option to disable the
111  * checksum computation.
112  *
113  * @warning MD5 hashes are disabled by default, as they are computationally
114  * expensive, and CRC32C checksums provide enough data integrity protection
115  * for most applications. Disabling CRC32C checksums while MD5 hashes remain
116  * disabled exposes your application to data corruption. We recommend that all
117  * uploads to GCS and downloads from GCS use CRC32C checksums.
118  */
120  : public internal::ComplexOption<DisableCrc32cChecksum, bool> {
121  using ComplexOption<DisableCrc32cChecksum, bool>::ComplexOption;
122  // GCC <= 7.0 does not use the inherited default constructor, redeclare it
123  // explicitly
125  static char const* name() { return "disable-crc32c-checksum"; }
126 };
127 
128 } // namespace STORAGE_CLIENT_NS
129 } // namespace storage
130 } // namespace cloud
131 } // namespace google
132 
133 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_HASHING_OPTIONS_H