Asylo
secret_sealer.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2017 Asylo authors
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 
19 #ifndef ASYLO_IDENTITY_SEALING_SECRET_SEALER_H_
20 #define ASYLO_IDENTITY_SEALING_SECRET_SEALER_H_
21 
22 #include <cstdint>
23 #include <string>
24 #include <vector>
25 
26 #include "asylo/crypto/util/byte_container_view.h"
27 #include "asylo/identity/identity.pb.h"
28 #include "asylo/identity/sealing/sealed_secret.pb.h"
29 #include "asylo/platform/common/static_map.h"
30 #include "asylo/util/cleansing_types.h"
31 #include "asylo/util/status.h"
32 #include "asylo/util/statusor.h"
33 
34 namespace asylo {
35 
36 class SecretSealer {
37  public:
38  SecretSealer() = default;
39  virtual ~SecretSealer() = default;
40 
41  /// Gets the sealing root type of this SecretSealer.
42  ///
43  /// \return The sealing root type of this class.
44  virtual SealingRootType RootType() const = 0;
45 
46  /// Gets the sealing root name of this SecretSealer.
47  ///
48  /// \return The sealing root name of this class.
49  virtual std::string RootName() const = 0;
50 
51  /// Gets the sealing root ACL of this SecretSealer.
52  ///
53  /// \return The sealing root ACL of this object.
54  virtual std::vector<EnclaveIdentityExpectation> RootAcl() const = 0;
55 
56  /// Generates the default sealed-secret header based on the configuration of
57  /// the SecretSealer and writes it to `header`.
58  ///
59  /// \param[out] header The destination for the default SealedSecretHeader
60  /// value.
61  /// \return A non-OK status if a default cannot be set.
63 
64  /// Gets the maximum message size (in bytes) that can be sealed according to
65  /// the cipher-suite configuration recorded in `header`.
66  ///
67  /// The user is expected to call this before calling Seal() to ensure that
68  /// they have chunked their messages correctly. The maximum message sizes of
69  /// supported cipher-suites are as follows:
70  /// - AES-GCM-SIV supports a maximum message size of 32 MiB
71  ///
72  /// \param header The associated header to determine the maximum message size.
73  /// \return The maximum message size that can be encrypted based on the
74  /// cipher-suite configuration in header, or a non-OK status if the
75  // cipher-suite configuration is not supported.
77  const SealedSecretHeader &header) const = 0;
78 
79  /// Gets the maximum number of messages that can safely be sealed according to
80  /// the cipher-suite configuration recorded in `header`.
81  ///
82  /// The user is responsible for following these guidelines. The secret sealer
83  /// will not check the number of secrets sealed. The maximum number of sealed
84  /// messages of supported cipher-suites are as follows:
85  /// - AES-GCM-SIV can safely seal 2 ^ 48 messages
86  ///
87  /// \param header The associated header to determine the maximum number of
88  /// sealed messages.
89  /// \return The maximum number of messages that can be sealed based on the
90  /// cipher-suite configuration in header, or a non-OK status if the
91  /// cipher-suite configuration is not supported.
93  const SealedSecretHeader &header) const = 0;
94 
95  /// Seals the input per the header specification.
96  ///
97  /// The `header` must have its `secret_name`, `secret_version` and
98  /// `secret_purpose` fields populated. If any of the remaining fields in the
99  /// `header` are populated, then they must be compatible with the underlying
100  /// sealing root.
101  ///
102  /// \param header The metadata to guide the sealing.
103  /// \param additional_authenticated_data Unencrypted data that is bundled with
104  /// the sealed secret.
105  /// \param secret The data to encrypt and seal.
106  /// \param[out] sealed_secret The output sealed secret.
107  /// \return A non-OK status if sealing fails.
108  virtual Status Seal(const SealedSecretHeader &header,
112 
113  /// Unseals the `sealed_secret` and writes it to `secret`.
114  ///
115  /// \param sealed_secret The input secret to unseal.
116  /// \param[out] secret The destination for the unsealed secret.
117  /// \return A non-OK Status if unsealing fails.
118  virtual Status Unseal(const SealedSecret &sealed_secret,
120 
121  /// Re-seals an already sealed secret to a new header.
122  ///
123  /// The net effect of calling this method is same as unsealing the secret and
124  /// then sealing it to the new header, and that is exactly how this method is
125  /// implemented by the base class. A derived class of SecretSealer may choose
126  /// to further optimize this method.
127  ///
128  /// \param old_sealed_secret The sealed secret to re-seal.
129  /// \param new_header The metadata to guide the re-sealing.
130  /// \param[out] new_sealed_secret The output sealed secret.
131  /// \return A non-OK status if re-sealing fails.
135 
136  /// Combines the specified sealing root type and sealing root name
137  /// to form a string. The combined string uniquely identifies the SecretSealer
138  /// responsible for handling secrets associated with the particular
139  /// combination of root-type `type` and root-name `name`.
140  ///
141  /// \param type The root type for sealing (e.g., from RootType()).
142  /// \param name The root name for sealing (e.g., from RootName()).
143  /// \return An object that represents a result string, or a failure status.
145  const std::string &name);
146 };
147 
148 /// \cond Internal
149 template <>
150 struct Namer<SecretSealer> {
151  std::string operator()(const SecretSealer &sealer) {
152  return SecretSealer::GenerateSealerId(sealer.RootType(), sealer.RootName())
153  .value();
154  }
155 };
156 
157 DEFINE_STATIC_MAP_OF_BASE_TYPE(SecretSealerMap, SecretSealer)
158 /// \endcond
159 
160 } // namespace asylo
161 
162 #endif // ASYLO_IDENTITY_SEALING_SECRET_SEALER_H_
virtual ~SecretSealer()=default
virtual Status Unseal(const SealedSecret &sealed_secret, CleansingVector< uint8_t > *secret)=0
Unseals the sealed_secret and writes it to secret.
virtual StatusOr< size_t > MaxMessageSize(const SealedSecretHeader &header) const =0
Gets the maximum message size (in bytes) that can be sealed according to the cipher-suite configurati...
SecretSealer()=default
virtual Status Seal(const SealedSecretHeader &header, ByteContainerView additional_authenticated_data, ByteContainerView secret, SealedSecret *sealed_secret)=0
Seals the input per the header specification.
virtual std::string RootName() const =0
Gets the sealing root name of this SecretSealer.
virtual std::vector< EnclaveIdentityExpectation > RootAcl() const =0
Gets the sealing root ACL of this SecretSealer.
virtual StatusOr< uint64_t > MaxSealedMessages(const SealedSecretHeader &header) const =0
Gets the maximum number of messages that can safely be sealed according to the cipher-suite configura...
Definition: secret_sealer.h:36
virtual Status SetDefaultHeader(SealedSecretHeader *header) const =0
Generates the default sealed-secret header based on the configuration of the SecretSealer and writes ...
virtual SealingRootType RootType() const =0
Gets the sealing root type of this SecretSealer.
virtual Status Reseal(const SealedSecret &old_sealed_secret, const SealedSecretHeader &new_header, SealedSecret *new_sealed_secret)
Re-seals an already sealed secret to a new header.
static StatusOr< std::string > GenerateSealerId(SealingRootType type, const std::string &name)
Combines the specified sealing root type and sealing root name to form a string.