Using DTLS

"SNMP over DTLS over UDP" and "SNMP over TLS over TCP" (RFC5953) 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.

Note: net-snmp-cert creates and uses its own openssl configuration file. Before you start generating certificates, you might want to customize this configuration file for your Country, State, Locality and so on. The first step is to get net-snmp-cert to generate its default file. You can do this by running the following command:

# net-snmp-cert showcerts

The only output should be the path to the newly created tls directory which contains the newly installed openssl.conf. Tweak to taste and then continue with the rest of this tutorial.

You may also need to change the permissions of the created directory hierarchy. This will be handled by the tool in the near future.

# chmod 755 /usr/local/share/snmp/tls/ /usr/local/share/snmp/tls/ca-certs/ /usr/local/share/snmp/tls/certs/

Generating a CA-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 the CA Certificate

To generate a CA certificate:

# net-snmp-cert genca -I -n hostname.example.com

Generating CA-signed Certificates

Generate the one for the manager:

# net-snmp-cert gencsr -I -t manager -n joecool --san email:cooljoe@hostname.example.com

Then generate one for your agent:

# net-snmp-cert gencsr -I -t snmpd -n hostname.example.com --san DNS:snmpd.example.com

Then sign them:

# net-snmp-cert signcsr -I --with-ca hostname.example.com --csr manager
# net-snmp-cert signcsr -I --with-ca hostname.example.com --csr snmpd

And move them to the certs directory and make them readable:

# mv /usr/local/share/snmp/tls/newcerts/*.crt /usr/local/share/snmp/tls/certs/
# chmod a+r /usr/local/share/snmp/tls/ca-certs/* /usr/local/share/snmp/tls/certs/*

If your manager will be a non-root user, you may want to move their private key to their home directory:

$ net-snmp-cert showcerts
$ sudo cp /usr/local/share/snmp/tls/certs/manager.crt ~/.snmp/tls/certs/
$ sudo mv /usr/local/share/snmp/tls/private/manager.key ~/.snmp/tls/private/
$ sudo chown $USER: ~/.snmp/tls/private/manager.key

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 gencert -I -t manager -n joecool --san email:cooljoe@hostname.example.com

Then generate one for your agent:

# net-snmp-cert gencert -I -t snmpd -n hostname.example.com --san DNS:snmpd.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

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: the snmpd.conf file examples below contain the [snmp] prefix to fool the snmpd.conf file into reading snmp.conf tokens (as described in the snmp_config manual page).

Setting the Server's Certificate

By default, snmpd will search for a certificate named snmpd.crt and if found, use that certificate. If another tag was specified for the server certificate, the snmpd server needs to be configured with its key. To do this, use the following line to the snmpd.conf file using the correct fingerprint from your fingerprint list (see above for how to list fingerprints).

 [snmp] defX509ServerPub 2A:10:4A:09:3C:7C:DF:E9:11:0F:73:D9:C6:58:90:74:3C:E3:6A:CC

Recognizing Client Certificates

You must configure a mapping for a SNMPv3 user name. You can specify the user name directly (using the --sn flag), or use a field from the certificate (like the common name suing the --cn flag). Here are two examples. The first specifies that the common name from the certificate should be used as the user name, while the second specifies the user name directly (SnmpAdmin):

certSecName 10 56:E4:53:CE:D4:52:87:A7:74:11:BE:BA:9F:37:11:23:4A:77:CE:83 --cn
certSecName 20 56:E4:53:CE:D4:52:87:A7:74:11:BE:BA:9F:37:11:23:4A:77:CE:83 --sn SnmpAdmin

See the snmpd.conf manual page for futhere documentation on the usage of the certSecName token.

Setting up Access Control

SNMP over TLS and 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 "joecool", which matches the certificate generated above:

 rwuser -s tsm "joecool"

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: and tls: addressing specifier. E.G. this:

 # snmpd dtlsudp:10161 tlstcp:10161

tells snmpd to open two ports (udp's 10161 and tcp's 10161) and listen for incoming SNMP over DTLS and SNMP over TLS connections to them.

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 certificates via the command line

The snmp applications can use the -T flag to pass configuration to the transports being used (i.e. TLS and DTLS):

# snmpget -v 3 --defSecurityModel=tsm -u joecool -l authPriv \
          -T our_identity=56:E4:53:CE:D4:52:87:A7:74:11:BE:BA:9F:37:11:23:4A:77:CE:83 \
          -T their_identity=2A:10:4A:09:3C:7C:DF:E9:11:0F:73:D9:C6:58:90:74:3C:E3:6A:CC \
          dtlsudp:localhost:10161 sysContact.0

Setting the Clients's Certificate in the snmp.conf file

For certificates you're going to use regularily you should put them in your snmp.conf file instead (such as ~/.snmp/snmp.conf): To do this, use the following two snmp.conf tokens to configure the client with it's key (the first line) and the server's key (the second line):

 defX509ClientPub   56:E4:53:CE:D4:52:87:A7:74:11:BE:BA:9F:37:11:23:4A:77:CE:83
 defX509ServerPub 2A:10:4A:09:3C:7C:DF:E9:11:0F:73:D9:C6:58:90:74:3C:E3:6A:CC

Note: this tool will change to allow more remote servers and CAs to be specified.

You might also want to add default security settings:

defSecurityModel tsm
defSecurityName joecool
defSecurityLevel authPriv

Running and Testing

Start the server:

 # snmpd dtlsudp:10161 tlstcp:10161

And try to get results from it (assuming the snmp.conf discussed above)

dtls:

 # ./snmpget dtlsudp:localhost:10161 sysContact.0

tls

 # ./snmpget tlstcp:localhost:10161 sysContact.0

Debugging

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

# snmpd -f -Le -Dtsm,dtls,tls,openssl,cert dtlsudp:10161

Same for the clients:

# snmpget -Dtsm,dtls,tls,openssl,cert ...