Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

tlsauth.eap File

Note: Use the Web GUI to maintain settings in the tlsauth.eap file. Do not edit the tlsauth.eap file manually.

Settings for the EAP-TLS automatic EAP helper are stored in the tlsauth.eap file. The tlsauth.eap configuration file is read each time the Steel-Belted Radius Carrier server receives a SIGHUP (1) signal.

[Server_Settings] Section

The [Server_Settings] section (Table 120) contains the settings that control the basic operation of the EAP-TLS authentication process.

Cipher_Suites Parameter

The Cipher_Suites parameter defined in the tlsauth.eap [Server_Settings] section, specifies the cipher suites (in order of preference) that the server uses for the EAP-TLS automatic EAP helper. When SBR Carrier receives a message for the EAP-TLS automatic EAP helper, it compares the cipher suites in the client message to the cipher suites defined in this parameter. A match is selected based on both type (for example DSS) and order of preference defined in the client cipher suite list. If no match is found, SBR Carrier returns a handshake failure alert and closes the connection. Following are several examples of the cipher suite selection process:

Example 1

SBR Carrier cipher suite list defined in Cipher_Suites parameter:
0x003C,0x003D,0x0067,0x006B,0x0039,0x0038,0x0033,
0x0035,0x002F,0x000a,0x0005,0x0004,0x0007

Client cipher suite list:
0x0040,0x0033,0x0032,0x0016,0x0013,0x0066,
0x0035,0x002f,0x0015,0x0012,0x000a,0x0005

Match found: 0x0033

In this example SBR Carrier selects 0x0033 because it is the first algorithm listed in the client cipher suite list that is also listed in the SBR Carrier cipher suite list, and because the type is also a match.

Example 2

SBR Carrier cipher suite list defined in Cipher_Suites parameter:

0x003C,0x003D,0x0067

Client cipher suite list:
0x0039,0x0033,0x0032,0x0016,0x0013,0x0066,0x0035,
0x002f,0x0015,0x0012,0x000a,0x0005

Match found: No match found, results in handshake failure.

Table 120: tlsauth.eap [Server_Settings] Syntax

Parameter

Function

TLS_Message_Fragment_Length

Maximum TLS message length that may be generated during each iteration of the TLS exchange. Anecdotal evidence suggests that some Access Points may have problems with RADIUS responses or EAP messages that exceed the size of one Ethernet frame (1500 bytes including IP/UDP headers).

The default value (1020) prevents the RADIUS challenge response (carried in a UDP packet) from exceeding one Ethernet frame. This is likely to be the safest setting.

Setting a smaller value affects the number of RADIUS challenge/response round-trips required to conclude the TLS exchange. While a value of 1400 may result in 6 round-trips, a value of 500 may result in 15 round-trips.

The minimum value is 500.

Verify_User_Name_Is_Principal_Name

Certificates issued by Microsoft's Windows 2000 Certificate Server usually include a Subject Alternative Name/Other Name attribute, where Principal Name set to something like user@certtest.acme.com.

The MS Windows XP client that supports EAP-TLS in conjunction with 802.1X extracts this attribute value from the client's certificate and uses it to respond to the Access Point's EAP Identity Request. The Access Point, in turn, packages up this value as the RADIUS User-Name attribute in requests it sends to a RADIUS server.

  • If set to 1, the EAP-TLS module verifies that the contents of the RADIUS User-Name attribute match the 'Principal Name' of the certificate used to authenticate the user.
  • If set to 0, no such check is performed. The value is set to 0 if the certificates used do not include a 'Principal Name' or if the client being used does not report the contents of 'Principal Name' as the user's identity in response to an EAP Identity Request.

Default value is 0.

Return_MPPE_Keys

Setting this attribute to 1 causes the EAP-TLS module to include RADIUS MS-MPPE-Send-Key and MS-MPPE-Recv-Key attributes in the final RADIUS Accept response sent to the Access Point. This is necessary for the Access Point to key the WEP encryption. If the Access Point is authenticating only end users and WEP is not being used, this attribute may be set to 0.

Default value is 1.

TLS_Protocol_Version

Specifies the TLS protocol version on which the server expects the client to initiate the handshake process. The value can be one of the following:

  • 31—TLS protocol version 1.0
  • 32—TLS protocol version 1.1
  • 33—TLS protocol version 1.2

Default value is 31.

If you set a value other than 31, 32, or 33, then the default TLS protocol version 1.0 (31) is considered.

DH_Prime_Bits

Specifies the size of the prime number that the module uses for Diffie-Hellman exponentiation. Selecting a larger prime number makes the system less susceptible to certain types of attacks but requires more CPU processing to compute the Diffie-Hellman key agreement operation.

Valid values are 512, 1024, 1536, 2048, 3072, and 4096.

Default value is 1024.

Cipher_Suites

Specifies the TLS cipher suites (in order of preference) that the server is to use. These cipher suites are documented in RFC 2246, The TLS Protocol Version 1, RFC 4346, The TLS Protocol Version 1.1, and RFC 5246, The TLS Protocol Version 1.2.

Default value is: 0x003C,0x003D,0x0067,0x006B,0x0039,0x0038,
0x0033,0x0035,0x002F,0x000a,0x0005,0x0004,0x0007.

See Table 111 for the list of tested cipher suites and their TLS protocol versions.

For more information see, Cipher_Suites Parameter.

[Secondary_Authorization] Section

The [Secondary_Authorization] section lets you specify whether secondary authorization is performed and, if it is, what information is used in the secondary authorization request.

Table 121: tlsauth.eap [Secondary_Authorization] Syntax

Parameter

Function

Enable

Specifies whether secondary authorization checking is enabled.

  • If set to 0, this feature is disabled and the EAP-TLS plug-in accepts the user upon proof of ownership of a private key that matches a valid certificate. If this setting is 0, no other settings in this section are applicable to the plug-in's operation.
  • If set to 1, a secondary authorization check against a traditional authentication method such as an SQL plug-in is performed.

Default value is 1.

UseSubjectCNAsUserName

Once the EAP-TLS module has concluded its processing, it may still defer to a traditional authentication method (core or plug-in) for final authorization. To do so, it must provide a username and password to the traditional authentication method.

If set to 1, the EAP-TLS module parses the Subject attribute of the client's certificate for the least significant 'CN=' and takes the value of this attribute (for example, 'George Washington') as the username being passed to the traditional authentication method.

Important: At any given instance, you can set only one of these parameters (UseSubjectCNAsUserName, UsePrincipalNameAsUserName, UseUserNameAttributeAsUserName, UseCallingStationIdAsUserName) to 1.

Default value is 1.

UsePrincipalNameAsUserName

Once the EAP-TLS module has concluded its processing, it may still defer to a traditional authentication method (core or plug-in) for final authorization. To do so, it must provide a username and password to the traditional authentication method.

  • If set to 0, the username passed to the traditional authentication method is the username retrieved from the Subject field of the client certificate (see description of UseSubjectCNAsUserName above).
  • If set to 1, the EAP-TLS module uses the principal name (Subject Alternate Name or Other Name) from the client certificate (for example, 'joe@acme.com') as the username being passed to the traditional authentication method.

Default value is 0.

Important: At any given instance, you can set only one of these parameters (UseSubjectCNAsUserName, UsePrincipalNameAsUserName, UseUserNameAttributeAsUserName, UseCallingStationIdAsUserName) to 1.

UseUserNameAttributeAsUserName

Indicates whether or not the plug-in should substitute the User Name for the RADIUS username before attempting to perform an inner authentication check. The default is not to make this substitution.

Default value is 0.

Important: At any given instance, you can set only one of these parameters (UseSubjectCNAsUserName, UsePrincipalNameAsUserName, UseUserNameAttributeAsUserName, UseCallingStationIdAsUserName) to 1.

UseCallingStationIdAsUserName

Indicates whether or not the plug-in should substitute the Calling Station Id for the RADIUS User Name before attempting to perform an inner authentication check. The default is not to make this substitution.

Default value is 0.

Important: At any given instance, you can set only one of these parameters (UseSubjectCNAsUserName, UsePrincipalNameAsUserName, UseUserNameAttributeAsUserName, UseCallingStationIdAsUserName) to 1.

UseInnerRadius

Indicates whether or not inner authentication is to be performed.

Set 1 to enable an inner authentication and 0 to disable inner authentication.

Default value is 0.

FixedPassword

By default, the secondary authorization check includes a username but no other user credentials, because no password or similar credential for the client is available at the conclusion of the TLS handshake. Some authentication methods (Native User, LDAP, and SQL) can be configured to not require user credentials.

If you plan to use secondary authorization against an authentication method (for example, LDAP) that cannot be configured to ignore the lack of user credentials, you may specify a fixed password that the plug-in uses on all secondary authorization checks.

Default is to perform the check without user credentials.

Include_Certificate_Info

If set to 1, the EAP-TLS plug-in adds four attributes to the request before the secondary authorization check is performed:

  • The Funk-Peer-Cert-Subject attribute contains the value of the Subject attribute in the client certificate.
  • The Funk-Peer-Cert-Principal attribute contains the value of the principal name (Subject Alternate Name or Other Name) attribute of the client certificate.
  • The Funk-Peer-Cert-Issuer attribute contains the value of the Issuer attribute in the client certificate.
  • The Funk-Peer-Cert-Hash attribute contains a hexadecimal ASCII representation of the SHA1 hash of the client certificate.

These attributes are ignored if the authentication method that performs the authentication check does not use them.

Default value is 0.

RequestFilter

Indicates the filter to be used to edit the attributes used in the inner authentication request. The filter can be used to modify attributes to influence routing of the inner authentication through attribute editing realm selection.

Filter is not applied by default.

ResponseFilter

Indicates the filter to be used to edit attributes in the authentication response.

Filter is not applied by default.

ProfileAttribute

Indicates response attribute from the inner authentication method can contain the name of a profile to apply to the Access-Accept message.

The profile name will be present in the attribute returned from the response. If the profile name is not available in the SBR, an Access-Reject message is sent.

Profile is not applied by default.

Realm

Indicates directed or proxy realm to which inner authentication requests will be sent.

If a realm name is configured in the SBR, all inner authentications will be forwarded to the realm. If a realm name is not configured, then standard authentication takes place as defined in the proxy.ini file

The default is standard authentication.

[CRL_Checking] Section

The [CRL_Checking] section (Table 122) lets you specify settings that control how Steel-Belted Radius Carrier performs certificate revocation list (CRL) checking.

Table 122: tlsauth.eap [CRL_Checking] Syntax

Parameter

Function

Enable

Specifies whether CRL checking is enabled.

Default value is 0 (disabled).

Retrieval_Timeout

Specifies the time (in seconds) that EAP-TLS waits for a CRL checking transaction to complete when the CRL check involves a CRL retrieval. When CRL retrieval takes longer than the specified time, the user's authentication request results in a reject.

Default value is 5 seconds.

Expiration_Grace_Period

Specifies the time (in seconds) after expiration during which a CRL is still considered acceptable. EAP-TLS always attempts to retrieve a new CRL when it is presented with a certificate chain and it finds an expired CRL in its cache.

  • If set to 0 (strict expiration mode), EAP-TLS does not accept a CRL that has expired.
  • If set to a value greater than 0 (lax expiration mode), EAP-TLS considers the expired CRL as an acceptable stand-in from the time the CRL expires to the time the grace period ends.

Default value is 0 (strict expiration mode).

Allow_Missing_CDP_Attribute

Specifies whether the omission of a CDP attribute in a non-root certificate is acceptable. Without a CDP attribute, EAP-TLS does not know how to retrieve a CRL and cannot perform a revocation check on the certificate.

  • If set to false, EAP-TLS does not accept a CRL with a missing CDP attribute.
  • If set to true, EAP-TLS allows such certificates and skip CRL checking for them.

Default value is true.

Default_LDAP_Server_Name

Specifies what LDAP server name to use if the CDP contains a value that begins with the string //ldap:\\\. This style of CDP (generated by some CAs) does not include the identity of the LDAP server.

Specify the name of the LDAP that contains the CRLs if you expect to encounter certificates with this style CDP. If you do not specify a server name and such certificates are encountered, the CRL retrieval fails.

LDAP_Bind_Version

Enables the selection of the LDAP protocol when binding to an LDAP server (2 or 3)

The default is 2 (LDAP version 2)

[Session_Resumption] Section

The [Session_Resumption] section lets you specify whether session resumption is permitted and under what conditions session resumption is performed. The [Session_Resumption] section consists of the parameters listed in Table 123.

Note: For session resumption to work, the network access server must be configured to handle the Session-Timeout return list attribute, because the network access server must be able to tell the client to reauthenticate after the session timer has expired.

Table 123: tlsauth.eap [Session_Resumption] Syntax

Parameter

Function

Session_Timeout

Set this attribute to the maximum number of seconds you want the client to remain connected to the network access server before having to reauthenticate.

  • If set to a number greater than 0, the lesser of this value and the remaining resumption limit (see description below) is sent in a Session-Limit attribute to the RADIUS client on the RADIUS Access Accept response.
  • If set to 0, no Session-Limit attribute is generated by the plug-in. This does not prevent the authentication methods performing secondary authorization from providing a value for this attribute.

Default value is 0.

Entering a value such as 600 (10 minutes) does not necessarily cause a full reauthentication to occur every 10 minutes. You can configure the resumption limit to make most reauthentications fast and computationally cheap.

Termination_Action

Specifies the value to return for the Termination-Action attribute sent for an accepted client. This is a standard attribute supported by most Access Points and determines what happens when the session timeout is reached. Valid values are:

  • -1: Do not send the attribute.
  • 0: Send the Termination-Action attribute with a value of 0.
  • 1: Send the Termination-Action attribute with a value of 1.

Default value is -1. This does not prevent the authentication methods performing secondary authorization from providing a value for this attribute.

Resumption_Limit

Set this attribute to the maximum number of seconds you want the client to be able to reauthenticate using the TLS session resumption feature.

This type of reauthentication is fast and computationally cheap. It does, however, depend on previous authentications and may not be considered as secure as a complete (computationally expensive) authentication. Specifying a value of 0 disables the session resumption feature.

Default value is 0.

Sample tlsauth.eap File

[Bootstrap]
LibraryName=tlsauth.so
Enable=1

; Maximum TLS Message fragment length
TLS_Message_Fragment_Length = 1020

; Indicates whether the EAP-TLS module is to check
; whether the User Name provided in the RADIUS request
; matches the principal name in the client's certificate.
Verify_User_Name_Is_Principal_Name = 1

; Indicates whether the EAP-TLS module should return
; the MS-MPPE-Send-Key and MS-MPPE-Recv-Key attribute upon
; successfully authenticating the user.
Return_MPPE_Keys = 1

; Specifies the size of the prime to use for DH modular
; exponentiation.
DH_Prime_Bits = 1536

[Secondary_Authorization]
; Indicates whether secondary authorization is to be
; performed. Set to 1 to require a secondary authorization
; check against traditional authentication method
; (for example, SQL plug-in)
Enable = 1

; Indicates whether the plug-in should substitute the CN
; contained in the client certificate for the RADIUS User
; Name before the secondary authorization check
Convert_User_Name_To_Subject_CN = 1

; Indicates whether the plug-in should substitute the
; principal name contained in the Subject Alternate Name
; (Other Name) field of the client certificate for the
; RADIUS User Name before secondary authorization check.
Convert_User_Name_To_Principal_Name = 0

; Indicates whether the secondary authorization check
; should use no user credentials or a fixed password.
FixedPassword = test

; Indicates whether attributes containing information
; about the client certificate should be added to the
; request before secondary authorization is performed.
; The attributes include Funk-Peer-Cert-Subject,
; Funk-Peer-Cert-Principal, Funk-Peer-Cert-Issuer, and
; Funk-Peer-Cert-Hash. The default is not to include
; these attributes.
;Include_Certificate_Info = 0

[Session_Resumption]
; Maximum length of time (in seconds) the RAS/AP
; allows the session to persist before the client is asked
; to reauthenticate.
Session_Timeout = 600

; The value to return for the Termination-Action attribute
; sent in an accepted client.
Termination_Action = 0

; The length of time (in seconds) during which an
; authentication request that seeks to resume a previous
; TLS session is considered acceptable.
Resumption_Limit = 3600

Configuring Secondary Authorization

The EAP-TLS plug-in may be configured to perform a secondary authorization check that typically requires a traditional authentication method that can be configured to authenticate users without the presence of credentials.

Examples for the Oracle SQL plug-in and the LDAP plug-in authentication are provided below.

SQL Authentication

The .aut file below shows an example of how the Oracle SQL plug-in can be configured so that password information is not required as input or output.

To configure these two plug-ins to cooperate, no password has been given in the SQL= string entry in the [Settings] section, and the Password= entry in the [Results] section has been similarly left empty.

[Settings]
SQL=SELECT FullName FROM orasqlauth WHERE username = %Name/50s

[Results]
; Empty definition of Password= indicates password to be ignored,
; since EAP-TLS is assumed to have already authenticated the user.
Password=
FullName=1/255s
;Profile=2/48
;Alias=3/48

For more information, see SQL Authentication.

If the SQL authentication method used for secondary authorization is intended to be used only in conjunction with EAP-TLS, use Web GUI to set EAP-Only=1 and EAP-Type=TLS in the appropriate section of the eap.ini file to prevent unintended use of this SQL authentication method for traditional authentication requests.

LDAP Authentication

The .aut file below shows an example of how the LDAP plug-in can be configured so that password information is not required as input or output.

To configure the EAP-TLS and LDAP plug-ins to cooperate properly, the BindName= option has been utilized in the [Settings] section to log into the LDAP server and no %password= setting has been specified in the [Response] section.

[Settings]
BindName=uid=admin,ou=administrators,o=bigco.com
BindPassword=adminPassword

Search=DoLdapSearch



[Request]
%Username=User-Name

[Response]
%profile=TheUserProfile

[Search/DoLdapSearch]
Base=ou=Special Users,o=bigco.com
Scope=2
Filter=(uid=<User-Name>)
Attributes=AttrList
Timeout=20
%DN=dn

For more information, see LDAP Authentication.

If the LDAP authentication method used for secondary authorization is intended to be used only in conjunction with EAP-TLS, use Web GUI to set EAP-Only=1 and EAP-Type=TLS in the appropriate section of the eap.ini file to prevent unintended use of this LDAP authentication method for traditional authentication requests.

Modified: 2017-09-27