Navigation

Changes between Version 6 and Version 7 of Configuration


Ignore:
Timestamp:
Mar 3, 2011, 4:04:57 PM (13 years ago)
Author:
Administrator
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Configuration

    v6 v7  
    44This 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].
    55
    6 The configuration file consists in three main parts: (1) local framework configuration, (2) extensions, (3) remote connections.
     6The configuration file consists in three main parts: local framework configuration, extensions, and remote connections. These parts are detailed in the next section.
    77
    88The remaining of this page gives information on how to configure TLS properly, and some typical configuration files examples.
    … …  
    1414
    1515 Identity::
    16    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.
     16   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}}}).
    1717
    1818 Realm::
    … …  
    2323
    2424 !NoRelay::
    25    By default, freeDiameter acts as a Diameter Relay Agent. This parameter disables this behavior.
     25   By default, {{{freeDiameter}}} acts as a Diameter Relay Agent by forwarding all messages it cannot handle locally. This parameter disables this behavior.
    2626
    2727 !AppServThreads::
    … …  
    3434
    3535 No_TCP, No_SCTP, Prefer_TCP, No_IP, No_IPv6::
    36    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.
     36   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.
    3737
    3838 SCTP_streams::
    … …  
    4949Other TLS_* parameters are optional but should usually be specified.
    5050
    51 See [#tls_tuto How to configure TLS] for instructions on how to get started with this.
     51See [#tls_tuto How to configure TLS] bellow for instructions on how to get started with this.
    5252
    5353=== Extensions ===
    … …  
    5656   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].
    5757
    58 See the list of extensions here: [wiki:Extensions].
     58See the list of extensions on page [wiki:Extensions]. Note that some extensions are not built by default, refer to [wiki:Installation] for details.
    5959
    6060=== Remote connections ===
    6161
    6262 !ConnectPeer::
    63    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).
    64 
    65 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.
     63   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).
     64
     65Note 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 allows exactly this.
    6666
    6767== How to configure TLS == #tls_tuto
    6868
    69 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.
    70 
    71 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).
    72 
    73 For these reason, the {{{freeDiameter}}} policy is to mandate the configuration of a valid TLS credential. Then, TLS can be disabled in ''!ConnectPeer'' directives.
     69Because 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.
     70
     71There 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.
     72
     73For 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.
    7474
    7575 {{{Priority}}} setting::
    76    The configuration file allows to specify {{{TLS_Prio}}} parameter. This parameter is directly passed to GNU TLS library, not interpreted by freeDiameter. You should check [http://www.gnu.org/software/gnutls/manual/gnutls.html#gnutls_005fpriority_005finit the relevant GNU TLS documentation] for more information on this Priority string.
    77 
     76   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 [http://www.gnu.org/software/gnutls/manual/gnutls.html#gnutls_005fpriority_005finit the relevant GNU TLS documentation] for more information on this Priority string.
     77
     78The following sub-sections show how to configure the TLS credentials properly, depending on your environment.
    7879
    7980=== Real PKI ===
    8081
    81 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.
    82 
    83 We imagine the following PKI hierarchy in this example:
     82If 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.
     83
     84We use the following imaginary PKI hierarchy in this example:
    8485{{{
    8586 Our realm: example.net  |   Other realms: partner1, partner2
    … …  
    9293}}}
    9394
    94 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:
    95 {{{
     95In 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:
     96{{{
     97#!sh
    9698$ cat my_root_ca.example.net.pem     \
    9799      my_partner1_ca.example.com.pem \
    98100      my_partner2_ca.example.org.pem > ca.pem
    99101}}}
    100 From this point, we assume that you have a file '''ca.pem''' that contains all the trust anchors for your Diameter node.
    101 
    102 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'''.
    103 
    104 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:
    105 {{{
     102From 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).
     103
     104You 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 [ticket:29]). This CRL is saved as '''crl.pem'''.
     105
     106You 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:
     107{{{
     108#!sh
    106109$ openssl genrsa -out my_key.pem 2048
    107110}}}
    108111
    109 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):
    110  * 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.
    111  * The key usage must allow for TLS client and server usage.
     112Then, 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):
     113 * 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.
     114 * The key usage must allow for TLS client and server usages.
    112115The following example command will generate a CSR after asking a few questions:
    113116{{{
     117#!sh
    114118$ openssl req -new -out csr.pem -key my_key.pem
    115119}}}
    116120
    117 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.
    118 
    119 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):
    120 {{{
     121Once 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.
     122
     123If 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):
     124{{{
     125#!sh
    121126$ cat cert.pem my_group_ca.pem \
    122127       > certchain.pem
    … …  
    134139=== Testbed ===
    135140
    136 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.
     141In 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.
     142
     143The 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.
    137144
    138145==== Without TLS ====
    … …  
    143150This can be done with many tools, here is an example using ''openssl''.
    144151{{{
     152#!sh
    145153$ openssl req -new -batch -x509 -days 3650 -nodes     \
    146154   -newkey rsa:1024 -out cert.pem -keyout privkey.pem \
    … …  
    155163This again can be done with GNUTLS's ''certtool'' or OpenSSL. Here is an example command with the later:
    156164{{{
     165#!sh
    157166$ openssl dhparam -out dh.pem 1024
    158167}}}
    … …  
    176185If 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:
    177186{{{
     187#!sh
    178188$ cat peer1.cert.pem peer2.cert.pem > ca.pem
    179189}}}