Using DTLS

"SNMP over DTLS over UDP" and "SNMP over TLS over TCP" are supported in Net-SNMP 5.6 and beyond (5.5 had preliminary experimental support that shouldn't be considered complete). This page describes what is necessary to configure the software to use it.

Note: these instructions are preliminary and are subject to change until the release of the 5.6 software

Compiling Net-SNMP with TLS and DTLS Support

Just ensure you have a recent version of OpenSSL installed as well as run configure with the following two options in addition to your normal options:

# ./configure --with-security-modules=tsm --with-transports=TLSTCP DTLSUDP

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.

Net-SNMP comes with an easy-to-use certificate management program (net-snmp-cert) that helps you generate and manage certificates on your system. You're encouraged to use it but you may certainly make your own as well.

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.

(documentation TBD about doing this)

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.

Generate the one for the manager:

# net-snmp-cert gencrt -t manager -c joecool

Then generate one for your agent:

# net-snmp-cert gencrt -t snmpd -c hostname.example.com

To see what certificates you've generated use the following command:

# net-snmp-cert showcerts
certs/manager.crt:
subject= /C=US/ST=California/L=Davis/O=Net-SNMP Developers/OU=SNMP/DTLS/CN=joecool/emailAddress=joecool@users.net-snmp.org

certs/snmpd.crt:
subject= /C=US/ST=California/L=Davis/O=Net-SNMP Developers/OU=SNMP/DTLS/CN=hostname.example.com/emailAddress=admin@users.net-snmp.org

todo: document how to change all the parameters, configure the config files, etc

todo: define how to set the subjectAltName extension

Examining the Fingerprints

We'll be referring to fingerprints in the configuration files a lot. Here's how to find them:

# net-snmp-cert showcerts fingerprint
certs/manager.crt:
SHA1 Fingerprint=56:E4:53:CE:D4:52:87:A7:74:11:BE:BA:9F:37:11:23:4A:77:CE:83

certs/snmpd.crt:
SHA1 Fingerprint=2A:10:4A:09:3C:7C:DF:E9:11:0F:73:D9:C6:58:90:74:3C:E3:6A:CC

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 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 dtlsudp: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 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 Server 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

Running and Testing

Start the server:

 # snmpd dtlsudp:9161

And try to get results from it:

 # ./snmpget --defSecurityModel=tsm dtlsudp:localhost:9161 sysContact.0

Debugging

For debugging in the server, run it in the foreground and turn on debugging of dtls and tsm:

# snmpd -f -Le -Dtsm,dtls dtlsudp:9161

Same for the clients:

# snmpget -Dtsm,dtls ...