Configuration

This page gives some information on the freeDiameter.conf file that is required by the freeDiameter framework. The complete documentation is included in [source:freeDiameter/doc/freediameter.conf.sample doc/freediameter.conf.sample].

The configuration file consists in three main parts: local framework configuration, extensions, and remote connections. These parts are detailed in the next section.

The remaining of this page gives information on how to configure TLS properly, and some typical configuration files examples.

freeDiameter.conf

Local framework configuration

Diameter Protocol parameters

Identity

The first parameter in this section is Identity, which will be used to identify this peer in the Diameter network. The Diameter protocol mandates that the Identity used is a valid FQDN for the peer. This parameter can be omitted, in that case the framework will attempt to use system default value (as returned by hostname --fqdn).

Realm

In Diameter, all peers also belong to a Realm. If the realm is not specified, the framework uses the part of the Identity after the first dot.

TcTimer, TwTimer

Change the default reconnection and watchdog timers.

NoRelay

By default, freeDiameter acts as a Diameter Relay Agent by forwarding all messages it cannot handle locally. This parameter disables this behavior.

AppServThreads

Number of parallel threads that will handle incoming application messages. This parameter may be deprecated later in favor of a dynamic number of threads depending on the load.

Network protocols parameters

Port, SecPort, TLS_old_method

The Port on which freeDiameter framework will listen for incoming Diameter connections. SecPort is the dedicated listening port for TLS connections, as specified by rfc3588bis. Note that freeDiameter supports both RFC3588's flavour TLS (using default Diameter Port, TLS handshake after the CER/CEA exchange) and rfc3588bis's flavour (using a dedicated SecPort where CER/CEA exchange is also TLS protected). TLS_old_method sets a default TLS flavour for outgoing connections, that can be overwritten for each peer.

No_TCP, No_SCTP, Prefer_TCP, No_IP, No_IPv6

The default is to listen for IP & IPv6 and TCP & SCTP incoming connections, and attempt SCTP first when contacting another peer. Change these parameters to modify this default behavior. Parameters for outgoing connections can also be specified for each peer.

SCTP_streams

Overwrite the number of SCTP streams. This value should be kept low, especially if you are using TLS over SCTP, because it consumes a lot of resources in that case. See tickets 19 and 27 for some additional details on this.

ListenOn

Specify the addresses on which to bind the listening server. This must be specified if the framework is unable to auto-detect these addresses, or if the auto-detected values are incorrect. Note that the list of addresses is sent in CER or CEA message, so one should pay attention to this parameter if some adresses should be kept hidden.

TLS parameters

TLS_Cred

This parameter is mandatory, even if it is possible to disable TLS for peers connections. A valid certificate for this Diameter Identity is expected.

Other TLS_* parameters are optional but should usually be specified.

See How to configure TLS bellow for instructions on how to get started with this.

Extensions

LoadExtension

Specify either an absolute path, or a relative path, in which case the file will be searched in the active directory first, and in INSTALL_EXTENSIONS_SUFFIX afterwards. The configuration file name is optional. If specified, it also falls back to files in DEFAULT_CONF_PATH.

See the list of extensions on page Extensions. Note that some extensions are not built by default, refer to Installation for details.

Remote connections

ConnectPeer

Declare a remote peer to which this peer must maintain a connection. In addition, this allows specifying non-default parameters for this peer only (for example disable SCTP with this peer, or use RFC3588-flavour TLS).

Note that by default, if a peer is not listed as a ConnectPeer entry, an incoming connection from this peer will be rejected. If you want to accept incoming connections from other peers, see the acl_wl.fdx? extension which allows exactly this.

How to configure TLS

Because Diameter protocol conveys sensible information in terms of privacy and security (such as user location, cryptographic material, ...) it must never be sent "in clear" on the wire. The Diameter specification allows either IPsec protection or TLS protection to be used to protect its messages.

There is currently no way for the freeDiameter framework to discover if an IPsec tunnel is setup with any given peer -- it would require for example an API to query the IKEv2 component, but there is no standard API for this.

For these reasons, the freeDiameter policy is to mandate the configuration of valid TLS credentials. Afterwards, TLS can be disabled for each connection in the ConnectPeer directive.

Priority setting

The configuration file allows to specify TLS_Prio parameter. This parameter is directly passed to GNU TLS library, it is not interpreted by freeDiameter. You should check ​the relevant GNU TLS documentation for more information on this Priority string.

The following sub-sections show how to configure the TLS credentials properly, depending on your environment.

Real PKI

If you already have a PKI set up for your Diameter nodes (for example when you join a Diameter consortium), the following hints will help you configuring freeDiameter. If you just want to setup an experimental testbed, please check the next sub-section.

We use the following imaginary PKI hierarchy in this example:

 Our realm: example.net  |   Other realms: partner1, partner2
=======================================================================
     my_root_ca  ----------- my_partner1_ca.example.com ------ ....
         |                                 |
     my_group_ca                         .....
         |                                 |
   my_diameter_peer                   remote_peer

In case of real PKI (or set of PKIs) the first thing you will need is the list of trusted root Certificate Authorities certificates. Concatenate all these different certificates into one file, as follow:

$ cat my_root_ca.example.net.pem     \
      my_partner1_ca.example.com.pem \
      my_partner2_ca.example.org.pem > ca.pem

From this point, we assume that you have a file ca.pem that contains all the trust anchors for your Diameter network (at least for the peers you may connect to).

You should do the same with Certificate Revocation Lists (CRL), with a script to update the file on a regular basis. Note however that currently freeDiameter does not support reloading the CRL (needs improvement, see 29). This CRL is saved as crl.pem.

You need a private key for your Diameter peer. There are many tools to generate such a key. You can use for example certtool from GNUTLS, or openssl. Once you have generated your private key, save it as my_key.pem. This is the command with openssl:

$ openssl genrsa -out my_key.pem 2048

Then, generate a Certificate Signing Request (CSR), that you will send to your PKI administrator. Depending on your realm's PKI policy, the content of the CSR may vary. However, the following points are important (confirm with your PKI administrator, since he can overwrite everything that is set in the CSR in the certificate):

• The Common Name (CN) must be your Diameter Identity ('my_diameter_peer.example.net' in our example). Support for domain-wide certificates has not been tested yet.
• The key usage must allow for TLS client and server usages.

The following example command will generate a CSR after asking a few questions:

$ openssl req -new -out csr.pem -key my_key.pem

Once you have this CSR, send it to your PKI administrator for certificate signing. In our example, the administrator will use "my_group_ca.example.net" CA to sign the request and issue the certificate, then give this certificate to you, as file cert.pem. In real life, this step usually requires additional checks / paperwork.

If the certificate is not signed directly by the root CA in your realm, you must retrieve all the intermediate CA certificates. In our example, there is only "my_group_ca", but it is possible to have several intermediate CAs. Save all these certificates, in addition to your final certificate, in one file, as follow (the order should be the hierarchical order from bottom to top):

$ cat cert.pem my_group_ca.pem \
       > certchain.pem

Now, you are all set. Configure freeDiameter as follow:

TLS_Cred = "certchain.pem", "my_key.pem";
TLS_CA = "ca.pem";
TLS_CRL = "crl.pem";
TLS_DH_Bits = 2048;

Testbed

In case you are setting a simple experiment with no real traffic expected, the following instructions will help you getting started. However, these do NOT provide a valid secure environment for real operation.

The first sub-section explains how to use a self-signed certificate to make freeDiameter framework happy, and then disable TLS for all connections. The second sub-section explains how to use self-signed certificates to actually use TLS protection in your testbed.

Without TLS

The most simple situation is when you don't want to use TLS for your communications in your testbed. In that case, you only need to create a self-signed certificate that corresponds to the Diameter Identity of your peer, and then specify the "No_TLS;" flag for your connections.

• Create the self-signed certificate.

This can be done with many tools, here is an example using openssl.

$ openssl req -new -batch -x509 -days 3650 -nodes     \
   -newkey rsa:1024 -out cert.pem -keyout privkey.pem \
   -subj /CN=my.diameter.identity

This command should generate a self-signed certificate with Common Name "my.diameter.identity" (change to match your real Identity).

• Create a Diffie-Hellman file.

Although not mandatory, it is recommended to create a DH file, so that the framework does not generate a new one each time it starts.

This again can be done with GNUTLS's certtool or OpenSSL. Here is an example command with the later:

$ openssl dhparam -out dh.pem 1024

• Configure freeDiameter.

This is the corresponding part of freeDiameter.conf:

TLS_Cred = "cert.pem", "privkey.pem";
TLS_CA = "cert.pem";
TLS_DH_File = "dh.pem";

ConnectPeer = ... { No_TLS; };

Note that it is possible (but not recommended) to have the private key and certificate stored in the same file.

With TLS

• Case of only two peers

If your testbed consists of only two peers, you may follow the same instructions as in previous section to generate the self-signed certificate on each peer. Then, the following additional step must be performed on both peers:

$ cat peer1.cert.pem peer2.cert.pem > ca.pem

Then configure freeDiameter.conf with:

TLS_Cred = "cert.pem", "privkey.pem";
TLS_CA = "ca.pem";

• Case of more peers

In order to avoid copying the self-signed certificates between all peers (you'd have to copy each peer certificate to all other peers), it is probably easier to set up a fake CA and have this CA sign all your peers certificates.

It is the scenario we are using in our testbed, therefore you might find the following resources useful:

[source:freeDiameter/contrib/PKI contrib/PKI]

This folder contains some scripts that can help you managing this "fake" CA. You will find a few more details in the [source:freeDiameter/contrib/README contrib/README] file. The easiest way is to have a storage shared with all your peers, and have this fake PKI files reside in this storage. Otherwise you may find the make ship target from ca_script2 script in this directory useful.

[source:VirtualTestbed/ca/rebuild_tree.sh rebuild_tree.sh]

This is the script we use to generate all the certificates of our test machines. It uses the Makefile from ca_script2. It shows an example of how to use this script to generate all the peers certificates. Check the script [source:VirtualTestbed/scripts/ca-install.sh ca-install.sh] for an example of how we use the generated certificates in each node.

Configuration examples

You can find many configuration files examples in our testbed [source:VirtualTestbed/conf here]. Some of the examples are explained in the Screenshots page in more details. You may also check the EAP Testbed explanation page that shows how to perform EAP authentication and accounting with freeDiameter.

Here is a typical example of configuration:

# -------- Local ---------

# Uncomment if the framework cannot resolv it.
#Identity = "backend.localhost";

# TLS configuration (see previous section)
TLS_Cred = "cert.pem" , "privkey.pem";
TLS_CA = "ca.pem";

# Limit the number of SCTP streams
SCTP_streams = 3;


# -------- Extensions ---------

# Uncomment (and create rtd.conf) to specify routing table for this peer.
#LoadExtension = "rt_default.fdx" : "rtd.conf";

# Uncomment (and create acl.conf) to allow incoming connections from other peers.
#LoadExtension = "acl_wl.fdx" : "acl.conf";

# Uncomment to display periodic state information
#LoadExtension = "dbg_monitor.fdx";

# Uncomment to enable an interactive Python interpreter session.
# (see doc/dbg_interactive.py.sample for more information)
#LoadExtension = "dbg_interactive.fdx";

# Load the RFC4005 dictionary objects
LoadExtension = "dict_nasreq.fdx";

# Load RFC4072 dictionary objects
LoadExtension = "dict_eap.fdx";

# Load the Diameter EAP server extension (requires diameap.conf)
LoadExtension = "app_diameap.fdx" : "diameap.conf";

# Load the Accounting Server extension (requires app_acct.conf)
LoadExtension = "app_acct.fdx" : "app_acct.conf";


# -------- Peers ---------

# The framework will actively attempt to establish and maintain a connection
# with the peers listed here.
# For only accepting incoming connections, see the acl_wl.fx extension.

ConnectPeer = "nas.localhost" { No_TLS; };
ConnectPeer = "relay.localhost" { ConnectTo = "2001:DB8:1234::5678"; };

---