Asylo
sgx_local_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_SGX_SGX_LOCAL_SECRET_SEALER_H_
20 #define ASYLO_IDENTITY_SGX_SGX_LOCAL_SECRET_SEALER_H_
21 
22 #include <memory>
23 
24 #include "asylo/crypto/aes_gcm_siv.h"
25 #include "asylo/crypto/util/byte_container_view.h"
26 #include "asylo/identity/identity.pb.h"
27 #include "asylo/identity/secret_sealer.h"
28 #include "asylo/identity/sgx/code_identity.pb.h"
29 #include "asylo/identity/util/bit_vector_128.pb.h"
30 #include "asylo/identity/util/sha256_hash.pb.h"
31 #include "asylo/util/cleansing_types.h"
32 #include "asylo/util/status.h"
33 
34 namespace asylo {
35 
36 /// An implementation of the SecretSealer abstract interface that binds the
37 /// secrets to the enclave identity on a local machine. The secrets sealed by
38 /// this sealer can only be unsealed on the same machine.
39 ///
40 /// The SgxLocalSecretSealer can be configured to seal secrets either to
41 /// MRENCLAVE or MRSIGNER. The SgxLocalSecretSealer class provides two factory
42 /// methods--one that creates an SgxLocalSecretSealer configured to seal secrets
43 /// to MRENCLAVE and another that creates an SgxLocalSecretSealer configured to
44 /// seal secrets to MRSIGNER. In the MRENCLAVE-sealing mode, the default
45 /// SealedSecretHeader generated by the sealer binds the secrets to the
46 /// MRENCLAVE portion of the enclave's identity. In the MRSIGNER mode, the
47 /// default SealedSecretHeader generated by the sealer binds the secrets to the
48 /// MRSIGNER portion of the enclave's identity. In either mode, the sealed
49 /// secret is bound to all bits of MISCSELECT, and all security-sensitive bits
50 /// of ATTRIBUTES, as defined in secs_attributes.h.
51 ///
52 /// Note that the SealedSecretHeader provided to the Seal() method also controls
53 /// the cipher suite used for sealing the secret. The default setting of this
54 /// field (as populated by SetDefaultHeader() ) is subject to change. As a
55 /// result, users must not make any assumptions about the default cipher suite.
56 /// If they wish to use a specific cipher suite, they must manually verify or
57 /// override the cipher suite set by the SetDefaultHeader() method.
58 ///
59 /// Sample usage for Seal():
60 /// ```
61 /// std::unique_ptr<SgxLocalSecretSealer> sealer = CreateMrsignerSealer();
62 ///
63 /// SealedSecretHeader header;
64 /// // Fill out the portions of the header that must be set by the client.
65 /// header.set_secret_name("my name");
66 /// header.set_secret_version("my version");
67 /// header.set_secret_purpose("my purpose");
68 /// // secret_handling_policy is a client-specific string, which, for example,
69 /// could be a serialized proto.
70 /// string secret_handling_policy = ...
71 /// header.set_secret_handling_policy(secret_handling_policy);
72 /// sealer->SetDefaultHeader(&header);
73 ///
74 /// // Override fields in the default header, if desired.
75 /// ...
76 ///
77 /// // Generate the secret to be sealed.
78 /// std::vector<uint8_t, CleansingAllocator> secret = ...;
79 ///
80 /// // Generate the additional authenticated data to be tied to the secret.
81 /// string additional_authenticated_data;
82 /// addtional_authenticated_data = ...
83 ///
84 /// // Seal the secret and the additional authenticated data.
85 /// SealedSecret sealed_secret;
86 /// Status status = sealer->Seal(header, additional_authenticated_data,
87 /// secret, &sealed_secret);
88 /// ```
89 ///
90 /// Sample usage for Unseal():
91 /// ```
92 /// std::unique_ptr<SgxLocalSecretSealer> sealer = CreateMrsignerSealer();
93 /// SealedSecret sealed_secret;
94 /// ...
95 /// sealed_secret.ParseFromString(...);
96 ///
97 /// std::vector<uint8_t, CleansingAllocator<uint8_t>> secret;
98 /// ASYLO_RETURN_IF_ERROR(sealer->Unseal(sealed_secret, secret));
99 /// // secret now holds the unsealed secret. The policy and
100 /// // additional_authenticated_data in the sealed_secret are now
101 /// // authenticated.
102 /// ```
103 ///
104 /// It should be noted that the SgxLocalSecretSealer's configuration only
105 /// affects the default header generated by the sealer. Users can override the
106 /// generated default header. A sealer in either MRENCLAVE or MRSIGNER
107 /// configuration can unseal secrets that are sealed by a sealer in either
108 /// configuration.
110  public:
111  /// Creates an SgxLocalSecretSealer that seals secrets to the MRENCLAVE part
112  /// of the enclave code identity.
113  ///
114  /// \return A smart pointer that owns the created sealer.
116 
117  /// Creates an SgxLocalSecretSealer that seals secrets to the MRSIGNER part of
118  /// the enclave identity.
119  ///
120  /// \return A smart pointer that owns the created sealer.
122 
123  SgxLocalSecretSealer(const SgxLocalSecretSealer &other) = delete;
124  virtual ~SgxLocalSecretSealer() = default;
125 
126  SgxLocalSecretSealer &operator=(const SgxLocalSecretSealer &other) = delete;
127 
128  // From SecretSealer interface.
129  SealingRootType RootType() const override;
130  std::string RootName() const override;
131  std::vector<EnclaveIdentityExpectation> RootAcl() const override;
137  CleansingVector<uint8_t> *secret) override;
138 
139  private:
140  // Maximum size (in bytes) of each protected message (including authenticated
141  // data). A protected message may not be larger than 32MB.
142  //
143  // A size-limit of 32MiB (2^25 bytes) allows the cryptor to safely encrypt
144  // 2^48 messages (see https://cyber.biu.ac.il/aes-gcm-siv/). On a 4GHz
145  // single-threaded Intel processor, assuming 1 byte/cycle AES-GCM processing
146  // bandwidth, this yields a key-lifetime of over 2^16 years, if the enclave
147  // did nothing but execute seal/unseal operations 24/7. On a 256-threaded
148  // machine, the key lifetime would reduce to ~256 years.
149  static constexpr size_t kMaxAesGcmSivMessageSize = (1 << 25);
150 
151  // Instantiates LocalSecretSealer that sets client_acl in the default sealed
152  // secret header per |default_client_acl|.
153  SgxLocalSecretSealer(const sgx::CodeIdentityExpectation &default_client_acl);
154 
155  // Cryptor to perform AEAD operations.
156  std::unique_ptr<AesGcmSivCryptor> cryptor_;
157 
158  // The default client ACL for this SecretSealer.
159  sgx::CodeIdentityExpectation default_client_acl_;
160 };
161 
162 } // namespace asylo
163 
164 #endif // ASYLO_IDENTITY_SGX_SGX_LOCAL_SECRET_SEALER_H_
Status SetDefaultHeader(SealedSecretHeader *header) const override
Generates the default sealed-secret header based on the configuration of the SecretSealer and writes ...
std::vector< EnclaveIdentityExpectation > RootAcl() const override
Gets the sealing root ACL of this SecretSealer.
Status Unseal(const SealedSecret &sealed_secret, CleansingVector< uint8_t > *secret) override
Unseals the sealed_secret and writes it to secret.
Status Seal(const SealedSecretHeader &header, ByteContainerView additional_authenticated_data, ByteContainerView secret, SealedSecret *sealed_secret) override
Seals the input per the header specification.
static std::unique_ptr< SgxLocalSecretSealer > CreateMrenclaveSecretSealer()
Creates an SgxLocalSecretSealer that seals secrets to the MRENCLAVE part of the enclave code identity...
virtual ~SgxLocalSecretSealer()=default
SgxLocalSecretSealer & operator=(const SgxLocalSecretSealer &other)=delete
An implementation of the SecretSealer abstract interface that binds the secrets to the enclave identi...
Definition: sgx_local_secret_sealer.h:109
SgxLocalSecretSealer(const SgxLocalSecretSealer &other)=delete
Definition: aes_gcm_siv.h:37
SealingRootType RootType() const override
Gets the sealing root type of this SecretSealer.
static std::unique_ptr< SgxLocalSecretSealer > CreateMrsignerSecretSealer()
Creates an SgxLocalSecretSealer that seals secrets to the MRSIGNER part of the enclave identity...
std::string RootName() const override
Gets the sealing root name of this SecretSealer.