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: (1) local framework configuration, (2) extensions, (3) remote connections.

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.

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. 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, 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 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 here: Extensions.

Remote connections

ConnectPeer

Declare a remote peer to maintain a connection to. In addition, this allows specifying non-default parameters for this peer only (for example disable SCTP with this peer).

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 does 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.

There is currently no way for the freeDiameter framework to discover if an IPsec tunnel is setup with any given peer (such as an API with the IKEv2 component).

For these reason, the freeDiameter policy is to mandate the configuration of a valid TLS credential. Then, TLS can be disabled in ConnectPeer directives.

Real PKI

If you already have a PKI set up for your Diameter nodes (for example when you join a Diameter consortium), the following will help you configuring freeDiameter properly. If on the other hand you just want to setup a testbed, please check the next section.

We imagine the following 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 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 node.

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). This 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 for example as my_key.pem. This is an example 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. Note however the following important points (to confirm with your PKI administrator, since he can overwrite anything that is set in the CSR anyway):

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

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.

If the certificate is not signed directly by the root CA in your realm, you must retrieve all the intermediate certificates. In our example, there is only "my_group_ca", but it is possible to have several intermediate CAs. Save all the intermediary CA's certificate, 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 testbed, the following instructions will help you getting started. However, these do NOT provide a valid secure environment for real operation.

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, 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 (especially if you have a storage shared with all your peers).

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

This folder contains some scripts that can help you managing this "fake" CA. You may find a few more details in the [source:freeDiameter/contrib/README contrib/README] file.

[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 included in the contrib/PKI folder. 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].

Here is a typical commented example:

# -------- 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"; };

---