Asylo
aead_cryptor.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2018 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_CRYPTO_AEAD_CRYPTOR_H_
20 #define ASYLO_CRYPTO_AEAD_CRYPTOR_H_
21 
22 #include <cstdint>
23 #include <memory>
24 
25 #include "absl/types/span.h"
26 #include "asylo/crypto/aead_key.h"
27 #include "asylo/crypto/algorithms.pb.h"
28 #include "asylo/crypto/nonce_generator_interface.h"
29 #include "asylo/crypto/util/byte_container_view.h"
30 #include "asylo/util/statusor.h"
31 
32 namespace asylo {
33 namespace experimental {
34 
35 /// An AEAD cryptor that provides Seal() and Open() functionality. Currently
36 /// supported configurations:
37 /// * AES-GCM-128 and AES-GCM-256 with 96-bit random nonces.
38 /// * AES-GCM-SIV-128 and AES-GCM-SIV-256 with 96-bit random nonces. (For
39 /// information on AES-GCM-SIV see https://cyber.biu.ac.il/aes-gcm-siv/)
40 class AeadCryptor {
41  public:
42  /// Creates a cryptor that uses AES-GCM for Seal() and Open(), and generates
43  /// random 96-bit nonces for use in Seal().
44  ///
45  /// \param key The underlying key used for encryption and decryption.
46  /// \return A pointer to the created cryptor, or a non-OK Status if creation
47  /// failed.
50 
51  /// Creates a cryptor that uses AES-GCM-SIV for Seal() and Open(), and
52  /// generates random 96-bit nonces for use in Seal().
53  ///
54  /// \param key The underlying key used for encryption and decryption.
55  /// \return A pointer to the created cryptor, or a non-OK Status if creation
56  /// failed.
59 
60  /// Gets the maximum size of a message that may be sealed successfully with a
61  /// cryptor that uses `scheme`.
62  ///
63  /// \param scheme The associated AeadScheme.
64  /// \return The maximum message size that may be sealed successfully, or a
65  /// non-OK Status if `scheme` is unsupported.
67 
68  /// Gets the maximum number of messages that may be sealed safely with a
69  /// cryptor that uses `scheme`.
70  ///
71  /// \param scheme The associated AeadScheme.
72  /// \return The maximum number of messages that may be sealed safely, or a
73  /// non-OK Status if `scheme` is unsupported.
75 
76  /// Gets the maximum size of a message that may be sealed successfully.
77  ///
78  /// \return The maximum message size that this cryptor will seal successfully.
79  size_t MaxMessageSize() const;
80 
81  /// Gets the maximum number of messages that may be sealed successfully.
82  ///
83  /// \return The maximum number of messages that this cryptor will seal
84  /// successfully.
85  uint64_t MaxSealedMessages() const;
86 
87  /// Gets the max overhead of Seal().
88  ///
89  /// \return The maximum space overhead of Seal().
90  size_t MaxSealOverhead() const;
91 
92  /// Gets the nonce size.
93  ///
94  /// \return The nonce size.
95  size_t NonceSize() const;
96 
97  /// Implements the AEAD Seal operation.
98  ///
99  /// The nonce used is returned through `nonce` and the authenticated
100  /// ciphertext is written to `ciphertext`. `plaintext.size()` must be less
101  /// than or equal to MaxMessageSize(). `nonce.size()` must be greater than or
102  /// equal to the value returned by NonceSize(). `ciphertext.size()` must be
103  /// greater than or equal to `plaintext.size()` + MaxSealOverhead().
104  /// `ciphertext` is not resized, but its final size is returned through
105  /// `ciphertext_size`. Seal() will succeed at most MaxSealedMessages() times.
106  ///
107  /// \param plaintext The secret that will be sealed.
108  /// \param associated_data The authenticated data for the Seal() operation.
109  /// \param[out] nonce The generated nonce.
110  /// \param[out] ciphertext The sealed ciphertext of `plaintext`.
111  /// \param[out] ciphertext_size The size of `ciphertext`.
112  /// \return The resulting status of the Seal() operation.
116 
117  /// Implements the AEAD Open operation.
118  ///
119  /// `nonce.size()` must be greater than or equal to the value returned by
120  /// NonceSize(). `plaintext` is not resized, but its final size is returned
121  /// through `plaintext_size`. To ascertain that `plaintext` is not smaller
122  /// than is necessary for Open(), `plaintext.size()` should be greater than or
123  /// equal to `ciphertext.size()`.
124  ///
125  /// \param ciphertext The sealed ciphertext.
126  /// \param associated_data The authenticated data for the Open() operation.
127  /// \param nonce The nonce used to seal the ciphertext.
128  /// \param[out] plaintext The unsealed ciphertext.
129  /// \param[out] plaintext_size The size of the plaintext.
130  /// \return The resulting status of the Open() operation.
134 
135  private:
136  AeadCryptor(std::unique_ptr<AeadKey> key, size_t max_message_size,
137  uint64_t max_sealed_messages,
138  std::unique_ptr<NonceGeneratorInterface> nonce_generator);
139 
140  // The AeadKey used for Seal() and Open().
141  const std::unique_ptr<AeadKey> key_;
142 
143  // The maximum size of a message passed in for Seal().
144  const size_t max_message_size_;
145 
146  // The maximum number of messages that may be sealed successfully.
147  const uint64_t max_sealed_messages_;
148 
149  // The nonce generator used to generate nonces for Seal().
150  const std::unique_ptr<NonceGeneratorInterface> nonce_generator_;
151 
152  // The number messages that have been sealed successfully.
153  size_t number_of_sealed_messages_;
154 };
155 
156 } // namespace experimental
157 } // namespace asylo
158 
159 #endif // ASYLO_CRYPTO_AEAD_CRYPTOR_H_
An AEAD cryptor that provides Seal() and Open() functionality.
Definition: aead_cryptor.h:40
static StatusOr< uint64_t > MaxSealedMessages(AeadScheme scheme)
Gets the maximum number of messages that may be sealed safely with a cryptor that uses scheme...
size_t MaxSealOverhead() const
Gets the max overhead of Seal().
static StatusOr< std::unique_ptr< AeadCryptor > > CreateAesGcmSivCryptor(ByteContainerView key)
Creates a cryptor that uses AES-GCM-SIV for Seal() and Open(), and generates random 96-bit nonces for...
static StatusOr< std::unique_ptr< AeadCryptor > > CreateAesGcmCryptor(ByteContainerView key)
Creates a cryptor that uses AES-GCM for Seal() and Open(), and generates random 96-bit nonces for use...
uint64_t MaxSealedMessages() const
Gets the maximum number of messages that may be sealed successfully.
static StatusOr< size_t > MaxMessageSize(AeadScheme scheme)
Gets the maximum size of a message that may be sealed successfully with a cryptor that uses scheme...
Status Open(ByteContainerView ciphertext, ByteContainerView associated_data, ByteContainerView nonce, absl::Span< uint8_t > plaintext, size_t *plaintext_size)
Implements the AEAD Open operation.
size_t NonceSize() const
Gets the nonce size.
Definition: aead_cryptor.h:32
size_t MaxMessageSize() const
Gets the maximum size of a message that may be sealed successfully.
Definition: aead_cryptor.h:33
Status Seal(ByteContainerView plaintext, ByteContainerView associated_data, absl::Span< uint8_t > nonce, absl::Span< uint8_t > ciphertext, size_t *ciphertext_size)
Implements the AEAD Seal operation.