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