You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/reference/technology/connectivity/securesocket.md
+22-23Lines changed: 22 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
## Secure Socket
2
2
3
-
Mbed OS provides an interface for creating secure connections in the form of TLS stream. The `TLSSocketWrapper` class provides the ability to secure any stream-based socket connection, for example TCP stream. This allows you to use existing protocol libraries through a secure connections.
3
+
Mbed OS provides an interface for creating secure connections in the form of TLS stream. The `TLSSocketWrapper` class gives you the ability to secure any stream-based socket connection, for example TCP stream. This allows you to use existing protocol libraries through secure connections.
4
4
5
-
`TLSSocketWrapper` inherits the `Socket` class, which allows any application that uses `Socket` to use `TLSSocketWrapper` instead. Secure socket both uses Socket interface as its transport layer and implements it. This makes it transport independent, and there is no direct dependency on the IP stack. For example, you can use the HTTP library and give `TLSSocketWrapper` to it to covert it to HTTPS.
5
+
`TLSSocketWrapper` inherits the `Socket` class, which allows any application that uses `Socket` to use `TLSSocketWrapper` instead. Secure socket both uses the Socket interface as its transport layer and implements it. This makes it transport independent, and there is no direct dependency on the IP stack. For example, you can use the HTTP library and give `TLSSocketWrapper` to it to covert it to HTTPS.
6
6
7
-
For easy to use API there is helper class called `TLSSocket` that contains internal TCP socket for transport stream.
7
+
The helper class called `TLSSocket` contains internal TCP socket for transport stream.
8
8
9
9
### Usage example
10
10
11
-
`TLSSocketWrapper` implements Mbed OS Socket API and extends it with functions that allow configuring security certificates, so it is straightforward to use after setting up. Please note that for most of the use cases, you are using these methods through `TLSSocket` class.
11
+
`TLSSocketWrapper` implements the Mbed OS Socket API and extends it with functions that allow configuring security certificates, so it is straightforward to use after setting up. Please note that for most of the use cases, you are using these methods through `TLSSocket` class:
12
12
13
13
```
14
14
TLSSocket *socket = new TLSSocket();
@@ -26,11 +26,11 @@ Please note that internal TLS structures require over 1 kB of RAM, so you need t
26
26
27
27
Internally `TLSSocket` consists of two classes, `TLSSocketWrapper` and `TLSSocket`, as shown in the following diagram:
The `TLSSocketWrapper` can use any `Socket` as its transport. `TLSSocket` is a helper that uses directly `TCPSocket` for its transport, so you can adopt existing TCP based applications to TLS.
32
32
33
-
One use case of `TLSSocketWrapper` is that existing TCP socket can be upgraded to TLS, by wrapping it like this:
33
+
One use case of `TLSSocketWrapper` is that you can upgrade the existing TCP socket to TLS, by wrapping it like this:
34
34
35
35
```
36
36
TCPSocket connection;
@@ -52,7 +52,7 @@ tls.send("HELLO", 5);
52
52
53
53
#### Configuring certificates
54
54
55
-
`TLSSocketWrapper` provides the following API to set server certificate. You can use either BASE64 formatted PEM certificate or binary DER certificates. The later form of these functions assumes `root_ca_pem` or `client_cert_pem` to be standard C string, counts its length and passes to method, which takes only `void*` and `len`.
55
+
`TLSSocketWrapper` provides the following API to set server certificate. You can use either BASE64 formatted PEM certificate or binary DER certificates. The latter form of these functions assumes `root_ca_pem` or `client_cert_pem` to be standard C string, counts its length and passes to method, which takes only `void*` and `len`.
`TLSSocketWrapper` implements [Mbed OS Socket API](../apis/network-socket.html) as follows.
93
+
`TLSSocketWrapper` implements the [Mbed OS Socket API](../apis/network-socket.html):
94
94
95
95
```
96
96
virtual nsapi_error_t close();
97
97
```
98
98
99
-
Destroys the memory allocated by TLS library. Also closes the transport socket, unless [transport mode](#transport-modes) is set to `TRANSPORT_KEEP` or `TRANSPORT_CONNECT`.
99
+
This destroys the memory the TLS library allocates. It also closes the transport socket, unless [transport mode](#transport-modes) is set to `TRANSPORT_KEEP` or `TRANSPORT_CONNECT`:
Initiates the TCP connection and continues to TLS hanshake. If [transport mode](#transport-modes) is either `TRANSPORT_KEEP` or `TRANSPORT_CLOSE`, TCP is assumed to be open and state directly goes into TLS handshake. This is currently forced to blocking mode. After succesfully connecting, you can set it to non-blockin mode.
105
+
The code above initiates the TCP connection and continues to TLS hanshake. If [transport mode](#transport-modes) is either `TRANSPORT_KEEP` or `TRANSPORT_CLOSE`, TCP is assumed to be open and state directly goes into TLS handshake. This is currently forced to blocking mode. After succesfully connecting, you can set it to nonblocking mode:
These work as expected, but `SocketAddress` parameters are ignored. TLS connection cannot change the peer. Also `recvfrom()` call does not set the peer address.
114
+
These work as expected, but `SocketAddress` parameters are ignored. The TLS connection cannot change the peer. Also,`recvfrom()` call does not set the peer address.
115
115
116
116
Mbed TLS error codes `MBEDTLS_ERR_SSL_WANT_READ` and `MBEDTLS_ERR_SSL_WANT_WRITE` are translated to `NSAPI_ERROR_WOULD_BLOCK` before passing to user.
117
117
118
-
`MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY` is ignored and zero is returned to user (connection closed). Other error codes are passed through.
118
+
`MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY` is ignored, and zero is returned to you (connection closed). Other error codes are passed through:
0 commit comments