View source for Using DTLS

[[SNMP]] over [[DTLS]] over [[UDP]] is supported in Net-SNMP 5.5 and beyond.  This page describes what is necessary to configure the software to use it.

== Generating X.509 Certificates ==

DTLS uses [[X.509]] certificates to authenticate both the client and server sides of DTLS connections.  This means that both the SNMP server and client need to have certificates generated and installed in order to make use of DTLS.  The client will need to verify the servers certificate, to make sure it's talking to the server it thinks it is.  The server needs to verify the clients certificate, and possibly extract user-name information from it, in order to verify the client is who they say they are and assign appropriate access control settings.

''Note:'' At the time of this writing, the DTLS code present in Net-SNMP 5.5 only accepts SNMPv3 user-names from the CommonName component of the X.509 certificate.

You need to generate certificates using the [[openssl]] command (I know you have OpenSSL installed or else you wouldn't have been able to even compile in DTLS support).  Certificates have both a private and public key halves.  Guard the private key well, and give the public key out freely.

=== Generating a Self-signed Certificate ===

Generally you'll want to generate a master CA certificate that is used as a trust point for all you software.  IE, you can configure snmpd to trust any certificate that has been signed by this single CA certificate.  That doesn't mean they'll get access, however, because they'll still need to pass the [[VACM]] checks before they can get or send any data to the server.

=== Generating a Self-signed Certificate ===

If you don't want to generate a CA to sign everything, you can also simply generate self-signed certificates and use them instead by using the -x509 flag.  The resulting server *.cert files should be all concatenated together for the clients to use as authorized servers, and the user certificates should be concatenated together for the servers to refer to (see below for configuration options).

 # openssl req -newkey rsa:2048 -x509 -nodes -out myhost.example.com.cert -keyout myhost.example.com.priv

It'll ask you a bunch of questions, which you should answer.  See the ''req(1)'' manual page for further reading about certificate generation.  If you want to examine the results after it is done, use openssl to read it back in:

 # openssl -in myhost.example.com.cert -text

== Configuring Servers ==

=== Configuring Certificates ===

The tokens for specifying which [[X.509]] certificates are configured in the [[snmp.conf]] file.  '''Note: NOT''' the [[snmpd.conf]] file.  The tokens are specific to all applications and thus belong in the ''snmp.conf'' file (without the "d").  If you wish to put them in the ''snmpd.conf'' file you can do so by prefixing the lines with ''[snmp]'', as described in the {{man|snmp_config}} manual page.

=== Setting the Server's Certificate ===

The server needs to be configured with both it's private and public keys.  To do this, use the following two ''snmp.conf'' tokens to configure the server:

  defX509ServerPub  /path/to/servercert.cert
  defX509ServerPriv /path/to/servercert.priv

=== Recognizing Client Certificates ===

Additionally, the client's incoming certificates need to be cryptographically checked and verified.  To define the root CA certificates, or self-signed certificates, they all need to be put together in a single file containing a concatenated set of acceptable certificates:

  defX509ClientCerts /path/to/for-users.cert

=== Setting up Access Control ===

SNMP over DTLS is a mode of SNMPv3, so [[access control]] settings are done using the standard [[VACM]] configuration tokens.  The [[security model]] used should normally be [[TSM]] (further discussed below in the example usage section).  Here are some example snmpd.conf configuration settings for incoming users with a X.509 [[CommonName]] field of "Wes Hardaker":

  rwuser -s tsm "Wes Hardaker"

=== Opening and Listening on a Port for DTLS traffic ===

[[snmpd]] and [[snmptrapd]] can both be configured to accept and process connections sent over DTLS.  This is done on the command line using the ''dtls:'' addressing specifier.  E.G. this:

  # '''snmpd dtls:9161'''

tells snmpd to open port 9161 and listen for incoming SNMP over DTLS connections on it.

''Note: at the time of this writing this is not yet a standardized port over which SNMP over DTLS should be run.  There will probably be a standard port after the [[IETF]]'s [[ISMS]] working group finishes with the specification and it becomes an [[RFC]].

== Configuring the Applications ==

Tools like [[snmpget]], [[snmpwalk]] or anything that uses the core [[session]] structures within the main [[libnetsnmp|Net-Snmp library]] like the [[perl]] and [[python]] modules can make use of [[DTLS]] using the procedures described below.

=== Setting the Clients's Certificate ===

The client needs to be configured with both it's private and public keys.  To do this, use the following two ''snmp.conf'' tokens to configure the client:

  defX509ClientPub  /path/to/user-cert.cert
  defX509ClientPriv /path/to/user-cert.priv

=== Recognizing Client Certificates ===

Additionally, the certificates for the servers that the client should connect to need to be cryptographically checked and verified.  To define the server's root CA certificates, or self-signed certificates, they all need to be put together in a single file containing a concatenated set of acceptable certificates:

  defX509ServerCerts /path/to/servers.cert