From: Jorge Pereira Date: Mon, 4 Feb 2019 23:29:44 +0000 (-0200) Subject: Update raddb/mods-available/eap X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a22c24df3977c7bae384b2afa683f6876c5555de;p=thirdparty%2Ffreeradius-server.git Update raddb/mods-available/eap --- diff --git a/raddb/mods-available/eap b/raddb/mods-available/eap index e95607a3334..33136e73620 100644 --- a/raddb/mods-available/eap +++ b/raddb/mods-available/eap @@ -1,58 +1,73 @@ # -*- text -*- -## -## eap.conf -- Configuration for EAP types (PEAP, TTLS, etc.) -## -## $Id$ +# +# :toc: +# +# $Id$ ####################################################################### # +# = EAP Module +# +# The `eap` module takes care of all EAP authentication as described in RFC 3579. +# +# [WARNING] +# ==== # Whatever you do, do NOT set 'Auth-Type := EAP'. The server is smart enough # to figure this out on its own. # # The most common side effect of setting 'Auth-Type := EAP' is that the users # then cannot use ANY other authentication method. +# ==== +# + +# +# # Default instance # eap { # - # Invoke the default supported EAP type when EAP-Identity response is - # received. + # default_eap_type::: Invoke the default supported EAP type when `EAP-Identity` + # response is received. # - # The incoming EAP messages DO NOT specify which EAP type they will be - # using, so it MUST be set here. + # The incoming EAP messages *DO NOT* specify which EAP type they will be using, + # so it MUST be set here. # # For now, only one default EAP type may be used at a time. # - # If the EAP-Type attribute is set by another module, then that EAP + # If the `EAP-Type` attribute is set by another module, then that EAP # type takes precedence over the default type configured here. # default_eap_type = md5 + # + # ignore_unknown_eap_types:: # # There are many EAP types, but the server has support for only a # limited subset. If the server receives a request for an EAP type it # does not support, then it normally rejects the request. By setting - # this configuration to "yes", you can tell the server to instead keep + # this configuration to `yes`, you can tell the server to instead keep # processing the request. Another module MUST then be configured to # proxy the request to another RADIUS server which supports that EAP # type. # - # If another module is NOT configured to handle the request, then the + # NOTE: If another module is NOT configured to handle the request, then the # request will still end up being rejected. # ignore_unknown_eap_types = no # - # Cisco AP1230B firmware 12.2(13)JA1 has a bug. When given a User-Name - # attribute in an Access-Accept, it copies one more byte than it should. + # cisco_accounting_username_bug:: + # + # Cisco AP1230B firmware 12.2(13)JA1 has a bug. When given a `User-Name` + # attribute in an `Access-Accept`, it copies one more byte than it should. # # We can work around it by configurably adding an extra zero byte. # cisco_accounting_username_bug = no # - # Allowed EAP-types + # ## Allowed EAP-types # - # Only EAP types listed below with a 'type = ' pair will be allowed. + # type:: Only EAP types listed below with a `type = ` pair will be allowed. # type = md5 # type = pwd @@ -67,19 +82,22 @@ eap { type = sim # - # EAP-MD5 authentication cannot be used for wireless - # connections. It is insecure, and does not provide for - # dynamic WEP keys or WPA enterprise. + # ### EAP-MD5 + # + # WARNING: EAP-MD5 authentication cannot be used for wireless + # connections. It is insecure, and does not provide for dynamic WEP + # keys or WPA enterprise. + # md5 { } - ## EAP-PWD (Secure password-based authentication) # - # In v4, the "known good" password is taken from the - # &request.control:Cleartext-Password list, as is done by - # other modules. The change from v3 is that the - # "inner-tunnel" virtual server is not used. + # ### EAP-PWD (Secure password-based authentication) + # + # In v4, the "known good" password is taken from the `&request.control:Cleartext-Password` list, + # as is done by other modules. The change from v3 is that the `inner-tunnel` virtual server + # is no not used. # # pwd { # group = 19 @@ -87,15 +105,19 @@ eap { # server_id = theserver@example.com # - # This has the same meaning as for TLS. + # fragment_size:: This has the same meaning as for TLS. # # fragment_size = 1020 # } - ## Cisco LEAP # - # We do not recommend using LEAP in new deployments. See: - # http://www.securiteam.com/tools/5TP012ACKE.html + # ### Cisco LEAP + # + # [WARNING] + # ==== + # We do not recommend using LEAP in new deployments. + # See: http://www.securiteam.com/tools/5TP012ACKE.html + # ==== # # Cisco LEAP uses the MS-CHAP algorithm (but not the MS-CHAP # attributes) to perform it's authentication. @@ -106,49 +128,55 @@ eap { # leap { # } - ## Generic Token Card. # - # Currently, this is only permitted inside of EAP-TTLS, or EAP-PEAP. - # The module "challenges" the user with text, and the response from the - # user is taken to be the User-Password. + # ### Generic Token Card + # + # Currently, this is only permitted inside of `EAP-TTLS`, or `EAP-PEAP`. + # The module `challenges` the user with text, and the response from the + # user is taken to be the `User-Password`. # - # Proxying the tunneled EAP-GTC session is a bad idea, the users + # WARNING: Proxying the tunneled `EAP-GTC` session is a bad idea, the users # password will go over the wire in plain-text, for anyone to see. # gtc { - # The default challenge, which many clients ignore.. + # + # challenge:: The default challenge, which many clients ignore. + # # challenge = "Password: " + # + # auth_type:: # # The plain-text response which comes back is put into a - # User-Password attribute, and passed to another module for - # authentication. This allows the EAP-GTC response to be + # `User-Password` attribute, and passed to another module for + # authentication. This allows the `EAP-GTC` response to be # checked against plain-text, or crypt'd passwords. # # If you say "Local" instead of "PAP", then the module will - # look for a User-Password configured for the request, and do + # look for a `User-Password` configured for the request, and do # the authentication itself. # auth_type = PAP } - ## Common TLS configuration for TLS-based EAP types # - # See raddb/certs/README for additional comments on certificates. + # ## Common TLS configuration for TLS-based EAP types + # + # See `raddb/certs/README` for additional comments on certificates. # - # If OpenSSL was not found at the time the server was built, the "tls", - # "ttls", and "peap" sections will be ignored. + # If OpenSSL was not found at the time the server was built, the `tls`, + # `ttls`, and `peap` sections will be ignored. # # If you do not currently have certificates signed by a trusted CA you # may use the 'snakeoil' certificates. Included with the server in - # raddb/certs. + # `raddb/certs`. # # If these certificates have not been auto-generated: # # cd raddb/certs # make # - # These test certificates SHOULD NOT be used in a normal + # These test certificates *SHOULD NOT* be used in a normal # deployment. They are created only to make it easier to # install the server, and to perform some simple tests with # EAP-TLS, TTLS, or PEAP. @@ -160,19 +188,21 @@ eap { # want. # tls-config tls-common { + # + # auto_chain:: # # OpenSSL will automatically create certificate chains, unless # we tell it to not do that. The problem is that it sometimes # gets the chains right from a certificate signature view, but # wrong from the clients view. # - # When setting "auto_chain = no", the server chain {} section(s) - # below MUST include the full certificate chain. + # NOTE: When setting `auto_chain = no`, the server `chain {}` + # section(s) below MUST include the full certificate chain. # # auto_chain = no # - # A chain of certificates to present to the client. + # .A chain of certificates to present to the client # # Multiple chain sections can be specified to allow different # chains for different key types (RSA, DSA, DH, EC). @@ -193,27 +223,32 @@ eap { # chain rsa { # - # The format of the certificate(s) and private key file. - # May be one of PEM, DER or ASN1 (ASN1 is an alias for DER). + # format:: The format of the certificate(s) and private key file. + # + # May be one of `PEM`, `DER` or `ASN1` (ASN1 is an alias for `DER`). # # format = "PEM" # - # If PEM is being used the "certificate_file" specified below + # certificate_file:: + # + # If PEM is being used the `certificate_file` specified below # should contain the server certificates, and any intermediary CAs # which are not available to the client. # - # If verify_mode (below) is set to "hard" or "soft" all + # [NOTE] + # ==== + # If `verify_mode` (below) is set to `hard` or `soft` all # intermediary CAs and the Root CA should be included. # # Any certificate chain MUST be in order from server # certificate (first in the file) to intermediary CAs (second) to - # Root CA (last in the file) as per RFC 4346 (see certificate_list) - # http://tools.ietf.org/html/rfc4346#section-7.4.2 ) + # Root CA (last in the file) as per RFC 4346 Section 7.4.2 (see certificate_list) # - # If DER is being used the "certificate_file" should contain ONLY - # the server's certificate, and one or more "ca_file" items should be + # If DER is being used the `certificate_file` should contain ONLY + # the server's certificate, and one or more `ca_file` items should be # used to load intermediary CAs and the Root CA. + # ==== # # We recommend using `ca_file` to load the # root CAs, instead of putting them in @@ -221,70 +256,83 @@ eap { # certificate_file = ${certdir}/rsa/server.pem + # + # ca_file:: # # Load an additional intermediary CA or Root CA for consideration in # chain compilation. Multiple "ca_file" config items may be used # to load multiple certificates. # - # When multiple `ca_file`s are used, the - # server will still present only one - # `certificate_file` to the clients. The - # main use of multiple `ca_file` is to permit - # the use of EAP-TLS with client certificates - # from multiple Root CAs. + # When multiple `ca_file`s are used, the server will still present only one + # `certificate_file` to the clients. The main use of multiple `ca_file` is + # to permit the use of EAP-TLS with client certificates from multiple Root CAs. # ca_file = ${certdir}/rsa/ca.pem # - # Password used to encrypt the private key. If the private key is - # not encrypted, this configuration item will have no effect. + # private_key_password:: Password used to encrypt the private key. + # If the private key is not encrypted, this configuration item + # will have no effect. # private_key_password = whatever + # + # private_key_file:: # # If the Private key & Certificate are located in the same file, - # then 'private_key_file' & 'certificate_file' must contain the + # then `private_key_file` & `certificate_file` must contain the # same file name. # private_key_file = ${certdir}/rsa/server.key + # + # verify_mode:: # # During startup we attempt to precompile the certificate chain # from server certificate to Root CA. This configuration item specifies # what happens if compilation fails. # - # hard - Error out if we cannot build a complete certificate chain. - # soft - Warn if we cannot build a complete certificate chain. - # none - Stay silent if we cannot build a complete certificate chain. + # [options="header,autowidth"] + # |=== + # | Error | Description + # | hard | Error out if we cannot build a complete certificate chain. + # | soft | Warn if we cannot build a complete certificate chain. + # | none | Stay silent if we cannot build a complete certificate chain. + # |=== # - # The default is "hard". The only time this should be changed is if + # The default is `hard`. The only time this should be changed is if # you want to limit the number of intermediary CAs sent to the # client by not including them in the chain. # - # Note: Depending on the value of "auto_chain" we may still be able to - # build a complete chain, but this will be done at runtime. + # [NOTE] + # ==== + # * Depending on the value of `auto_chain` we may still be able to + # build a complete chain, but this will be done at runtime. # - # Note: "auto_chain" has no effect on which certificates are considered - # for pre-compilation. Only those listed in this chain {} section will be - # used. + # * `auto_chain` has no effect on which certificates are considered + # for pre-compilation. Only those listed in this `chain {}` section + # will be used. + # ==== # # verify_mode = "hard" + # + # include_root_ca:: # # Omit the Root CA from the compiled certificate chain. # The Root CA should already be known/trusted by the client so it is # usually not needed unless the client is particularly poorly behaved. # - # Note: The Root CA must still be available for chain compilation to - # succeed even if "include_root_ca = no". + # NOTE: The Root CA must still be available for chain compilation to + # succeed even if `include_root_ca = no`. # - # The default here is "no". + # Default: `no`. # include_root_ca = no } # - # Load the ECC certificate chain for key agility + # ### ECC certificate chain for key agility # # This is disabled by default, see the warning above. # If your supplicants propose a mix of different @@ -299,6 +347,8 @@ eap { # private_key_file = ${certdir}/ecc/server.key # } + # + # ## Server certificate # # The server certificate may also be specified at # runtime on a per session basis. In that use-case, @@ -321,24 +371,25 @@ eap { # verifying that the supplicant returns the correct # TLS alert (available in Module-Failure-Message). # - # Note that after receiving a fatal alert, TLS - # negotiation cannot continue. However, as most - # supplicants will immediately retry authenticaton, - # this failure will likely not be an issue. + # NOTE: After receiving a fatal alert, TLS negotiation + # cannot continue, but as most supplicants retry + # enthusiastically this probably won't be an issue. # # - # Trusted Root CA list + # ca_file:: Trusted Root CA list # # ALL of the CA's in this list will be trusted to issue client # certificates for authentication. # - # You should not use a public CA here. This should either be + # NOTE: You should not use a public CA here. This should either be # set to a certificate chain for your institution's CA # or a self signed Root CA. - # + # # ca_file = ${cadir}/rsa/ca.pem + # + # psk_identity::: # # If OpenSSL supports TLS-PSK, then we can use a PSK identity # and (hex) password. @@ -350,9 +401,14 @@ eap { # psk_identity = "test" # psk_hexphrase = "036363823" - # Dynamic queries for the PSK. If TLS-PSK is used, - # and psk_query is set, then you MUST NOT use - # psk_identity or psk_hexphrase. + # + # WARNING: Dynamic queries for the `PSK`. If `TLS-PSK` is used, + # and `psk_query` is set, then you MUST NOT use + # `psk_identity` or `psk_hexphrase`. + # + + # + # psk_query:: # # Instead, use a dynamic expansion similar to the one # below. It keys off of TLS-PSK-Identity. It should @@ -365,7 +421,6 @@ eap { # # psk_query = "%{sql:select hex(key) from psk_keys where keyid = '%{TLS-PSK-Identity}'}" - # # For DH cipher suites to work, you have to run OpenSSL to # create the DH file first: @@ -374,69 +429,83 @@ eap { # dh_file = ${certdir}/dh + # + # fragment_size:: # # This can never exceed the size of a RADIUS packet (4096 # bytes), and is preferably half that, to accommodate other # attributes in RADIUS packet. On most APs the MAX packet - # length is configured between 1500 - 1600 In these cases, - # fragment size should be 1024 or less. + # length is configured between `1500 - 1600` In these cases, + # fragment size should be `1024` or less. # # fragment_size = 1024 # - # Check the Certificate Revocation List + # 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 + # <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 + # <3> uncomment the lines below. + # <4> Restart radiusd. # # check_crl = yes + # + # ca_path:: Full path to the CA file. + # ca_path = ${cadir} - # Accept an expired Certificate Revocation List + # + # allow_expired_crl:: Accept an expired Certificate Revocation List. # # allow_expired_crl = no # - # If check_cert_issuer is set, the value will be checked + # 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 + # of the `TLS-Client-Cert-Issuer` attribute. This check can be # done via any mechanism you choose. # # check_cert_issuer = "/C=GB/ST=Berkshire/L=Newbury/O=My Company Ltd" # - # If check_cert_cn is set, the value will be xlat'ed and + # 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" + # 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 + # of the `TLS-Client-Cert-Common-Name` attribute. This check can be done # via any mechanism you choose. # # check_cert_cn = %{User-Name} + # + # cipher_list:: # # Set this option to specify the allowed TLS cipher suites. - # The format is listed in "man 1 ciphers". + # The format is listed in `man 1 ciphers`. # - # For EAP-FAST, use "ALL:!EXPORT:!eNULL:!SSLv2" + # NOTE: For `EAP-FAST`, use "ALL:!EXPORT:!eNULL:!SSLv2" # cipher_list = "DEFAULT" + # + # cipher_server_preference:: # # If enabled, OpenSSL will use server cipher list # (possibly defined by cipher_list option above) @@ -448,16 +517,25 @@ eap { cipher_server_preference = yes # - # Work-arounds for OpenSSL nonsense OpenSSL 1.0.1f and 1.0.1g do - # not calculate the EAP keys correctly. The fix is to upgrade + # tls_max_version:: + # + # [NOTE] + # ==== + # * Work-arounds for OpenSSL nonsense OpenSSL 1.0.1f and 1.0.1g do + # not calculate the `EAP` keys correctly. The fix is to upgrade # OpenSSL, or disable TLS 1.2 here. # - # SSLv2 and SSLv3 are permanently disabled due to security + # * SSLv2 and SSLv3 are permanently disabled due to security # issues. + # ==== # # tls_max_version = 1.1 # + # tls_min_version:: + # + # [NOTE] + # ==== # Prevents versions < tls_min_version from being negotiated. # In general the higher the tls_min_version the more secure # the protocol, but the narrower the range of supported TLS @@ -465,18 +543,19 @@ eap { # # SSLv2 and SSLv3 are permanently disabled due to security # issues. + # ==== # # tls_min_version = 1.0 # - # Elliptical cryptography configuration + # ecdh_curve:: Elliptical cryptography configuration. # # Only for OpenSSL >= 0.9.8.f # ecdh_curve = "prime256v1" # - # TLS Session resumption + # ### TLS Session resumption # # We currently support RFC 5246 style TLS session resumption # only. @@ -490,28 +569,30 @@ eap { # session. # # Resuming a TLS session avoids the certificate exchange and in - # the case PEAP and TTLS, allows the client to skip the inner - # EAP method. + # the case `PEAP` and `TTLS`, allows the client to skip the inner + # `EAP` method. # - # Enabling Session-Resumption is highly recommended for sites + # Enabling `Session-Resumption` is highly recommended for sites # using slow authentication backends such as winbindd/Active # Directory, and for access federations operating over the # internet, such as Eduroam. # - # Note: You must ensure any attributes required for policy + # NOTE: You must ensure any attributes required for policy # decisions are cached at the same time as the TLS session - # data. See sites-available/tls-cache for documentation on + # data. See `sites-available/tls-cache` for documentation on # how TLS cache now works. # - # If using the default tls-cache virtual server and + # If using the default `tls-cache` virtual server and # cache module config, policy attributes may be stored in the - # &session-state: list. + # `&session-state:` list. # cache { + # + # virtual_server:: # # To enable session resumption, uncomment the virtual # server entry below, and link - # sites-available/tls-cache to sites-enabled/tls-cache. + # `sites-available/tls-cache` to `sites-enabled/tls-cache`. # # You can disallow resumption for a particular user by # adding the following attribute to the control item @@ -519,14 +600,14 @@ eap { # # Allow-Session-Resumption = No # - # If no virtual_server is specified you CANNOT enable + # NOTE: If no virtual_server is specified you *CANNOT* enable # resumption for just one user by setting the above - # attribute to "yes". + # attribute to `yes`. # # virtual_server = 'tls-cache' # - # Name of the context TLS sessions are created under. + # name:: Name of the context TLS sessions are created under. # # Qualifies TLS sessions so that they can't be used for # purposes for which they were not intended. @@ -537,28 +618,30 @@ eap { # # To disable - set to a zero length string "". # - # Note: OpenSSL only allows 32 bytes of session ctx, so - # the value provided here is digested with SHA256. + # NOTE: OpenSSL only allows 32 bytes of session ctx, so + # the value provided here is digested with SHA256. # # name = "%{EAP-Type}%{Virtual-Server}" + # + # 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. + # ttl set in `rlm_cache`. # - # Default is 24hrs inline with RFC4346. + # Default is 24hrs inline with RFC 4346. # # lifetime = 86400 # - # Revalidate client's certificate chain each time a session - # is resumed. + # 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. + # 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 @@ -566,6 +649,8 @@ eap { # # verify = no + # + # require_extended_master_secret:: # # Only allow session resumption if an extended master # secret has been created. This requires client support. @@ -575,32 +660,40 @@ eap { # a session if it can insert itself into the path between # the TLS client and TLS server. # - # https://mitls.org/pages/attacks/3SHAKE + # See more at https://mitls.org/pages/attacks/3SHAKE # - # Note: This attack is undetectable by the client. + # WARNING: This attack is undetectable by the client. # # require_extended_master_secret = yes + # + # require_perfect_forward_secrecy:: # # Only allow session resumption if a cipher which would # allow perfect forward secrecy has been selected. # # require_perfect_forward_secrecy = no + # + # [NOTE] + # ==== # 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. + # session caching is now handled by the `cache` module. # That module is more configurable, and has more back-ends # than the simple configurations below. # - # enable - # persist_dir - # max_entries + # * `enable` + # * `persist_dir` + # * `max_entries` + # ==== # } + # + # ### 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 @@ -611,12 +704,14 @@ eap { # below to enable it. # verify { + # + # 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 + # `chmod go-rwx` on the directory, for security # reasons. The directory MUST exist when the server # starts. # @@ -625,14 +720,16 @@ eap { # # tmpdir = /tmp/radiusd + # + # 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 + # The `${..ca_path}` text is a reference to the ca_path # variable defined above. # - # The %{TLS-Client-Cert-Filename} is the name of the + # 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. @@ -641,7 +738,7 @@ eap { } # - # OCSP Configuration + # ### OCSP Configuration # # Certificates can be verified against an OCSP Responder. # This makes it possible to immediately revoke certificates without @@ -650,36 +747,49 @@ eap { # 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 + # 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: # - # - no OCSP responder indicated the certificate is not valid. - # - yes OCSP responder indicated the certificate is valid. - # - skipped OCSP checks were skipped. + # [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 + # 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 + # 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 + # 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: # - # - no Invalid. - # - yes Valid. - # - skipped If softfail = yes value else invalid. + # [options="header,autowidth"] + # |=== + # | Value | Description + # | no | Invalid. + # | yes | Valid. + # | skipped | If `softfail = yes` value else invalid. + # |=== # ocsp { # - # Enable it. The default is "no". Deleting the entire - # "ocsp" subsection also disables ocsp checking + # enable:: + # + # Deleting the entire `ocsp` subsection also disables ocsp checking. + # + # Default is `no`. # # enable = no + # + # virtual_server:: # # OCSP checks are performed immediately after the # complete certificate is received from the supplicant, @@ -689,78 +799,100 @@ eap { # In order to retrieve cached OCSP states, a virtual # server must be defined here. # - # See raddb/sites-available/tls-cache for details. + # See `raddb/sites-available/tls-cache` for details. # # virtual_server = 'tls-cache' + # + # 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". + # OCSP Responder URL set `override_cert_url = yes`. # override_cert_url = yes + # + # url:: # # If the OCSP Responder address is not extracted from # the certificate, the URL can be defined here. # url = "http://127.0.0.1/ocsp/" + # + # use_nonce:: # # If the OCSP Responder can not cope with nonce in the # request, then it can be disabled here. # - # For security reasons, disabling this option is not + # [WARNING] + # ==== + # * For security reasons, disabling this option is not # recommended as nonce protects against replay attacks. # - # Note that Microsoft AD Certificate Services OCSP + # * 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 + # disable it in the query here. + # + # See http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx + # ==== # # use_nonce = yes + # + # timeout:: # # Number of seconds before giving up waiting for OCSP - # response. 0 uses system default. + # response. + # + # Default is `0`. # # timeout = 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 + # To treat these errors as `soft` failures and still # accept the certificate, enable this option. # - # Warning: this may enable clients with revoked + # WARNING: this may enable clients with revoked # certificates to connect if the OCSP responder is not - # available. Use with caution. + # available. *Use with caution*. # # softfail = no } - # - # Configures OCSP stapling for server certificates. + # ### 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. # staple { # - # Enable it. The default is "no". Deleting the entire - # "ocsp" subsection also disables ocsp checking + # enable:: + # + # Enable it. Deleting the entire `ocsp` subsection also disables ocsp checking. + # + # Default is `no`. # # enable = no + # + # virtual_server:: # # OCSP checks are performed whenever a TLS client includes # an OCSP stapling extension. @@ -771,47 +903,60 @@ eap { # The same virtual server can be used for caching # client OCSP response states, and stapling information. # - # See raddb/sites-available/tls-cache for details. + # See `raddb/sites-available/tls-cache` for details. # # virtual_server = 'tls-cache' + # + # 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". + # OCSP Responder URL set `override_cert_url = yes`. # override_cert_url = yes + # + # url:: # # If the OCSP Responder address is not extracted from # the certificate, the URL can be defined here. # url = "http://127.0.0.1/ocsp/" + # + # use_nonce:: # # If the OCSP Responder can not cope with nonce in the # request, then it can be disabled here. # - # For security reasons, disabling this option is not + # [WARNING] + # ==== + # * For security reasons, disabling this option is not # recommended as nonce protects against replay attacks. # - # Note that Microsoft AD Certificate Services OCSP + # * 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 + # ==== # # use_nonce = yes # # Number of seconds before giving up waiting for OCSP - # response. 0 uses system default. + # response. + # + # Default is `0`. # # timeout = 0 + # + # softfail:: # # Normally if we can't query the OCSP Responder - # we issue a fatal alert, and abort. Set this to true + # 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. # @@ -819,20 +964,23 @@ eap { } } - ## EAP-TLS # - # As of Version 3.0, the TLS configuration for TLS-based - # EAP types is above in the "tls-config" section. + # ### EAP-TLS + # + # As of Version 3.0, the TLS configuration for `TLS-based` + # EAP types is above in the `tls-config { ... }` section. # tls { # Point to the common TLS configuration tls = tls-common # - # EAP-TLS can work without a client certificate, but situations + # require_client_cert:: + # + # `EAP-TLS` can work without a client certificate, but situations # whether this is useful are quite limited. # - # Currently only the Hotspot 2.0 R2 standard utilises EAP-TLS + # Currently only the Hotspot 2.0 R2 standard utilises `EAP-TLS` # without a peer certificate. # # This is to secure the SSID used to provide connectivity to the OSU @@ -840,41 +988,46 @@ eap { # # You can override this option by setting: # - # EAP-TLS-Require-Client-Cert = Yes/No + # EAP-TLS-Require-Client-Cert = Yes/No # # in the control items for a request. # # require_client_cert = yes # - # Include_length is a flag which is by default set to yes If - # set to yes, Total Length of the message is included in EVERY - # packet we send. If set to no, Total Length of the message is + # include_length:: + # + # flag which is by default set to yes If set to `yes`, + # Total length of the message is included in EVERY + # packet we send. If set to `no`, Total length of the message is # included ONLY in the First packet of a fragment series. # # include_length = yes # - # As part of checking a client certificate, the EAP-TLS sets - # some attributes such as TLS-Client-Cert-Common-Name. This virtual + # 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. # # virtual_server = check-eap-tls } - ## EAP-TTLS # - # Note: To use EAP-TTLS you must also configure an inner method in - # mods-enabled/eap_inner. + # ### EAP-TTLS # - # The TTLS module implements the EAP-TTLS protocol, which can be + # The TTLS module implements the `EAP-TTLS` protocol, which can be # described as EAP inside of Diameter, inside of TLS, inside of EAP, - # inside of RADIUS... + # inside of RADIUS. + # + # NOTE: To use `EAP-TTLS `you must also configure an `inner` method in + # `mods-enabled/eap_inner`. # # Surprisingly, it works quite well. # - # When using PAP, GTC, or MSCAHPv2 as an inner method EAP-TTLS is + # When using `PAP`, `GTC`, or `MSCAHPv2` as an inner method `EAP-TTLS` is # only secure if the supplicant is configured to validate the the # server certificate presented. # @@ -883,26 +1036,33 @@ eap { # ttls { # - # Which tls-config section the TLS negotiation parameters - # are in - see EAP-TLS above for an explanation. + # tls:: + # + # Which `tls-config` section the TLS negotiation parameters + # are in - see `EAP-TLS` above for an explanation. # # In the case that an old configuration from FreeRADIUS - # v2.x is being used, all the options of the tls-config + # v2.x is being used, all the options of the `tls-config { ... }` # section may also appear instead in the 'tls' section - # above. If that is done, the tls= option here (and in - # tls above) MUST be commented out. + # above. If that is done, the `tls=` option here (and in tls above) + # MUST be commented out. # tls = tls-common # - # Both copy_request_to_tunnel and use_tunneled_reply have been + # [WARNING] + # ==== + # Both `copy_request_to_tunnel` and `use_tunneled_reply` have been # removed in v4.0. # - # See the new policy "copy_request_to_tunnel" in - # sites-available/inner-tunnel, and in policy.d/eap + # See the new policy `copy_request_to_tunnel` in + # `sites-available/inner-tunnel`, and in `policy.d/eap` # for more information. + # ==== # + # + # virtual_server:: # # The inner tunneled request can be sent through a virtual # server constructed specifically for this purpose. @@ -913,92 +1073,90 @@ eap { # virtual_server = "inner-tunnel" + # + # include_length:: # # This has the same meaning, and overwrites, the same field in - # the "tls" configuration, above. The default value here is - # "yes". + # the `tls` configuration, above. The default value here is + # `yes`. # # include_length = yes # - # EAP-TTLS does not require a client certificate. + # require_client_cert:: + # + # `EAP-TTLS` does not require a client certificate. # However, you can require one by setting the # following option. You can also override this option by # setting # - # EAP-TLS-Require-Client-Cert = Yes + # EAP-TLS-Require-Client-Cert = Yes # # in the control items for a request. # - # Note that the majority of supplicants do not support using a - # client certificate with EAP-TTLS, so this option is unlikely + # NOTE: The majority of supplicants do not support using a + # client certificate with `EAP-TTLS`, so this option is unlikely # to be usable for most people. # # require_client_cert = yes } - - ## EAP-PEAP # - ########################################################################### + # ### EAP-PEAP # - # !!!!! WARNINGS for Windows compatibility !!!!! - # - ########################################################################### - # - # If you see the server send an Access-Challenge, and the client never - # sends another Access-Request, then + # The tunneled `EAP` session needs a default `EAP` type which is separate + # from the one for the non-tunneled EAP module. Inside of the TLS/PEAP + # tunnel, we recommend using `EAP-MS-CHAPv2`. # - # STOP! + # When using `GTC`, or `MSCAHPv2` as an inner method, `PEAP` is only secure + # if the supplicant is configured to validate the server certificate. # - # The server certificate has to have special OID's in it, or else the - # Microsoft clients will silently fail. See the "scripts/xpextensions" - # file for details, and the following page: + # It is trivial to retrieve the user's credentials from these inner + # methods, if the user connects to a rogue server. # - # http://support.microsoft.com/kb/814394/en-us + # #### Windows compatibility # - # For additional Windows XP SP2 issues, see: + # [IMPORTANT] + # ==== + # * If you see the server send an `Access-Challenge`, and the client never + # sends another `Access-Request`, then *STOP*! # - # http://support.microsoft.com/kb/885453/en-us + # * The server certificate has to have special OID's in it, or else the + # Microsoft clients will silently fail. See the `scripts/xpextensions` + # file for details, and the following page + # http://support.microsoft.com/kb/814394/en-us . # - # If is still doesn't work, and you're using Samba, you may be - # encountering a Samba bug. See: + # * For additional Windows XP SP2 issues, + # see: http://support.microsoft.com/kb/885453/en-us # - # https://bugzilla.samba.org/show_bug.cgi?id=6563 + # * If is still doesn't work, and you're using Samba, you may be + # encountering a Samba bug. + # see: https://bugzilla.samba.org/show_bug.cgi?id=6563 # - # Note that we do not necessarily agree with their explanation... but + # * Note that we do not necessarily agree with their explanation. but # the fix does appear to work. + # ==== # - ########################################################################## - - # - # - # Note: To use EAP-TTLS you must also configure an inner method in - # mods-enabled/eap_inner. - # - # The tunneled EAP session needs a default EAP type which is separate - # from the one for the non-tunneled EAP module. Inside of the TLS/PEAP - # tunnel, we recommend using EAP-MS-CHAPv2. - # - # When using GTC, or MSCAHPv2 as an inner method, PEAP is only secure if - # the supplicant is configured to validate the server certificate. - # - # It is trivial to retrieve the user's credentials from these inner - # methods, if the user connects to a rogue server. + # NOTE: To use `EAP-TTLS` you must also configure an inner method in + # `mods-enabled/eap_inner`. # peap { # - # Which tls-config section the TLS negotiation parameters are - # in - see EAP-TLS above for an explanation. + # tls:: + # + # Which `tls-config` section the TLS negotiation parameters are + # in - see `EAP-TLS` above for an explanation. # # In the case that an old configuration from FreeRADIUS v2.x is - # being used, all the options of the tls-config section may - # also appear instead in the 'tls' section above. If that is + # being used, all the options of the `tls-config` section may + # also appear instead in the `tls` section above. If that is # done, the tls= option here (and in tls above) MUST be # commented out. # tls = tls-common + # + # default_eap_type:: # # The tunneled EAP session needs a default EAP type which is # separate from the one for the non-tunneled EAP module. @@ -1008,21 +1166,28 @@ eap { default_eap_type = mschapv2 # - # Both copy_request_to_tunnel and use_tunneled_reply have been + # [NOTE] + # ==== + # Both `copy_request_to_tunnel` and `use_tunneled_reply` have been # removed in v4.0. # - # See the new policy "copy_request_to_tunnel" in - # sites-available/inner-tunnel, and in policy.d/eap + # See the new policy `copy_request_to_tunnel` in + # `sites-available/inner-tunnel`, and in `policy.d/eap` # for more information. + # ==== # + # + # proxy_tunneled_request_as_eap:: # # When the tunneled session is proxied, the home server may not - # understand EAP-MSCHAP-V2. Set this entry to "no" to proxy the - # tunneled EAP-MSCHAP-V2 as normal MSCHAPv2. + # understand `EAP-MSCHAP-V2`. Set this entry to `no` to proxy the + # tunneled `EAP-MSCHAP-V2` as normal`MSCHAPv2`. # # proxy_tunneled_request_as_eap = yes + # + # virtual_server:: # # The inner tunneled request can be sent through a virtual # server constructed specifically for this purpose. @@ -1034,153 +1199,182 @@ eap { virtual_server = "inner-tunnel" # - # This option enables support for MS-SoH see doc/SoH.txt for + # soh:: + # + # This option enables support for `MS-SoH` see `doc/SoH.txt` for # more info. It is disabled by default. # # soh = yes # - # The SoH reply will be turned into a request which can be sent + # soh_virtual_server:: + # + # The `SoH` reply will be turned into a request which can be sent # to a specific virtual server: # # soh_virtual_server = "soh-server" # - # Unlike EAP-TLS, PEAP does not require a client certificate. + # require_client_cert:: + # + # Unlike `EAP-TLS`, `PEAP `does not require a client certificate. # However, you can require one by setting the following # option. You can also override this option by setting # # EAP-TLS-Require-Client-Cert = Yes # - # in the control items for a request. + # in the `control` items for a request. # - # Note that the majority of supplicants do not support using a - # client certificate with PEAP, so this option is unlikely to + # NOTE: The majority of supplicants do not support using a + # client certificate with `PEAP`, so this option is unlikely to # be usable for most people. # # require_client_cert = yes } + # + # ### EAP MS-CHAPv2 # # This takes no configuration. # - # Note that it is the EAP MS-CHAPv2 sub-module, not the main 'mschap' + # NOTE: It is the EAP MS-CHAPv2 sub-module, not the main `mschap` # module. # # Note also that in order for this sub-module to work, the main - # 'mschap' module MUST ALSO be configured. + # `mschap` module MUST ALSO be configured. # - # This module is the *Microsoft* implementation of MS-CHAPv2 in EAP. - # There is another (incompatible) implementation of MS-CHAPv2 in EAP by - # Cisco, which FreeRADIUS does not currently support. + # This module is the *Microsoft* implementation of `MS-CHAPv2` in `EAP`. + # There is another (*incompatible*) implementation of `MS-CHAPv2 in `EAP` by + # Cisco, which *FreeRADIUS does not currently support*. # mschapv2 { + # + # send_error:: + # # Prior to version 2.1.11, the module never sent the - # MS-CHAP-Error message to the client. This worked, but it had + # `MS-CHAP-Error` message to the client. This worked, but it had # issues when the cached password was wrong. The server - # *should* send "E=691 R=0" to the client, which tells it to + # *should* send `E=691 R=0` to the client, which tells it to # prompt the user for a new password. # - # The default is to behave as in 2.1.10 and earlier, which is - # known to work. If you set "send_error = yes", then the error + # CAUTION: The default is to behave as in `2.1.10` and earlier, which is + # known to work. If you set `send_error = yes`, then the error # message will be sent back to the client. This *may* help some # clients work better, but *may* also cause other clients to # stop working. # # send_error = no + # + # identity:: + # # Server identifier to send back in the challenge. This should # generally be the host name of the RADIUS server. Or, some # information to uniquely identify it. + # # identity = "FreeRADIUS" } - ## EAP-FAST # - # Note: To use EAP-FAST you must also configure an inner method in - # mods-enabled/eap_inner. + # ### EAP-FAST # - # The FAST module implements the EAP-FAST protocol + # The FAST module implements the EAP-FAST protocol. + # + # NOTE: To use `EAP-FAST` you must also configure an `inner` method in + # `mods-enabled/eap_inner`. # fast { - # Point to the common TLS configuration + # + # tls:: + # + # Point to the common TLS configuration. # tls = tls-common # - # If 'cipher_list' is set here, it will over-ride the - # 'cipher_list' configuration from the 'tls-common' - # configuration. The EAP-FAST module has it's own - # over-ride for 'cipher_list' because the + # cipher_list:: + # + # If `cipher_list` is set here, it will over-ride the + # `cipher_list` configuration from the `tls-common` + # configuration. The `EAP-FAST` module has it's own + # over-ride for `cipher_list` because the # specifications mandata a different set of ciphers - # than are used by the other EAP methods. + # than are used by the other `EAP` methods. # - # cipher_list though must include "ADH" for anonymous provisioning. + # `cipher_list` though must include "ADH" for anonymous provisioning. # This is not as straight forward as appending "ADH" alongside # "DEFAULT" as "DEFAULT" contains "!aNULL" so instead it is # recommended "ALL:!EXPORT:!eNULL:!SSLv2" is used # - # Note - for OpenSSL 1.1.0 and above you may need - # to add ":@SECLEVEL=0" + # NOTE: for OpenSSL 1.1.0 and above you may need to add ":@SECLEVEL=0" # cipher_list = "ALL:!EXPORT:!eNULL:!SSLv2" - # PAC lifetime in seconds (default: seven days) + # + # pac_lifetime:: PAC lifetime in seconds. + # + # Default is: `seven days` # pac_lifetime = 604800 - # Authority ID of the server # - # if you are running a cluster of RADIUS servers, you should make - # the value chosen here (and for "pac_opaque_key") the same on all - # your RADIUS servers. This value should be unique to your - # installation. We suggest using a domain name. + # authority_identity:: Authority ID of the server. + # + # if you are running a cluster of RADIUS servers, you should make + # the value chosen here (and for `pac_opaque_key`) the same on all + # your RADIUS servers. This value should be unique to your + # installation. We suggest using a domain name. # authority_identity = "1234" - # PAC Opaque encryption key (must be exactly 32 bytes in size) # - # This value MUST be secret, and MUST be generated using - # a secure method, such as via 'openssl rand -hex 32' + # pac_opaque_key:: + # + # PAC Opaque encryption key (must be exactly 32 bytes in size). + # + # This value MUST be secret, and MUST be generated using + # a secure method, such as via `openssl rand -hex 32` # pac_opaque_key = "0123456789abcdef0123456789ABCDEF" - # Same as for TTLS, PEAP, etc. + # + # virtual_server:: Same as for `TTLS`, `PEAP`, etc. # virtual_server = inner-tunnel } - ## EAP-SIM + # + # ### EAP-SIM # # Triplets can be provided using control attributes: # - # - &control:EAP-SIM-KC - # - &control:EAP-SIM-RAND - # - &control:EAP-SIM-SRES + # * `&control:EAP-SIM-KC` + # * `&control:EAP-SIM-RAND` + # * `&control:EAP-SIM-SRES` # - # Note: Three instances of each attribute must be provided. + # NOTE: Three instances of each attribute must be provided. # # Alternatively triplets can be generated locally using # control attributes: # - # - &control:SIM-Ki - # - &control:SIM-OPc - # - &control:SIM-Algo-Version (optional - see defaults below) + # * `&control:SIM-Ki` + # * `&control:SIM-OPc` + # * `&control:SIM-Algo-Version` (optional - see defaults below) # # UMTS Milenage inputs (AMF, SQN) are ignored. # - # &control:SIM-Algo-Version selects the SIM algorithm used, + # `&control:SIM-Algo-Version` selects the SIM algorithm used, # it must match the algorithm used by the SIM. # - # Accepted values for SIM-Algo-Versio are: + # Accepted values for `SIM-Algo-Versio` are: # - # - Comp128v1 - # - Comp128v2 - # - Comp128v3 (default if no &control:SIM-OPc) - # - Milenage (default if &control:SIM-OPc is available) + # * `Comp128v1` + # * `Comp128v2` + # * `Comp128v3` (default if no &control:SIM-OPc) + # * `Milenage` (default if &control:SIM-OPc is available) # - # Note: In general operators will not provide the Ki (subscriber - # key) for their SIM cards, as the Ki is considered highly + # NOTE: In general operators will not provide the Ki (subscriber + # key) for their `SIM cards`, as the Ki is considered highly # sensitive. # # Local triplet generation is intended for testing and @@ -1188,20 +1382,24 @@ eap { # are in use. # sim { - ## Send a protected success message # - # If true - indicate to the peer that we'd like to send + # send_result_ind:: 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. + # 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. # - # After the Notification is ACKed by the peer, we send - # the final EAP-Success packet containing MPPE keys. # send_result_ind = yes } - ## EAP-AKA # + # ### EAP-AKA + # + # This takes no configuration. # aka {