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