blob: 8a74b8b0c0bc016efc7ff874d6afd97706627e19 (
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
// Copyright (C) 2020-2021 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
/**
@page libasiolink libkea-asiolink - Kea Boost ASIO Library
@section asiolinkUtilities Boost ASIO Utilities
The asiolink library (libkea-asiolink) encapsulates Boost ASIO tools:
- addr utilities: prefix (IOAddress and length pair) tools.
- dummy I/O callback.
- interval timer.
- I/O acceptor: asynchronous server ASIO socket (base class).
- I/O address: ASIO IP address.
- I/O ASIO socket (derived from I/O socket).
- I/O endpoint: ASIO IP endpoint (abstraction of a socket address).
- I/O error: @c isc::asiolink::IOError exception declaration.
- I/O service: ASIO I/O service (named I/O context in recent versions).
- I/O socket: ASIO I/O socket base class.
- TCP acceptor: TCP derivation of I/O acceptor.
- TCP endpoint: TCP derivation of I/O endpoint.
- TCP socket: TCP derivation of I/O socket.
- TLS acceptor: TLS derivation of TCP acceptor.
- TLS socket: TLS derivation of I/O socket embedding a TCP socket.
- UDP endpoint: UDP derivation of I/O endpoint.
- UDP socket: UDP derivation of I/O socket.
- Unix domain socket: Unix socket (AF_LOCAL) derivation of I/O socket.
- Unix domain acceptor: Unix socket (AF_LOCAL) derivation of I/O acceptor.
- Unix domain endpoint: Unix socket (AF_LOCAL) derivation of I/O endpoint.
These tools in general use the error code (vs throwing exception) overload
and for asynchronous methods / functions a callback taking the error code
as its first argument.
@section asiolinkTLSSupport TLS ASIO support
The TLS support is an extension of the TCP one:
- the TLS acceptor is derived from the TCP acceptor.
- the TLS socket embeds a TCP socket.
Basic socket operations as accept, connect, close, etc, are performed on
the parent or embedded TCP socket.
TLS adds a TLS context (TLS context objects encapsulate the TLS setup e.g.
certificates) and two new operations:
- TLS handshake which must be called after accept or connect before
any read or write.
- TLS shutdown which is an optional orderly close prepare. It must not
be called on any kind of errors and after a TLS shutdown the TLS stream
can not be used: the only valid operation on it is to close it.
@note TLS shows a stream of sequenced records interface but there is
no direct mapping between high level TLS operations and TCP I/O,
e.g. a TLS read can involve a TCP write and the opposite.
@note TLS introduces a new error code "stream_truncated" which is
the TLS short read.
To debug or extend the TLS support two tools are available:
- client and server samples for both OpenSSL and Botan.
- TLS unit tests (tls_unittest.cc file).
@section asiolinkMTConsiderations Multi-Threading Consideration for Boost ASIO Utilities
By default Boost ASIO utilities are not thread safe even if Boost ASIO tools
themselves are. When there is no state and the encapsulation is direct
the thread safety property is preserved. Exceptions to the by default
no thread safe are:
- I/O address (direct encapsulation) is thread safe.
- interval timer setup and cancel methods are thread safe.
*/
|
