Asylo
trusted_application.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_PLATFORM_CORE_TRUSTED_APPLICATION_H_
20 #define ASYLO_PLATFORM_CORE_TRUSTED_APPLICATION_H_
21 
22 // Defines a high-level interface for constructing enclave applications.
23 
24 #include <string>
25 
26 #include "asylo/enclave.pb.h"
27 #include "asylo/platform/arch/include/trusted/entry_points.h"
28 #include "asylo/platform/core/trusted_global_state.h"
29 #include "asylo/util/status.h"
30 
31 namespace asylo {
32 
33 /// Abstract base class for trusted applications.
34 ///
35 /// To implement an enclave application, client code declares a
36 /// TrustedApplication and implements the entry points it wishes to handle. For
37 /// example:
38 ///
39 /// ```
40 /// class HelloWorld : public TrustedApplication {
41 /// public:
42 /// Status Initialize(const EnclaveConfig &config) override {
43 /// enc_untrusted_puts("Hello!");
44 /// return Status::OkStatus();
45 /// }
46 ///
47 /// Status Run(const EnclaveInput &input, EnclaveOutput *output) override {
48 /// enc_untrusted_puts("Running!");
49 /// return Status::OkStatus();
50 /// }
51 ///
52 /// Status Finalize(const EnclaveFinal &fini) override {
53 /// enc_untrusted_puts("Goodbye!");
54 /// return Status::OkStatus();
55 /// }
56 /// };
57 /// ```
58 ///
59 /// At startup, the runtime will call the user supplied function
60 /// BuildTrustedApplication and install the returned instance as the handler for
61 /// enclave entries events. For instance:
62 ///
63 /// ```
64 /// TrustedApplication *BuildTrustedApplication() {
65 /// return new HelloWorld;
66 /// }
67 /// ```
68 ///
69 /// Note that types derived from TrustedApplication must be trivially
70 /// destructible, and any such destructor will never be invoked by the runtime.
71 class TrustedApplication {
72  public:
73  /// An enumeration of possible enclave runtime states.
74  enum class State {
75  /// Enclave initialization has not started.
77  /// Asylo internals are initializing.
79  /// Asylo internals are initialized. User-defined initialization is
80  /// in-progress.
82  /// All initialization has completed. The enclave is running.
83  kRunning,
84  /// The enclave is finalizing.
86  /// The enclave has finalized.
87  kFinalized,
88  };
89 
90  /// \private
91  Status InitializeInternal(const EnclaveConfig &config);
92 
93  /// Implements enclave initialization entry-point.
94  ///
95  /// \param config The configuration used to initialize the enclave.
96  /// \return An OK status or an error if the enclave could not be initialized.
97  /// \anchor initialize
99  return Status::OkStatus();
100  }
101 
102  /// Implements enclave execution entry-point.
103  ///
104  /// \param input Message passed to determine behavior for the Run routine.
105  /// \param output Message passed back to the untrusted caller.
106  /// \return OK status or error
107  /// \anchor run
109  return Status::OkStatus();
110  }
111 
112  /// Implements enclave finalization behavior.
113  ///
114  /// \param final_input Message passed on enclave finalization.
115  /// \return OK status or error
116  /// \anchor finalize
118  return Status::OkStatus();
119  }
120 
121  /// Trivial destructor.
122  ///
123  /// Trivial destructor. Note that classes derived from of TrustedApplication
124  /// must not add a non-trivial destructor, as they will not be called by the
125  /// enclave runtime.
126  virtual ~TrustedApplication() = default;
127 
128  /// Returns the enclave state in a thread-safe manner.
129  State GetState() LOCKS_EXCLUDED(mutex_);
130 
131  private:
132  // Tracks the current enclave state.
133  State enclave_state_ GUARDED_BY(mutex_) = State::kUninitialized;
134  absl::Mutex mutex_;
135 
136  // Verifies the expected enclave state and sets a new one in thread-safe
137  // manner. Returns error if the verification fails.
138  asylo::Status VerifyAndSetState(const State &expected_state,
139  const State &new_state)
140  LOCKS_EXCLUDED(mutex_);
141 
142  // Sets the enclave state in thread-safe manner.
143  void SetState(const State &state) LOCKS_EXCLUDED(mutex_);
144 
145  friend int __asylo_user_init(const char *name, const char *config,
146  size_t config_len, char **output,
147  size_t *output_len);
148  friend int __asylo_user_run(const char *input, size_t input_len,
149  char **output, size_t *output_len);
150  friend int __asylo_user_fini(const char *input, size_t input_len,
151  char **output, size_t *output_len);
152  friend int __asylo_threading_donate();
153  friend int __asylo_handle_signal(const char *input, size_t input_len);
154 };
155 
156 /// User-supplied factory function for making a trusted application instance.
157 ///
158 /// \return A new TrustedApplication instance, or nullptr on failure.
159 /// \relates TrustedApplication
160 TrustedApplication *BuildTrustedApplication();
161 
162 /// Returns the trusted application instance.
163 ///
164 /// \return The enclave application instance or nullptr on failure.
165 /// \relates TrustedApplication
166 TrustedApplication *GetApplicationInstance();
167 
168 } // namespace asylo
169 
170 #endif // ASYLO_PLATFORM_CORE_TRUSTED_APPLICATION_H_
State
An enumeration of possible enclave runtime states.
Definition: trusted_application.h:74
friend int __asylo_handle_signal(const char *input, size_t input_len)
TrustedApplication * GetApplicationInstance()
Returns the trusted application instance.
friend int __asylo_threading_donate()
friend int __asylo_user_init(const char *name, const char *config, size_t config_len, char **output, size_t *output_len)
friend int __asylo_user_run(const char *input, size_t input_len, char **output, size_t *output_len)
virtual Status Run(const EnclaveInput &input, EnclaveOutput *output)
Implements enclave execution entry-point.
Definition: trusted_application.h:108
Enclave initialization has not started.
Definition: aes_gcm_siv.h:37
State GetState() LOCKS_EXCLUDED(mutex_)
Returns the enclave state in a thread-safe manner.
friend int __asylo_user_fini(const char *input, size_t input_len, char **output, size_t *output_len)
All initialization has completed. The enclave is running.
virtual ~TrustedApplication()=default
Trivial destructor.
virtual Status Finalize(const EnclaveFinal &final_input)
Implements enclave finalization behavior.
Definition: trusted_application.h:117
virtual Status Initialize(const EnclaveConfig &config)
Implements enclave initialization entry-point.
Definition: trusted_application.h:98
TrustedApplication * BuildTrustedApplication()
User-supplied factory function for making a trusted application instance.