From: Alan T. DeKok Date: Wed, 11 Aug 2021 14:04:25 +0000 (-0400) Subject: regenerate from raddb source X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=633f08ac0e3b0256c3bb9cfe7193fbd93e078466;p=thirdparty%2Ffreeradius-server.git regenerate from raddb source --- diff --git a/doc/antora/modules/raddb/pages/mods-available/cache_tls.adoc b/doc/antora/modules/raddb/pages/mods-available/cache_tls.adoc index 85c5f41fe5e..e25e455a194 100644 --- a/doc/antora/modules/raddb/pages/mods-available/cache_tls.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/cache_tls.adoc @@ -48,18 +48,6 @@ update
{ ... }:: -NOTE: If you want to store authorization attributes too, consider -performing LDAP/SQL lookups in the tls-cache virtual server and -storing the results in `&session-state`. - -The complete list can then be restored along with the -`Session-Data` using the entry below. - -Policies run in `post-auth` then have access to the same data -irrespective of whether the session is being resumed. - - - ### OCSP Session Configuration In addition to TLS sessions, the OCSP queries can be cached. @@ -84,8 +72,7 @@ cache cache_tls_session { key = &Session-Id ttl = 3600 # 60 mins update { - &session-state.Session-Data := &session-state.Session-Data -# &session-state += &session-state + &reply.Session-Data := &Session-Data } } cache cache_ocsp { diff --git a/doc/antora/modules/raddb/pages/mods-available/eap.adoc b/doc/antora/modules/raddb/pages/mods-available/eap.adoc index 751beb930d6..4ce6f856d27 100644 --- a/doc/antora/modules/raddb/pages/mods-available/eap.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/eap.adoc @@ -156,6 +156,64 @@ authenticate via EAP-TLS! This is likely not what you want. +[NOTE] +==== +As of 4.0 the following TLS config items/config sections have been +removed. Equivalent functionality is available. + +[options="header,autowidth"] +|=== +| Config item | Replacement + +| `verify_client_cert_cmd` +| Unlang policy in the `verify certificate { ... }` section of the specified `virtual_server`. + +| `check_cert_issuer` +| Unlang policy in the `verify certificate { ... }` section of the specified `virtual_server`. + +| `check_cert_cn` +| Unlang policy in the `verify certificate { ... }` section of the specified `virtual_server`. + +| `ocsp` +| rlm_ocsp call in the `verify certificate { ... }` section of the specified `virtual_server`. + +| `staple` +| rlm_ocsp call in the `staple certificate { ... }` section of the specified `virtual_server`. +|=== + + +virtual_server:: + +All certificate checks and stateful session resumption calls will be +made to the virtual server specified here. + +The virtual server must specify `namespace = tls`, and may contain +the following sections: + +[options="header,autowidth"] +|=== +| Section | Purpose + +| `load session { ... }` +| Load stateful session information from a cache. + +| `store session { ... }` +| Store stateful session information in a cache. + +| `clear session { ... }` +| Clear stateful session information from a cache. + +| `verify certificate { ... }` | +| Apply policies based on the client certificate presented. + +| `staple certificate { ... }` +| Gather stapling information for one or more of our certificates. +|=== + +More information about the various sections can be found in +link:../sites-available/tls.adoc[sites-available/tls]. + + auto_chain:: OpenSSL will automatically create certificate chains, unless @@ -388,55 +446,10 @@ fragment size should be `1024` or less. -check_crl:: Check the Certificate Revocation List. - -Will check CRLs for all certificates in the certificate chain. - -1. Copy CA certificates and CRLs to same directory. -2. Execute `c_rehash `. `c_rehash` is - OpenSSL's command. -3. uncomment the lines below. -4. Restart radiusd. - - - ca_path:: Full path to the CA file. -allow_expired_crl:: Accept an expired Certificate Revocation List. - - - -check_cert_issuer:: - -If `check_cert_issuer` is set, the value will be checked -against the DN of the issuer in the client certificate. If -the values do not match, the certificate verification will -fail, rejecting the user. - -This check can be done more generally by checking the value -of the `TLS-Client-Cert-Issuer` attribute. This check can be -done via any mechanism you choose. - - - -check_cert_cn:: - -If `check_cert_cn` is set, the value will be xlat'ed and -checked against the CN in the client certificate. If the -values do not match, the certificate verification will fail -rejecting the user. - -This check is done only if the previous `check_cert_issuer` -is not set, or if the check succeeds. - -This check can be done more generally by checking the value -of the `TLS-Client-Cert-Common-Name` attribute. This check can be done -via any mechanism you choose. - - - cipher_list:: Set this option to specify the allowed TLS cipher suites. @@ -499,22 +512,121 @@ openssl ecparam -list_curves -### TLS Session resumption +mode:: Which client certificates should be verified + +[options="header,autowidth"] +|=== +| Value | Description + +| `disabled` +| Don't verify any certificates. + +| `all` +| Verify all certificates. Check none have been + revoked via CRL, and that all are trusted. + +| `untrusted` +| Verify all untrusted certificates, + i.e. those which were presented by the client + and not loaded on startup. + +| `client-and-issuer` +| Verify the client certificate and its issuer. + +| `client` +| Only verify the client certificate. +|=== + +It is recommended to leave mode as `all` except +when debugging, or in an emergency situation. + +[NOTE] +==== +This verification is only applied during a full +handshake, and with stateful session resumption. +Verification for stateless session resumption +should be performed using the `verify [*] { ... }` +section(s) of the specified `virtual_server`. +==== + + + +attribute_mode:: Which client certificates should +be converted to attributes for use in the +`verify * { ... }` sections of the specified +`virtual_server`. + +Attributes created during certificate processing +will be placed in the `&session-state` list. +This is to simplify session-resumption, as the +contents of this list also contains session data +for stateful resumption, and this list is encoded +in the session-ticket for stateless resumption. + +[options="header,autowidth"] +|=== +| Value | Description + +| `disabled` +| Don't produce any attributes. + +| `all` +| Create attributes for all certificates from + the root, to the presented client certificate. -We currently support https://tools.ietf.org/html/rfc5246[RFC 5246] style TLS session resumption -only. +| `untrusted` +| Create attributes for untrusted certificates, + i.e. those which were presented by the client + and not loaded on startup. -Once authentication has completed the TLS client is provided -with a unique session identifier (or cookie) that it may -present during its next authentication attempt. +| `client-and-issuer` +| Create attributes for the client certificate + and its issuer. +| `client` -Presenting this identifier allows the client to skip the -majority of TLS tunnel setup during its next authentication -session. +| Only create attributes for the client + certificate. +|=== + +[NOTE] +==== +Attribute generation is only performed on full +handshake, or where we detect that attributes +are missing from the &session-state list during +stateful session-resumption. + +Certificate attributes will usually be retrieved +from the the session-ticket in the case of +stateless session-resumption. +==== + + + +check_crl:: Check the Certificate Revocation List. + +Will check CRLs for all certificates in the certificate chain. + +1. Copy CA certificates and CRLs to same directory. +2. Execute `c_rehash `. `c_rehash` is + OpenSSL's command. +3. uncomment the lines below. +4. Restart radiusd. + + + +allow_expired_crl:: Accept an expired Certificate Revocation List. + + +### TLS Session resumption + +Once authentication has completed the TLS client may be +provided with a unique session identifier (stateful resumption) +or a session-ticket (stateless resumption) that it may present +during its next authentication attempt. -Resuming a TLS session avoids the certificate exchange and in -the case `PEAP` and `TTLS`, allows the client to skip the inner -`EAP` method. +Presenting a session identifier or session-ticket allows the +client to skip the majority of TLS tunnel setup during its next +authentication session. Enabling `Session-Resumption` is highly recommended for sites using slow authentication backends such as winbindd/Active @@ -523,30 +635,50 @@ internet, such as Eduroam. NOTE: You must ensure any attributes required for policy decisions are cached at the same time as the TLS session -data. See link:../sites-available/tls-cache.adoc[sites-available/tls-cache] for documentation on -how TLS cache now works. - -If using the default `tls-cache` virtual server and -cache module config, policy attributes may be stored in the -`&session-state.` list. - - -virtual_server:: - -To enable session resumption, uncomment the virtual -server entry below, and link -link:../sites-available/tls-cache.adoc[sites-available/tls-cache] to `sites-enabled/tls-cache`. +data. This is usually done by placing policy attributes in the +`&session-state` list, or in the case of EAP-PEAP, EAP-TTLS and +EAP-FAST, the `&parent.session-state` list (i.e. in the request +that represents the TLS part of the authentication attempt), +so that they are cached at the same time as the session resumption +data. -You can disallow resumption for a particular user by -adding the following attribute to the control item -list: - Allow-Session-Resumption = No +mode:: What type of session caching should be allowed. -NOTE: If no virtual_server is specified you *CANNOT* enable -resumption for just one user by setting the above -attribute to `yes`. +[options="header,autowidth"] +|=== +| Value | Description + +| `disabled` +| Don't allow any kind of session resumption. + +| `stateful` +| Use <= TLS 1.2 style stateful session resumption. + A unique session-identifier is provided to the client. + The client provides this identifier during the next + authentication attempt, and we lookup session information + based on this identifier. + A `virtual_server` with `load session { ... }`, + `store session { ... }` and `clear session { ... }` + sections must be configured. + +| `stateless` +| Allow session-ticket based resumption. This requires no + external support. All information required for resumption + is sent to the TLS client in an encrypted session-ticket. + The client returns this ticket during the next + authentication attempt. + +| `auto` +| Choose an appropriate session resumption type based on + the TLS version used and whether a `virtual_server` is + configured and has the required `session` sections. +|=== +It is recommended to set `mode = auto` *and* provide a +correctly configured `virtual_server`. wpa_supplicant +does not request/allow session tickets by default for +TLS < 1.3. name:: Name of the context TLS sessions are created under. @@ -568,27 +700,11 @@ the value provided here is digested with SHA256. lifetime:: The period for which a resumable session remains valid. -The actual period is the lower of this value, and the -ttl set in `rlm_cache`. Default is 24hrs inline with https://tools.ietf.org/html/rfc4346[RFC 4346]. -verify:: Revalidate client's certificate chain each time -a session is resumed. - -Intermediaries provided by the client are not cached, -or copied to the server's certificate store, so -rebuilding the certificate chain will fail if we don't -have the intermediaries loaded from `ca_file` or `ca_path`. - -This is useful with long cache lifetimes, where a -certificate may be revoked in the interim between the -session being created and re-used. - - - require_extended_master_secret:: Only allow session resumption if an extended master @@ -618,9 +734,10 @@ As of 4.0 OpenSSL's internal cache has been disabled due to scoping/threading issues. The following configuration options are deprecated. TLS -session caching is now handled by the `cache` module. -That module is more configurable, and has more back-ends -than the simple configurations below. +session caching is now handled by FreeRADIUS +either using session-tickets (stateless), or using TLS +`virtual_server` and storing/retrieving sessions to/from +an external datastore (stateful). * `enable` * `persist_dir` @@ -629,255 +746,6 @@ than the simple configurations below. -### Dynamic CRLs or OCSP - -As of version 2.1.10, client certificates can be validated -via an external command. This allows dynamic CRLs or OCSP to -be used. - -This configuration is commented out in the default -configuration. Uncomment it, and configure the correct paths -below to enable it. - - -tmpdir:: - -A temporary directory where the client certificates -are stored. This directory MUST be owned by the UID -of the server, and MUST not be accessible by any -other users. When the server starts, it will do -`chmod go-rwx` on the directory, for security -reasons. The directory MUST exist when the server -starts. - -You should also delete all of the files in the -directory when the server starts. - - - -client:: - -The command used to verify the client cert. We -recommend using the OpenSSL command-line tool. - -The `${..ca_path}` text is a reference to the ca_path -variable defined above. - -The `%{TLS-Client-Cert-Filename}` is the name of the -temporary file containing the cert in PEM format. -This file is automatically deleted by the server when -the command returns. - - - -### OCSP Configuration - -Certificates can be verified against an OCSP Responder. -This makes it possible to immediately revoke certificates without -the distribution of new Certificate Revocation Lists (CRLs). - -In addition to the configuration items below, the behaviour of -OCSP can be altered by runtime attributes. - -If OCSP is enabled, the `&reply.TLS-OCSP-Cert-Valid` attribute will -be added after OCSP completes. One of the following values will -be set: - -[options="header,autowidth"] -|=== -| Value | Description -| no | OCSP responder indicated the certificate is not valid. -| yes | OCSP responder indicated the certificate is valid. -| skipped | OCSP checks were skipped. -|=== - -If an OCSP check is performed, the `&reply.TLS-OCSP-Next-Update` -attribute will also be added. The value of this will attribute -be the number of seconds until the certificate state need be refreshed. -This can be used as a `Cache-TTL` value if you wish to use the cache -module to store OCSP certificate validation status. - -If when the OCSP check is performed, a `&control.TLS-OCSP-Cert-Valid` -attribute is present, its value will force the outcome of the OCSP -check, and the OCSP responder will not be contacted. -Values map to the following OCSP responses: - -[options="header,autowidth"] -|=== -| Value | Description -| no | Invalid. -| yes | Valid. -| skipped | If `softfail = yes` value else invalid. -|=== - - -enable:: - -Deleting the entire `ocsp` subsection also disables ocsp checking. - -Default is `no`. - - - -virtual_server:: - -OCSP checks are performed immediately after the -complete certificate is received from the supplicant, -and directly after the attributes from that -certificate are inserted into the request. - -In order to retrieve cached OCSP states, a virtual -server must be defined here. - -See `raddb/sites-available/tls-cache` for details. - - - -override_cert_url:: - -The OCSP Responder URL can be automatically extracted -from the certificate in question. To override the -OCSP Responder URL set `override_cert_url = yes`. - - - -url:: - -If the OCSP Responder address is not extracted from -the certificate, the URL can be defined here. - - - -use_nonce:: - -If the OCSP Responder can not cope with nonce in the -request, then it can be disabled here. - -[WARNING] -==== - * For security reasons, disabling this option is not -recommended as nonce protects against replay attacks. - - * Microsoft AD Certificate Services OCSP -Responder does not enable nonce by default. It is more -secure to enable nonce on the responder than to -disable it in the query here. - -See http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx -==== - - - -timeout:: - -Number of seconds before giving up waiting for OCSP -response. - -Default is `0`. - - - -softfail:: - -Normally an error in querying the OCSP responder (no -response from server, server did not understand the -request, etc) will result in a validation failure. - -To treat these errors as `soft` failures and still -accept the certificate, enable this option. - -WARNING: this may enable clients with revoked -certificates to connect if the OCSP responder is not -available. *Use with caution*. - - - -### OCSP stapling for server certificates - -If requested, we query either the server listed below (as url), -or the one specified in our server certificate, to retrieve an -OCSP response to pass back to the TLS client. - -staple { ... }:: - -This allows TLS clients to check for certificate revocation before -divulging credentials to a (possibly rogue) server, that may be -presenting a compromised certificate. - - -enable:: - -Enable it. Deleting the entire `ocsp` subsection also disables ocsp checking. - -Default is `no`. - - - -virtual_server:: - -OCSP checks are performed whenever a TLS client includes -an OCSP stapling extension. - -In order to retrieve cached OCSP staples, a virtual -server must be defined here. - -The same virtual server can be used for caching -client OCSP response states, and stapling information. - -See `raddb/sites-available/tls-cache` for details. - - - -override_cert_url:: - -The OCSP Responder URL can be automatically extracted -from the certificate in question. To override the -OCSP Responder URL set `override_cert_url = yes`. - - - -url:: - -If the OCSP Responder address is not extracted from -the certificate, the URL can be defined here. - - - -use_nonce:: - -If the OCSP Responder can not cope with nonce in the -request, then it can be disabled here. - -[WARNING] -==== - * For security reasons, disabling this option is not -recommended as nonce protects against replay attacks. - - * Microsoft AD Certificate Services OCSP -Responder does not enable nonce by default. It is more -secure to enable nonce on the responder than to -disable it in the query here. See -http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx -==== - - - -Number of seconds before giving up waiting for OCSP -response. - -Default is `0`. - - - -softfail:: - -Normally if we can't query the OCSP Responder -we issue a fatal alert, and abort. Set this to `true` -to allow the session to continue without an OCSP -stapling response being sent to the TLS client. - - - ### EAP-TLS As of Version 3.0, the TLS configuration for `TLS-based` @@ -914,15 +782,6 @@ included ONLY in the First packet of a fragment series. -virtual_server:: - -As part of checking a client certificate, the `EAP-TLS` sets -some attributes such as `TLS-Client-Cert-Common-Name`. This virtual -server has access to these attributes, and can be used to -accept or reject the request. - - - ### EAP-TTLS The TTLS module implements the `EAP-TTLS` protocol, which can be @@ -1283,57 +1142,6 @@ research purposes where programmable or virtual SIM cards are in use. -request_identity:: Send a SIM-Start message to Requests -an additional identity to the one from the EAP-Identity-Response. - -If `yes` - We send a request with AT_SUBTYPE SIM-start -with an AT_ANY_ID_REQ attribute to prompt the supplicant -to send a new identity. - -The type of identity requested can be controlled by adding -one of the following attributes from the -`recv Identity-Response { ... }` section of the specified -EAP-SIM virtual_server, to the reply list: - -- &reply.Any-Id-Req -- &reply.Fullauth-Id-Req -- &reply.Permanent-Id-Req - -Even if this configuration item is set to 'no', additional -identities can be requested by policy. -See sites-available/eap-aka-sim for details. - - - -ephemeral_id_length:: The length of any pseudonyms or -fastauth identities we generate (not including hint byte). - -See sites-available/eap-aka-sim for details on how to trigger -the generation of pseudonym or fastauth identities. - - - -strip_permanent_identity_hint:: Strip the identity hint when -copying &EAP-Identity or &Identity to &Permanent-Identity. - -The stripping is only performed if this config item is set -to yes, and the hint byte matches what we'd expect for the -EAP-Method being executed. - - - -protected_success:: Send a protected success message. - -If `yes` - indicate to the peer that we'd like to send -a protected success message. If the peer agrees and -authentication succeeds, send a `SIM-Notification` (Success) -packet protected with an `AT_MAC` attribute. - -After the Notification is ACKed by the peer, we send -the final `EAP-Success` packet containing `MPPE` keys. - - - virtual_server:: EAP-SIM virtual server containing policy sections. This must be set, EAP-SIM will not function without it, as certain operations like vector gathering @@ -1344,64 +1152,6 @@ require user configuration. ### EAP-AKA -protected_success:: Send protected success messages - - - -virtual_server:: Same as for `TTLS`, `PEAP`, etc. - - -request_identity:: Send a AKA-Identity message to request -an additional identity to the one from the EAP-Identity-Response. - -If `yes` - We send a request with AT_SUBTYPE AKA-Identity -with an AT_ANY_ID_REQ attribute to prompt the supplicant -to send a new identity. - -The type of identity requested can be controlled by adding -one of the following attributes from the -`recv Identity-Response { ... }` section of the specified -EAP-AKA virtual_server, to the reply list: - -- &reply.Any-Id-Req -- &reply.Fullauth-Id-Req -- &reply.Permanent-Id-Req - -Even if this configuration item is set to 'no', additional -identities can be requested by policy. -See sites-available/eap-aka-sim for details. - - - -ephemeral_id_length:: The length of any pseudonyms or -fastauth identities we generate (not including hint byte). - -See sites-available/eap-aka-sim for details on how to trigger -the generation of pseudonym or fastauth identities. - - - -strip_permanent_identity_hint:: Strip the identity hint when -copying &EAP-Identity or &Identity to &Permanent-Identity. - -The stripping is only performed if this config item is set -to yes, and the hint byte matches what we'd expect for the -EAP-Method being executed. - - - -protected_success:: Send a protected success message. - -If `yes` - indicate to the peer that we'd like to send -a protected success message. If the peer agrees and -authentication succeeds, send a `AKA-Notification` (Success) -packet protected with an `AT_MAC` attribute. - -After the Notification is ACKed by the peer, we send -the final `EAP-Success` packet containing `MPPE` keys. - - - prefer_aka_prime:: Send the AT_BIDDING attribute in AKA-Challenge messages. @@ -1426,73 +1176,6 @@ require user configuration. ### EAP-AKA-Prime -network_name:: The default value used for AT_KDF_INPUT - -EAP-AKA-Prime mixes various keys with a network identifier -specifying the user's point of connection into the network -to prevent vectors being used where they were not intended -to be. - -The value of the AT_KDF_INPUT can be overridden in the -eap-aka-prime virtual server with &reply.KDF-Input if -this value needs to be determined dynamically. - -How this value should be created and formatted is specified -in 3GPP.24.302. - - - -request_identity:: Send a AKA-Identity message to request -an additional identity to the one from the EAP-Identity-Response. - -If `yes` - We send a request with AT_SUBTYPE AKA-Identity -with an AT_ANY_ID_REQ attribute to prompt the supplicant -to send a new identity. - -The type of identity requested can be controlled by adding -one of the following attributes from the -`recv Identity-Response { ... }` section of the specified -EAP-AKA virtual_server, to the reply list: - -- &reply.Any-Id-Req -- &reply.Fullauth-Id-Req -- &reply.Permanent-Id-Req - -Even if this configuration item is set to 'no', additional -identities can be requested by policy. -See sites-available/eap-aka-sim for details. - - - -ephemeral_id_length:: The length of any pseudonyms or -fastauth identities we generate (not including hint byte). - -See sites-available/eap-aka-sim for details on how to trigger -the generation of pseudonym or fastauth identities. - - - -strip_permanent_identity_hint:: Strip the identity hint when -copying &EAP-Identity or &Identity to &Permanent-Identity. - -The stripping is only performed if this config item is set -to yes, and the hint byte matches what we'd expect for the -EAP-Method being executed. - - - -protected_success:: Send a protected success message. - -If `yes` - indicate to the peer that we'd like to send -a protected success message. If the peer agrees and -authentication succeeds, send a `AKA-Notification` (Success) -packet protected with an `AT_MAC` attribute. - -After the Notification is ACKed by the peer, we send -the final `EAP-Success` packet containing `MPPE` keys. - - - virtual_server:: EAP-AKA virtual server containing policy sections. This must be set, EAP-AKA-Prime will not function without it, as certain operations like vector gathering @@ -1628,6 +1311,7 @@ eap { auth_type = PAP } tls-config tls-common { +# virtual_server = tls # auto_chain = no chain rsa { # format = "PEM" @@ -1650,52 +1334,30 @@ eap { # psk_query = "%{sql:select hex(key) from psk_keys where keyid = '%{TLS-PSK-Identity}'}" dh_file = ${certdir}/dh # fragment_size = 1024 -# check_crl = yes ca_path = ${cadir} -# allow_expired_crl = no -# check_cert_issuer = "/C=GB/ST=Berkshire/L=Newbury/O=My Company Ltd" -# check_cert_cn = %{User-Name} cipher_list = "DEFAULT" cipher_server_preference = yes # tls_max_version = 1.2 # tls_min_version = 1.2 ecdh_curve = prime256v1 + verify { +# mode = all +# attribute_mode = client-and-issuer +# check_crl = yes +# allow_expired_crl = no + } cache { -# virtual_server = 'tls-cache' +# mode = auto # name = "%{EAP-Type}%{Virtual-Server}" # lifetime = 86400 -# verify = no # require_extended_master_secret = yes # require_perfect_forward_secrecy = no } - verify { -# tmpdir = /tmp/radiusd -# client = "/path/to/openssl verify -CApath ${..ca_path} %{TLS-Client-Cert-Filename}" - } - ocsp { -# enable = no -# virtual_server = 'tls-cache' - override_cert_url = yes - url = "http://127.0.0.1/ocsp/" -# use_nonce = yes -# timeout = 0 -# softfail = no - } - staple { -# enable = no -# virtual_server = 'tls-cache' - override_cert_url = yes - url = "http://127.0.0.1/ocsp/" -# use_nonce = yes -# timeout = 0 -# softfail = no - } } tls { tls = tls-common # require_client_cert = yes # include_length = yes -# virtual_server = check-eap-tls } ttls { tls = tls-common @@ -1728,28 +1390,13 @@ eap { # default_provisioning_eap_type = mschapv2 } sim { -# request_identity = no -# ephemeral_id_length = 14 -# strip_permanent_identity_hint = yes -# protected_success = yes virtual_server = eap-aka-sim } aka { -# protected_success = no -# virtual_server = "" -# request_identity = no -# ephemeral_id_length = 14 -# strip_permanent_identity_hint = yes -# protected_success = yes # prefer_aka_prime = yes virtual_server = eap-aka-sim } aka-prime { -# network_name = "" -# request_identity = no -# ephemeral_id_length = 14 -# strip_permanent_identity_hint = yes -# protected_success = yes virtual_server = eap-aka-sim } } diff --git a/doc/antora/modules/raddb/pages/mods-available/echo.adoc b/doc/antora/modules/raddb/pages/mods-available/echo.adoc index c08064c7816..3789b8f214e 100644 --- a/doc/antora/modules/raddb/pages/mods-available/echo.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/echo.adoc @@ -4,19 +4,14 @@ = Echo Module -The `echo` module is an example of the `exec` module, configured with -its `program` configuration item set so it can be called as any other -module i.e. +The `echo` module an example of the `exec` module configured +with a `program` configuration item set so it can be called +as any other module, i.e. echo -The sample `program` in the default configuration is a trivial example -and should be replaced with something more meaningful. - -Arguments can be supplied to the program on the command line, with the -value of `program` being dynamically expanded. In addition, setting -`input_pairs` causes the corresponding list of attributes to be placed -in environment variables. +The sample `program` below is a trivial example and should be replaced +with something more meaningful. The return value of the program run determines the result of the exec instance call as follows: @@ -68,6 +63,9 @@ the following example will work. input_pairs:: The attributes which are placed into the environment variables for the program. +If your program does not require access to values from +environment variables, then do not set this. + Allowed values are: [options="header,autowidth"] diff --git a/doc/antora/modules/raddb/pages/mods-available/exec.adoc b/doc/antora/modules/raddb/pages/mods-available/exec.adoc index b3388542923..c89804416cb 100644 --- a/doc/antora/modules/raddb/pages/mods-available/exec.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/exec.adoc @@ -16,21 +16,21 @@ The value of the attribute will be replaced with the output of the program which is executed. Due to RADIUS protocol limitations, any output over `253` bytes will be ignored. -The RADIUS attributes from the attribute list specified in the -configuration item `input_list` will be placed -into environment variables of the executed program, as -described in `man unlang` and in `doc/unlang/xlat.adoc` +The RADIUS attributes from the list referenced in the `input_pairs` +configuraton item will be placed into environment variables of the executed +program, as described in `man unlang` and in `doc/unlang/xlat.adoc` -Alternatively to using the `xlat`, by setting the `program` configuration, -item, the module can be called as a module. +Alternatively, by setting the `program` item of the module configuration, +the module can be called as a module rather than as an xlat function. +See the `echo` module for an example of this. -In this scenario, the output of executing the program will be parsed for -attribute pairs which will be added to the list referenced in the -`output_pairs` configuration item, if the `wait` configuration item -is set to "yes". +In this scenario, if the configuration item `output_pairs` is set, +and the `wait` configuration item is set to "yes", the output of +executing the program will be parsed for attribute pairs which +will be added to the list referenced in `output_pairs`. -The return value of the program run determines the result of the exec -instance call as follows: +When called as a module, the return value of the program run determines +the result of the exec instance call as follows: [options="header,autowidth"] |=== @@ -57,18 +57,18 @@ instance call as follows: wait:: Wait for the program to finish. If we do NOT wait, then the program is "fire and -forget", and any output from it is ignored. +forget", and any output attributes from it are ignored. -program:: The name of the program to execute, and its -arguments. +program:: The name of the program to execute, and it's +arguments, when called as a module. Dynamic translation is done on this field, so things like +the following example will work. - program = "/bin/true %{User-Name}" +See the `echo` module for examples of how to use the module "in line". -will work. input_pairs:: The attributes which are placed into the diff --git a/doc/antora/modules/raddb/pages/mods-available/json.adoc b/doc/antora/modules/raddb/pages/mods-available/json.adoc index 45ff62297b8..38cf008cd4d 100644 --- a/doc/antora/modules/raddb/pages/mods-available/json.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/json.adoc @@ -34,12 +34,10 @@ Selectors currently implemented are: * Automatic casting will occur between JSON and attribute types where possible. * Assignment of JSON objects/arrays to strings is supported, in which case the JSON serialized form of the object/array is used. - * If a jpath matches multiple nodes, unless the map includes the `+=` or `^=` - operator only the first node's value will be used. - * If the map uses `+=` or `^=` then multiple instances of the attribute will be - created, each holding a different node value. - * If the map uses `^=` then any new instances will be inserted at the head of - of the list. + * If a jpath matches multiple nodes, unless the map includes the `+=` operator + * only the first node's value will be used. + * If the map uses `+=` then multiple instances of the attribute will be created, + each holding a different node value. ==== diff --git a/doc/antora/modules/raddb/pages/mods-available/mschap.adoc b/doc/antora/modules/raddb/pages/mods-available/mschap.adoc index a1629b1e798..a46d38c6716 100644 --- a/doc/antora/modules/raddb/pages/mods-available/mschap.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/mschap.adoc @@ -7,7 +7,7 @@ The `mschap` module performs `MS-CHAP` and `MS-CHAPv2` authentication. MS-CHAP authentication requires access to either the -Password.Cleartext or NT-Password attribute for the user. Due to +Password.Cleartext or Password.NT attribute for the user. Due to the limitations of MS-CHAP, no other password "encryption" methods are possible. @@ -20,7 +20,20 @@ The module also enforces the `SMB-Account-Ctrl` attribute. See the Samba documentation for the meaning of SMB account control. The module does not read Samba password files. Instead, the rlm_passwd module can be used to read a Samba password file, and then supply -an `NT-Password` attribute which this module can use. +an `Password.NT` attribute which this module can use. + +The `mschap` module registers a few `xlat` functions. + +[options="header,autowidth"] +|=== +| Function | Description +| `Challenge` | The MS-CHAP challenge. +| `Domain-Name` | The full domain name, taken from the `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]` attribute +| `NT-Domain` | The NT domain portion of the domain name, taken from the `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]` attribute +| `NT-Hash` | Take the NT-Hash of the string passed into the xlat +| `NT-Response` | The MS-CHAP response. +| `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]` | The MS-CHAP username portion of the `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]` attribute. +|=== [NOTE] ==== diff --git a/doc/antora/modules/raddb/pages/mods-available/perl.adoc b/doc/antora/modules/raddb/pages/mods-available/perl.adoc index d6b2cb9ff60..f15efb9f890 100644 --- a/doc/antora/modules/raddb/pages/mods-available/perl.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/perl.adoc @@ -15,6 +15,7 @@ included in your module. If the module is called for a section which does not have a function defined, it will return `noop`. + ## Configuration Settings The following hashes are given to the module and @@ -124,29 +125,3 @@ perl { # } } ``` - -## xlat for calling arbitrary Perl subroutines - -An xlat based on the instance name can be called to run arbitrary subroutines -declared in the perl file configured in the instance. The xlat takes the -subroutine name as its first argument and then any subsequent arguments are -passed as string scalars to the subroutine. If any of the arguments are -lists with multiple values e.g. `%{User-Name[*]}` where there are multiple -instances of `User-Name` then those arguments will be passed as references -to arrays containing all the values from the list. - -The return value of the subroutine is passed back as the expanded value of -the xlat. Since the subroutine is called in array context, all returned values -are received, though currently they are concatenated to form a single value. -This is due to change in the future. - -NOTE: The Perl xlat does not have access to the attribute lists, nor will -setting the hashes update the attribute lists. - -.Example - -``` -update control { - &Tmp-String-0 := "%(perl:myfunc arg1 arg2)" -} -``` diff --git a/doc/antora/modules/raddb/pages/mods-available/rest.adoc b/doc/antora/modules/raddb/pages/mods-available/rest.adoc index 44509794f00..a2836f31305 100644 --- a/doc/antora/modules/raddb/pages/mods-available/rest.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/rest.adoc @@ -247,7 +247,10 @@ The response format adds three optional fields: | `is_json` | If `true`, any nested JSON data will be copied to the attribute in string form. Defaults to `true`. | `op` | Controls how the attribute is inserted into the target list. - Defaults to `:=`. + Defaults to `:=`. To create multiple attributes from multiple + values, this should be set to `+=`, otherwise only the last + value will be used, and it will be assigned to a single + attribute. |=== [source,json] @@ -426,30 +429,6 @@ or increase lifetime/idle_timeout. ==== -## xlat for REST calls - -An xlat based on the instance name can be used to perform REST calls. - -.Example - -``` -%(rest:http://www.example.com/) -%(rest:GET https://www.example.com/user/%{User-Name}) -%(rest:POST https://www.example.com/auth/%{User-Name} %{Called-Station-Id}) -``` - -The xlat takes up to 3 arguments: - - * Method - * URI - * Body data - -If only one argument is presented, that will be taken as the URI and the -method will default to GET. - -Any attributes in the xlat read from the request packet will be escaped. - - == Default Configuration ``` diff --git a/doc/antora/modules/raddb/pages/mods-available/unbound.adoc b/doc/antora/modules/raddb/pages/mods-available/unbound.adoc index 63cf5fe228d..de55d9dbeb0 100644 --- a/doc/antora/modules/raddb/pages/mods-available/unbound.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/unbound.adoc @@ -11,19 +11,29 @@ FQDNs to be resolved during request processing. ## Configuration Settings -filename:: libunbound configuration file. See `man unbound.conf` for -details of options which can be set in this file. -Defaults to `"${raddbdir}/mods-config/unbound/default.conf"` +File to read unbound configuration details from. -timeout:: maximum time to wait for a DNS resolution. +filename = "${raddbdir}/mods-config/unbound/default.conf" -Defaults to 3000 -resolvconf:: resolv.conf file to load. Without this set unbound will -query root servers. +Timeout for unbound queries. + +timeout = 3000 + + +resolv.conf file to instruct unbound to load resolvers from. +Defaults to not set. +Without this set, unbound queries root DNS servers. If a local +caching DNS server is available that will improve performance. + +resolvconf = "/etc/resolv.conf" + + +hosts file to load data from. Defaults to not set. + +hosts = "/etc/hosts" -hosts:: hosts file to load. ## xlat for DNS resolution @@ -37,7 +47,7 @@ An xlat based on the instance name can be used to perform DNS lookups. ``` Given an instance `dns` the above xlats will perform A record and -AAA record lookups on www.example.com +AAAA record lookups on www.example.com. .Example @@ -48,12 +58,13 @@ AAA record lookups on www.example.com The above example will perform reverse DNS lookup on 192.168.1.1 .Example + ``` %(dns:example.com MX 1) ``` -The above example will perform an MX lookup on example.com only -returning the first record. +The above example will perform an MX lookup on example.com returning +just the first result. == Default Configuration diff --git a/doc/antora/modules/raddb/pages/sites-available/default.adoc b/doc/antora/modules/raddb/pages/sites-available/default.adoc index 9b0b73f1498..f88e2b01837 100644 --- a/doc/antora/modules/raddb/pages/sites-available/default.adoc +++ b/doc/antora/modules/raddb/pages/sites-available/default.adoc @@ -983,7 +983,6 @@ available). - Insert the `link:https://freeradius.org/rfc/rfc2865.html#Class[Class]` attribute with a unique value into the response, which aids matching auth and acct records and protects against duplicate Acct-Session-Id. @@ -1411,12 +1410,12 @@ send Access-Accept { # } # wimax # update reply { -# &Reply-Message += "%{session-state.TLS-Cert-Serial}" -# &Reply-Message += "%{session-state.TLS-Cert-Not-After}" -# &Reply-Message += "%{session-state.TLS-Cert-Subject}" -# &Reply-Message += "%{session-state.TLS-Cert-Issuer}" -# &Reply-Message += "%{session-state.TLS-Cert-Common-Name}" -# &Reply-Message += "%{session-state.TLS-Cert-Subject-Alt-Name-Email}" +# &Reply-Message += "%{session-state.TLS-Certificate.Serial}" +# &Reply-Message += "%{session-state.TLS-Certificate.Not-After}" +# &Reply-Message += "%{session-state.TLS-Certificate.Subject}" +# &Reply-Message += "%{session-state.TLS-Certificate.Issuer}" +# &Reply-Message += "%{session-state.TLS-Certificate.Common-Name}" +# &Reply-Message += "%{session-state.TLS-Certificate.Subject-Alt-Name-Email}" # } # insert_acct_class # if (&reply.EAP-Session-Id) { diff --git a/doc/antora/modules/raddb/pages/sites-available/detail.adoc b/doc/antora/modules/raddb/pages/sites-available/detail.adoc index 53e2fab6446..fce7825e894 100644 --- a/doc/antora/modules/raddb/pages/sites-available/detail.adoc +++ b/doc/antora/modules/raddb/pages/sites-available/detail.adoc @@ -14,6 +14,11 @@ following directory. +The "listen" section MUST have a second name here, which +says "load the detail file processor, and not the typical +RADIUS UDP / TCP socket IO. + + Types of packets we are reading. @@ -231,7 +236,7 @@ configuration. server detail { namespace = radius directory = ${radacctdir}/detail - listen { + listen detail { type = Accounting-Request # priority = 1 file { @@ -254,7 +259,7 @@ server detail { } recv Accounting-Request { update request { - &Acct-Delay-Time := "%{expr:%{%{Acct-Delay-Time}:-0} + %c - %{%(integer:%{Event-Timestamp}):-%(integer:%{Packet-Original-Timestamp})}}" + &Acct-Delay-Time := "%{expr:%{%{Acct-Delay-Time}:-0} + %c - %(integer:%{%{Event-Timestamp}:-%{Packet-Original-Timestamp}})}" } ok } diff --git a/doc/antora/modules/raddb/pages/sites-available/eap-aka-sim.adoc b/doc/antora/modules/raddb/pages/sites-available/eap-aka-sim.adoc index 61938048bdb..4356538af95 100644 --- a/doc/antora/modules/raddb/pages/sites-available/eap-aka-sim.adoc +++ b/doc/antora/modules/raddb/pages/sites-available/eap-aka-sim.adoc @@ -43,8 +43,8 @@ will instead generate a warning: - `recv Success-Notification` sending failure after EAP-Response/ - `recv Authentication-Reject` already rejecting the auth attempt. - `recv Client-Error` already rejecting the auth attempt. -- `clear Pseudonym` nothing more we can do... -- `clear Session` nothing more we can do... +- `clear pseudonym` nothing more we can do... +- `clear session` nothing more we can do... For sections dealing with identity processing the `notfound` rcode will trigger identity negotiation. The EAP-AKA module will then request @@ -67,6 +67,182 @@ additional identity processing sections are used. +request_identity:: Send a SIM-Start message to Requests +an additional identity to the one from the EAP-Identity-Response. + +If `yes` - We send a request with AT_SUBTYPE SIM-start +with an AT_ANY_ID_REQ attribute to prompt the supplicant +to send a new identity. + +The type of identity requested can be controlled by adding +one of the following attributes from the +`recv Identity-Response { ... }` section of the specified +EAP-SIM virtual_server, to the reply list: + +- &reply.Any-Id-Req +- &reply.Fullauth-Id-Req +- &reply.Permanent-Id-Req + +Even if this configuration item is set to 'no', additional +identities can be requested by policy. +See sites-available/eap-aka-sim for details. + + + +ephemeral_id_length:: The length of any pseudonyms or +fastauth identities we generate (not including hint byte). + +See sites-available/eap-aka-sim for details on how to trigger +the generation of pseudonym or fastauth identities. + + + +strip_permanent_identity_hint:: Strip the identity hint when +copying &EAP-Identity or &Identity to &Permanent-Identity. + +The stripping is only performed if this config item is set +to yes, and the hint byte matches what we'd expect for the +EAP-Method being executed. + + + +protected_success:: Send a protected success message. + +If `yes` - indicate to the peer that we'd like to send +a protected success message. If the peer agrees and +authentication succeeds, send a `SIM-Notification` (Success) +packet protected with an `AT_MAC` attribute. + +After the Notification is ACKed by the peer, we send +the final `EAP-Success` packet containing `MPPE` keys. + + + +protected_success:: Send protected success messages + + + +virtual_server:: Same as for `TTLS`, `PEAP`, etc. + + +request_identity:: Send a AKA-Identity message to request +an additional identity to the one from the EAP-Identity-Response. + +If `yes` - We send a request with AT_SUBTYPE AKA-Identity +with an AT_ANY_ID_REQ attribute to prompt the supplicant +to send a new identity. + +The type of identity requested can be controlled by adding +one of the following attributes from the +`recv Identity-Response { ... }` section of the specified +EAP-AKA virtual_server, to the reply list: + +- &reply.Any-Id-Req +- &reply.Fullauth-Id-Req +- &reply.Permanent-Id-Req + +Even if this configuration item is set to 'no', additional +identities can be requested by policy. +See sites-available/eap-aka-sim for details. + + + +ephemeral_id_length:: The length of any pseudonyms or +fastauth identities we generate (not including hint byte). + +See sites-available/eap-aka-sim for details on how to trigger +the generation of pseudonym or fastauth identities. + + + +strip_permanent_identity_hint:: Strip the identity hint when +copying &EAP-Identity or &Identity to &Permanent-Identity. + +The stripping is only performed if this config item is set +to yes, and the hint byte matches what we'd expect for the +EAP-Method being executed. + + + +protected_success:: Send a protected success message. + +If `yes` - indicate to the peer that we'd like to send +a protected success message. If the peer agrees and +authentication succeeds, send a `AKA-Notification` (Success) +packet protected with an `AT_MAC` attribute. + +After the Notification is ACKed by the peer, we send +the final `EAP-Success` packet containing `MPPE` keys. + + + +network_name:: The default value used for AT_KDF_INPUT + +EAP-AKA-Prime mixes various keys with a network identifier +specifying the user's point of connection into the network +to prevent vectors being used where they were not intended +to be. + +The value of the AT_KDF_INPUT can be overridden in the +eap-aka-prime virtual server with &reply.KDF-Input if +this value needs to be determined dynamically. + +How this value should be created and formatted is specified +in 3GPP.24.302. + + + +request_identity:: Send a AKA-Identity message to request +an additional identity to the one from the EAP-Identity-Response. + +If `yes` - We send a request with AT_SUBTYPE AKA-Identity +with an AT_ANY_ID_REQ attribute to prompt the supplicant +to send a new identity. + +The type of identity requested can be controlled by adding +one of the following attributes from the +`recv Identity-Response { ... }` section of the specified +EAP-AKA virtual_server, to the reply list: + +- &reply.Any-Id-Req +- &reply.Fullauth-Id-Req +- &reply.Permanent-Id-Req + +Even if this configuration item is set to 'no', additional +identities can be requested by policy. +See sites-available/eap-aka-sim for details. + + + +ephemeral_id_length:: The length of any pseudonyms or +fastauth identities we generate (not including hint byte). + +See sites-available/eap-aka-sim for details on how to trigger +the generation of pseudonym or fastauth identities. + + + +strip_permanent_identity_hint:: Strip the identity hint when +copying &EAP-Identity or &Identity to &Permanent-Identity. + +The stripping is only performed if this config item is set +to yes, and the hint byte matches what we'd expect for the +EAP-Method being executed. + + + +protected_success:: Send a protected success message. + +If `yes` - indicate to the peer that we'd like to send +a protected success message. If the peer agrees and +authentication succeeds, send a `AKA-Notification` (Success) +packet protected with an `AT_MAC` attribute. + +After the Notification is ACKed by the peer, we send +the final `EAP-Success` packet containing `MPPE` keys. + + + ### `recv Identity-Response { ... }` - Process an EAP-Identity-Response or AKA-Identity value This is usually the first section called when starting a new EAP-AKA @@ -306,6 +482,9 @@ values: NOTE: Add a `&reply.Next-Pseudonym-Id` attribute in this section to avoid having the permanent Id of the SIM exposed during subsequent authentication attempts. +The value of this attribute may be empty (a zero length string) if +which case a random value with the correct hint character will be +generated for you. ### Fast-Reauth @@ -320,6 +499,9 @@ authentication attempts. NOTE: Add a `&reply.Next-Reauth-Id` attribute in this section, to allow session-resumption for subsequent authentication attempts. +The value of this attribute may be empty (a zero length string) if +which case a random value with the correct hint character will be +generated for you. ### Cryptographic identity overrides @@ -638,6 +820,27 @@ server eap-aka-sim { # namespace = eap-sim namespace = eap-aka # namespace = eap-aka-prime +# eap-sim { +# request_identity = no +# ephemeral_id_length = 14 +# strip_permanent_identity_hint = yes +# protected_success = yes +# } + eap-aka { +# protected_success = no +# virtual_server = "" +# request_identity = no +# ephemeral_id_length = 14 +# strip_permanent_identity_hint = yes +# protected_success = yes + } +# eap-aka-prime { +# network_name = "" +# request_identity = no +# ephemeral_id_length = 14 +# strip_permanent_identity_hint = yes +# protected_success = yes +# } recv Identity-Response { ok }