1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 #pragma once 16 17 #include <string_view> 18 19 #include "pw_stream/stream.h" 20 #include "pw_tls_client/options.h" 21 #include "pw_tls_client/status.h" 22 23 // The backend shall provide the following header that implements a 24 // backend::SessionImplementation type. 25 #include "pw_tls_client_backends/backend_types.h" 26 27 namespace pw::tls_client { 28 29 // Session provides APIs for performing TLS communication. 30 class Session : public stream::NonSeekableReaderWriter { 31 public: 32 Session() = delete; 33 34 Session(const Session&) = delete; 35 Session& operator=(const Session&) = delete; 36 37 // Resources allocated during Session::Create() will be released in the 38 // destructor. For example, backend may choose to allocate Session from a pool 39 // during Session::Create() and returns it in the destructor. 40 // 41 // Close() will be called if the Session is open. Since Close() returns a 42 // pw::Status which cannot be forwarded from a destructor for callers to 43 // check. Backend shall assert check that it is OkStatus(). 44 ~Session() override; 45 46 // Starts a TLS connection. The backend performs TLS handshaking and 47 // certificate verification/revocation/expiration check. 48 // 49 // Calling Open() on an already opened Session returns error. 50 Status Open(); 51 52 // Closes a TLS connection. The backend sends shutdown notification to the 53 // server. Note that the shutdown notification is part of the TLS protocol. 54 // Nothing is done to the underlying transport used to create this Session. 55 // The closing of the underlying transport is managed by the users of this 56 // class. Calling Close() on an unopened Session returns error. 57 Status Close(); 58 59 // If Open()/Close()/Read()/Write() fails, the method returns a more detailed 60 // code indicating the last error. See definition of TLSStatus in status.h. 61 // The backend is responsible for mapping TLS library errors into the ones 62 // defined in TLSStatus. 63 TLSStatus GetLastTLSStatus(); 64 65 // Factory method for creating an instance of Session according to the given 66 // options. Backend allocates and initializes library specific data structures 67 // (implmented in |session_impl_|) for operating as a TLS client. 68 // 69 // The client remains inactive until the call of Open(). 70 static Result<Session*> Create(const SessionOptions& option); 71 72 private: 73 // A Session instance should only be created from Create(). 74 Session(const SessionOptions& option); 75 76 StatusWithSize DoRead(ByteSpan dest) override; 77 Status DoWrite(ConstByteSpan data) override; 78 79 // An opaque object up to the backend to implement. 80 backend::SessionImplementation session_impl_; 81 }; 82 83 } // namespace pw::tls_client 84