ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Doxygen corrections to DTLSSocket.h, TLSSocket.h, TLSSocketWrapper.h and DTLSSocketWrapper.h

pull/9646/head
Kari Haapalehto 2019-01-10 10:43:24 +02:00 committed by adbridge
parent c2718e3666
commit 02e2704db0
4 changed files with 85 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
features/netsocket/DTLSSocket.h
View File

@ -29,11 +29,16 @@
// This class requires Mbed TLS SSL/TLS client code
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief DTLSSocket implement DTLS stream over the existing Socket transport
*/
class DTLSSocket : public DTLSSocketWrapper {
public:
/** Create an uninitialized DTLS socket
/** Create an uninitialized DTLS socket.
*
* Must call open to initialize the socket on a network stack.
* @param _udp_socket Underlying transport socket.
*/
DTLSSocket() : DTLSSocketWrapper(&_udp_socket) {}
@ -41,14 +46,14 @@ public:
*/
virtual ~DTLSSocket();
/** Create a socket on a network interface
/** Create a socket on a network interface.
*
* Creates and opens a socket on the network stack of the given
* network interface.
* If hostname is also given, user is not required to call set_hostname() later.
*
* @param stack Network stack as target for socket
* @param hostname Hostname used for certificate verification
* @param stack Network stack as target for socket.
* @param hostname Hostname used for certificate verification.
*/
template <typename S>
DTLSSocket(S *stack, const char *hostname = NULL) : DTLSSocketWrapper(&_udp_socket, hostname)
@ -57,14 +62,14 @@ public:
MBED_ASSERT(ret == NSAPI_ERROR_OK);
}
/** Opens a socket
/** Opens a socket.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure.
*/
virtual nsapi_error_t open(NetworkStack *stack)
{
@ -79,14 +84,14 @@ public:
using DTLSSocketWrapper::connect;
/** Connects TCP socket to a remote host
/** Connects TCP socket to a remote host.
*
* Initiates a connection to a remote server specified by either
* a domain name or an IP address and a port.
*
* @param host Hostname of the remote host
* @param port Port of the remote host
* @return 0 on success, negative error code on failure
* @param host Hostname of the remote host.
* @param port Port of the remote host.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t connect(const char *host, uint16_t port);

14
features/netsocket/DTLSSocketWrapper.h
View File

@ -1,3 +1,4 @@
/** @file DTLSSocketWrapper.h DTLSSocketWrapper */
/*
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
@ -14,6 +15,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @addtogroup netsocket
* @{
*/
#ifndef DTLSSOCKETWRAPPER_H
#define DTLSSOCKETWRAPPER_H
@ -23,8 +27,17 @@
// This class requires Mbed TLS SSL/TLS client code
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief DTLSSocketWrapper implement DTLS stream over the existing Socket transport
*/
class DTLSSocketWrapper : public TLSSocketWrapper {
public:
/** Create a DTLSSocketWrapper.
*
* @param transport Underlying transport socket to wrap.
* @param hostname Hostname of the remote host, used for certificate checking.
* @param control Transport control mode. See @ref control_transport.
*/
DTLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
private:
static void timing_set_delay(void *ctx, uint32_t int_ms, uint32_t fin_ms);
@ -37,3 +50,4 @@ private:
#endif
#endif
/** @} */

22
features/netsocket/TLSSocket.h
View File

@ -35,13 +35,14 @@
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers
* \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers.
*/
class TLSSocket : public TLSSocketWrapper {
public:
/** Create an uninitialized socket
/** Create an uninitialized socket.
*
* Must call open to initialize the socket on a network stack.
* @param tcp_socket Underlying transport socket.
*/
TLSSocket() : TLSSocketWrapper(&tcp_socket) {}
@ -49,17 +50,16 @@ public:
*/
virtual ~TLSSocket();
/** Opens a socket
/** Opens a socket.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
* network interface.
*
* @note TLSSocket cannot be reopened after closing. It should be destructed to
* clear internal TLS memory structures.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure.
*/
virtual nsapi_error_t open(NetworkStack *stack)
{
@ -74,14 +74,14 @@ public:
using TLSSocketWrapper::connect;
/** Connects TCP socket to a remote host
/** Connects TCP socket to a remote host.
*
* Initiates a connection to a remote server specified by either
* a domain name or an IP address and a port.
*
* @param host Hostname of the remote host
* @param port Port of the remote host
* @return 0 on success, negative error code on failure
* @param host Hostname of the remote host.
* @param port Port of the remote host.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t connect(const char *host, uint16_t port);

74
features/netsocket/TLSSocketWrapper.h
View File

@ -39,23 +39,25 @@
*/
class TLSSocketWrapper : public Socket {
public:
/** Transport modes */
enum control_transport {
TRANSPORT_KEEP,
TRANSPORT_CONNECT_AND_CLOSE,
TRANSPORT_CONNECT,
TRANSPORT_CLOSE,
TRANSPORT_KEEP, /**< Doesn't call connect() or close() on transport socket */
TRANSPORT_CONNECT_AND_CLOSE, /**< Does call connect() and close() on transport socket */
TRANSPORT_CONNECT, /**< Does call only connect() on transport socket */
TRANSPORT_CLOSE, /**< Does call close() on transport socket */
};
/* Create a TLSSocketWrapper
/** Create a TLSSocketWrapper.
*
* @param transport Underlying transport socket to wrap
* @param hostname Hostname of the remote host, used for certificate checking
* @param transport Underlying transport socket to wrap.
* @param hostname Hostname of the remote host, used for certificate checking.
* @param control Transport control mode. See @ref control_transport.
*/
TLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
/** Destroy a socket wrapper
/** Destroy a socket wrapper.
*
* Closes socket wrapper if the socket wrapper is still open
* Closes socket wrapper if the socket wrapper is still open.
*/
virtual ~TLSSocketWrapper();
@ -64,6 +66,8 @@ public:
* TLSSocket requires hostname that is used to verify the certificate.
* If hostname is not given in constructor, this function must be used before
* starting the TLS handshake.
*
* @param hostname Hostname of the remote host, used for certificate checking.
*/
void set_hostname(const char *hostname);
@ -71,12 +75,14 @@ public:
*
* @param root_ca Root CA Certificate in any mbed-TLS supported format.
* @param len Length of certificate (including terminating 0 for PEM).
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
/** Sets the certification of Root CA.
*
* @param root_ca_pem Root CA Certificate in PEM format
* @param root_ca_pem Root CA Certificate in PEM format.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
@ -84,8 +90,9 @@ public:
*
* @param client_cert client certification in PEM or DER format.
* @param client_cert_len certificate size including the terminating null byte for PEM data.
* @param client_private_key_pem client private key in PEM or DER format
* @param client_private_key_pem client private key in PEM or DER format.
* @param client_private_key_len key size including the terminating null byte for PEM data
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
const void *client_private_key_pem, size_t client_private_key_len);
@ -94,6 +101,7 @@ public:
*
* @param client_cert_pem Client certification in PEM format.
* @param client_private_key_pem Client private key in PEM format.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
@ -102,20 +110,19 @@ public:
* The socket must be connected to a remote host. Returns the number of
* bytes sent from the buffer.
*
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @return Number of sent bytes on success, negative error
* code on failure
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error code on failure.
*/
virtual nsapi_error_t send(const void *data, nsapi_size_t size);
/** Receive data over a TLS socket
/** Receive data over a TLS socket.
*
* The socket must be connected to a remote host. Returns the number of
* bytes received into the buffer.
*
* @param data Destination buffer for data received from the host
* @param size Size of the buffer in bytes
* @param data Destination buffer for data received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure. If no data is available to be received
* and the peer has performed an orderly shutdown,
@ -140,48 +147,55 @@ public:
virtual nsapi_error_t getpeername(SocketAddress *address);
#if defined(MBEDTLS_X509_CRT_PARSE_C) || defined(DOXYGEN_ONLY)
/** Get own certificate directly from Mbed TLS
* @return internal Mbed TLS X509 structure
/** Get own certificate directly from Mbed TLS.
*
* @return internal Mbed TLS X509 structure.
*/
mbedtls_x509_crt *get_own_cert();
/** Set own certificate directly to Mbed TLS
/** Set own certificate directly to Mbed TLS.
*
* @param crt Mbed TLS X509 certificate chain.
* @return error code from mbedtls_ssl_conf_own_cert()
* @return error code from mbedtls_ssl_conf_own_cert().
*/
int set_own_cert(mbedtls_x509_crt *crt);
/** Get CA chain structure.
*
* @return Mbed TLS X509 certificate chain.
*/
mbedtls_x509_crt *get_ca_chain();
/** Set CA chain directly to Mbed TLS
/** Set CA chain directly to Mbed TLS.
*
* @param crt Mbed TLS X509 certificate chain.
*/
void set_ca_chain(mbedtls_x509_crt *crt);
#endif
/** Get internal Mbed TLS configuration structure
* @return Mbed TLS SSL config
/** Get internal Mbed TLS configuration structure.
*
* @return Mbed TLS SSL config.
*/
mbedtls_ssl_config *get_ssl_config();
/** Override Mbed TLS configuration.
* @param conf Mbed TLS SSL configuration structure
*
* @param conf Mbed TLS SSL configuration structure.
*/
void set_ssl_config(mbedtls_ssl_config *conf);
/** Get internal Mbed TLS context structure.
* @return SSL context
*
* @return SSL context.
*/
mbedtls_ssl_context *get_ssl_context();
protected:
/** Initiates TLS Handshake
/** Initiates TLS Handshake.
*
* Initiates a TLS handshake to a remote peer
* Underlying transport socket should already be connected
* Initiates a TLS handshake to a remote peer.
* Underlying transport socket should already be connected.
*
* Root CA certification must be set by set_ssl_ca_pem() before
* call this function.