diff --git a/doc/connectivity/networking/api/lwm2m.rst b/doc/connectivity/networking/api/lwm2m.rst index 73859f093d34716..6d26205511e3340 100644 --- a/doc/connectivity/networking/api/lwm2m.rst +++ b/doc/connectivity/networking/api/lwm2m.rst @@ -370,37 +370,38 @@ LwM2M security modes ******************** The Zephyr LwM2M library can be used either without security or use DTLS to secure the communication channel. -When using DTLS with LwM2M engine, PSK (Pre-Shared Key) and X.509 certificates are two security modes that can be used to secure the communication. -The engine uses LwM2M Security object (Id 0) to read stored credentials and feed keys from security object into +When using DTLS with the LwM2M engine, PSK (Pre-Shared Key) and X.509 certificates are the security modes that can be used to secure the communication. +The engine uses LwM2M Security object (Id 0) to read the stored credentials and feed keys from the security object into the TLS credential subsystem, see :ref:`secure sockets documentation `. -When security is used :kconfig:option:`CONFIG_LWM2M_DTLS_SUPPORT` Kconfig option must be enabled. +Enable the :kconfig:option:`CONFIG_LWM2M_DTLS_SUPPORT` Kconfig option to use the security. -Depending on the selected mode, security object should contain following data: +Depending on the selected mode, the security object must contain following data: PSK - Security Mode (Resource ID 2) should be set to zero (Pre-Shared Key mode). + Security Mode (Resource ID 2) set to zero (Pre-Shared Key mode). Identity (Resource ID 3) contains PSK ID in binary form. Secret key (Resource ID 5) contains the PSK key in binary form. - If key or identity is provided as a hex string, it must be converted to binary before storing into security object. + If the key or identity is provided as a hex string, it must be converted to binary before storing into the security object. X509 - When X509 certificates are used, Security Mode (ID 2) should be set to 2 (Certificate mode). + When X509 certificates are used, set Security Mode (ID 2) to ``2`` (Certificate mode). Identity (ID 3) is used to store the client certificate and Secret key (ID 5) must have a private key associated with the certificate. Server Public Key resource (ID 4) must contain a server certificate or CA certificate used to sign the certificate chain. - If :kconfig:option:`CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT` is enabled, certificates and private key can be fed as a PEM format. Otherwise they must be in binary DER format. + If the :kconfig:option:`CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT` Kconfig option is enabled, certificates and private key can be entered in PEM format. + Otherwise, they must be in binary DER format. NoSec - When no security is used, Security Mode (Resource ID 2) should be set to value 3 (NoSec). + When no security is used, set Security Mode (Resource ID 2) to ``3`` (NoSec). -In all modes above, Server URI resource (ID 0) should contain full URI for the target server. -When DNS names are used, DNS resolver should be enabled. +In all modes, Server URI resource (ID 0) must contain the full URI for the target server. +When DNS names are used, the DNS resolver must be enabled. -LwM2M stack provides callbacks in :c:struct:`lwm2m_ctx` structure that are used to feed keys from -LwM2M security object into the TLS credential subsystem. By default, these callbacks can be left -as NULL pointers, in which case default callbacks are used. When external TLS stack, or non default -socket options are required, user may overwrite the :c:func:`lwm2m_ctx.load_credentials` or :c:func:`lwm2m_ctx.set_socketoptions` callbacks. +LwM2M stack provides callbacks in the :c:struct:`lwm2m_ctx` structure. +They are used to feed keys from the LwM2M security object into the TLS credential subsystem. +By default, these callbacks can be left as NULL pointers, in which case default callbacks are used. +When an external TLS stack, or non-default socket options are required, you can overwrite the :c:func:`lwm2m_ctx.load_credentials` or :c:func:`lwm2m_ctx.set_socketoptions` callbacks. -Example of setting up the security object for PSK mode: +An example of setting up the security object for PSK mode: .. code-block:: c @@ -419,7 +420,7 @@ Example of setting up the security object for PSK mode: /* Set the client pre-shared key (PSK) */ lwm2m_set_opaque(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 5), client_psk, sizeof(client_psk)); -Example of setting up the security object for X509 certificate mode: +An example of setting up the security object for X509 certificate mode: .. code-block:: c diff --git a/include/zephyr/net/lwm2m.h b/include/zephyr/net/lwm2m.h index 211c91ce051f0de..9874a327a07c5c7 100644 --- a/include/zephyr/net/lwm2m.h +++ b/include/zephyr/net/lwm2m.h @@ -2253,7 +2253,7 @@ enum lwm2m_security_mode_e { /** * @brief Read security mode from selected security object instance. * - * This data is only valid if RD client is running. + * This data is valid only if RD client is running. * * @param ctx Pointer to client context. * @return int Positive values are @ref lwm2m_security_mode_e, negative error codes otherwise. @@ -2263,8 +2263,8 @@ int lwm2m_security_mode(struct lwm2m_ctx *ctx); /** * @brief Set default socket options for DTLS connections. * - * Engine calls this when @ref lwm2m_ctx::set_socketoptions is not overwritten. - * You may call this from overwritten callback to set extra options after or + * The engine calls this when @ref lwm2m_ctx::set_socketoptions is not overwritten. + * You can call this from the overwritten callback to set extra options after or * before defaults. * * @param ctx Client context