Changes between Initial Version and Version 1 of Configuration

Timestamp:

Feb 28, 2011, 6:07:01 PM (13 years ago)

Author:

Sebastien Decugis

Comment:

--

Configuration

@@ +1 @@
+[[PageOutline(2-4)]]
+= 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 [ticket:19] and [ticket: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 [#tls_tuto 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 [wiki:Installation#cmakeflags INSTALL_EXTENSIONS_SUFFIX] afterwards. The configuration file name is optional. If specified, it also falls back to files in [wiki:Installation#cmakeflags DEFAULT_CONF_PATH].
+
+See the list of extensions here: [wiki: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 [wiki:acl_wl.fdx] extension which does exactly this.
+
+== How to configure TLS == #tls_tuto 
+
+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"; };
+
+}}}