RADIUS Interface for Cisco SPS
RADIUS Preauthentication for Cisco SPS
Downloads: This chapterpdf (PDF - 265.0KB) The complete bookPDF (PDF - 1.63MB) | Feedback

RADIUS Preauthentication for Cisco SPS

Table Of Contents

RADIUS Preauthentication for Cisco SPS

RADIUS Preauthentication for Cisco SPS Overview

RADIUS Access-Request Format

Code

Identifier

Length

Authenticator

Request Authenticator

Response Authenticator

Attributes

Standard Attributes

Vendor Specific Attributes

Configuring RADIUS Preauthentication

RPMS Module Directives

Preauthentication-Related SIP Server Core Directives

Configuration Example and Call Flows with Debugging Enabled

INVITE-Accepted Scenario

Configuring the INVITE-Accepted Scenario

Call Flow

RADIUS Debugging File

Cisco SPS error_log File

INVITE-Rejected Scenario

Configuration

Call Flow


RADIUS Preauthentication for Cisco SPS


Preauthentication is a process in which Cisco SPS sends a preauthentication query in the form of an Access-Request packet to a Resource Policy Management System (RPMS) to check policy limits of the matching customer. If RPMS determines that the customer limits will not be exceeded on accepting this call, RPMS sends an Access-Accept response to Cisco SPS. On the other hand, if RPMS detects that accepting this call violates the policy agreement, RPMS sends an Access-Reject response to Cisco SPS.

RADIUS Preauthentication for Cisco SPS Overview

You can configure Cisco SPS to send RADIUS Access-Request packets that correspond to SIP INVITE requests that are received from a configurable set of previous-hop devices. RPMS maps the previous-hop IP address to a entity with a specified service-level agreements (SLA). The SIP INVITE is either accepted or rejected by Cisco SPS based on the response it receives from RPMS. This allows Cisco SPS to be used to offload downstream gateways by proactively rejecting calls that would ultimately fail due to SLAs being exceeded. These calls are then redirected without expending gateway resources. The high-level diagram in Figure 12 shows a SIP INVITE from a previous hop for which preauthentication is required by Cisco SPS, as well as by the corresponding RADIUS Access-Request packet sent by Cisco SPS to RPMS. Forwarding the INVITE to the appropriate downstream gateway or proxy by Cisco SPS depends on the response Cisco SPS receives from RPMS.

Figure 12 Preauthentication Components

Preauthentication, when enabled, is performed on INVITEs before any user authentication is performed by Cisco SPS. RPMS appears as a standard RADIUS server to Cisco SPS. All preauthentication Access-Request packets go to RPMS, but all user authentication Access-Request packets and Accounting records are sent to the configured authentication and accounting RADIUS servers as if preauthentication were not enabled. If the preauthentication query fails (Accept-Reject message received from RPMS), Cisco SPS sends a 480 response back upstream. If it succeeds (Accept-Accept message received from RPMS), Cisco SPS proceeds with normal processing and eventually forwards the INVITE to the appropriate next hop.

RADIUS Access-Request Format

A summary of the RADIUS data format, as defined in RFC 2865 and RADIUS Extension for Digest Authentication follows. The fields are transmitted from left to right.


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Code      |  Identifier   |            Length             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   |                         Authenticator                         |
   |                                                               |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Attributes ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-

Code

The Code field is one octet and identifies the type of RADIUS packet. RADIUS access codes (decimal) are assigned as follows:

1. Access-Request code (request sent by Cisco SPS)

2. Access-Accept code (returned by RADIUS server if SIP request should be accepted)

3. Access-Reject code (returned by RADIUS server if SIP request should be rejected)

Upon receipt of an Access-Request packet, the RADIUS server must transmit an Access-Accept or Access-Reject reply. If all attribute values received in an Access-Request packet are acceptable, then the RADIUS server must transmit a packet with the Code field set to 2 (Access-Accept). If any value of the received Attributes is not acceptable, then the RADIUS server must transmit a packet with the Code field set to 3 (Access-Reject).

Identifier

The Identifier field is one octet and aids in matching requests and replies. The RADIUS server can detect a duplicate request if it has the same client source IP address and source UDP port and Identifier field value within a short span of time. Cisco SPS changes the Identifier field whenever the content of the Attributes field change, and whenever a valid reply has been received for a previous request. For retransmissions where the contents are identical, the Identifier field value remains unchanged. Cisco SPS uses monotonically increasing identifiers that wrap around to 1 once they reach 254.

Length

The Length field is two octets and indicates the length of the packet including the Code, Identifier, Length, Authenticator, and Attribute fields. Octets outside the range of the Length field are treated as padding and ignored on reception. If a packet is shorter than the Length field indicates, it must be silently discarded. The minimum value for the Length field is 20 and maximum value is 4095. If Cisco SPS is configured to include more headers than fit within the maximum length, the Access-Request packet is truncated.

Authenticator

The Authenticator field is sixteen (16) octets. The most significant octet is transmitted first. The Authenticator value is used to authenticate the messages between the client and the RADIUS access server.

Request Authenticator

In Access-Request packets, the Authenticator value is a 16 octet random number, called the Request Autheticator. The value is unpredictable and unique over the lifetime of aa shared secret between Cisco SPS and the RADIUS server because repetition of a request value with the same secret permits an attacker to reply with a previously intercepted response. The shared secret is configured on Cisco SPS as described in the "Authentication Module Directives" section on page 30.

Response Authenticator

The Authenticator field in an Access-Accept and Access-Reject packet is called the Response Authenticator and contains a one-way MD5 hash calculated over a stream of octets, consisting of the RADIUS packet that begins with the Code field, including the Identifier, the Length, the Request Authenticator field from the Access-Request packet, and the response Attributes, followed by the shared secret. That is, ResponseAuth = MD5 (Code+ID+Length+RequestAuth+Attributes+Secret) where + denotes concatenation. The shared secret that is configured on the RADIUS server must match the one that is configured on Cisco SPS.

On reception of an Access-Accept packet, the Response Authenticator field must contain the correct response for the pending Access-Request packet. Invalid packets are discarded by Cisco SPS and an error is logged in the error_log file.

Attributes

The Attributes field is variable in length and contains a list of attributes. Attributes may have multiple instances. The end of the list of attributes is indicated by the Length field of the RADIUS packet. The following is a summary of the Attribute field format. The fields are transmitted from left to right.


    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |  Value ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Standard Attributes

The standard RADIUS attributes in RFC 2865 included in Access-Request packets from Cisco SPS are listed in Table 10. The Attribute column is for illustrative purposes only because it is not a field in the actual attributes that are included in the request. The Length field is in octets and is 1 (for the Type field) + 1 (for the Length field) + length of the Value field.

Table 10 Standard Attributes for Access-Request Packets

Attribute
Type
Length
(octets)
Value

User Name

1

3-254

User part of the URL in the "From" SIP header or user in "Proxy-Authorization" SIP header, if present. This is controlled by a configuration directive (OrigUserNameSource).

If the RadiusUserNameAttrAddDomain directive is On, the domain in the "From" header is appended to the User Name attribute and the User Name attribute is in the name@domain format.

The UserName can be expanded to a fully expanded E164 number. If the user name is taken from the "From" header, the expansion is dependent on the user type and the NumericUserNameInterpretation directive. If the User Name is taken from the "Proxy-Authorization" header, the expansion is dependent on the NumExpandAuthUserName directive. Expansion is based on the number expansion rules which are defined in the number expansion module.

Example: "5000"

Example: "+1xxxyyy1212"

Example: "bob@foo.com"

Service-Type

6

6

Cisco SPS always sets it to 10 (Call-Check), indicating to RPMS that this is a preauthentication request.

Example: "10"

Vendor-Specific

26

7-254

See Table 2 on page 10 for the complete set.

Called-Station-ID

30

3-254

"To" SIP header value of the request.

Example: "<sip:5004@foo.com>"

Acct-Session-ID

44

3-254

"Call-Id" SIP header value of the request.

Example: "003094c3-ad5f5e93-2351ccb4-436f323d@a.22.76.38"


Vendor Specific Attributes

A summary of the VSA format is as follows:


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |  Length       |            Vendor-Id
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        Vendor-Id (cont)           |  Vendor-Type   | Vendor-Length|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Vendor-Data ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-
       

The values of these fields for Accounting-Request packets from Cisco SPS are:

Type = 26 (indicating Vendor-Specific)

Length = 7-254 octets

Vendor-ID = 9 (Cisco's Vendor-ID for all VSAs used by Cisco SPS)

Vendor-Type, Vendor-Length, and Vendor-Data take various values as summarized in Table 2 on page 10.

The Attribute column is for illustrative purposes only because it is not a field in the actual attributes that are included in the request. The Vendor-Length field is in octets and is 1 (for the Vendor-Type field) + 1 (for the Vendor-Length field) + length of the Vendor-Data field. For additional details on all Cisco VSAs, see http://www.cisco.com/univercd/cc/td/doc/product/access/acs_serv/vapp_dev/vsaig3.htm#27593.

Table 11 Cisco VSAs for Access-Request Packets

Attribute
Vendor Type
Vendor-Length
(octets)
Vendor Data

prev-hop-ip

1

Less than or equal to 247

Previous hop IP address as seen by the proxy.

Example: "prev-hop-ip=a.22.76.38:5060"

resource-service

1

Less than or equal to 247

Set to query to indicate that this is a preauthentication query (from a proxy), rather than an actual preauthentication request (from a gateway). There are no resources reserved as the result of a query.

Example: "resource-service=query"

call-id

1

Less than or equal to 247

"Call-ID" SIP header value.

Example: "call-id=003094c3-ad5f5e93-2351ccb4-436f323d@a.22.76.38"


Configuring RADIUS Preauthentication

You can configure Cisco SPS to send preauthentication Access-Request packets to 10 RPMS servers. For initial testing, it may be more convenient to set-up a single RPMS server only; but, in a production environment, using at least two RPMS servers for redundancy is strongly recommended.

Cisco SPS has multiple SIP message-handling processes (sipds); each process handles individual SIP messages. In the event the given INVITE is one that requires preauthentication, it is the responsibility of the sipd handling the INVITE to send the corresponding Access-Request packet. The Access-Request packet is generated and sent prior to accepting the INVITE as a valid request. In the event no response is received from any RPMS server, Cisco SPS processes the INVITE as if an Access-Accept had been received. The algorithm by which the sipd selects a RADIUS server to which to send the Access-Request packet is shown in Figure 13.

Figure 13 RPMS Request State Machine

The values of the various retransmission timers and counters, as well as the configuration of the RPMS servers, are described in "RPMS Module Directives" section and in "Preauthentication-Related SIP Server Core Directives" section.

RPMS Module Directives

The following directives are specific to the RPMS module for Cisco SPS. Reasonable default values are assigned when possible; however, it is advisable to carefully set and review the values of all these directives. The mechanisms for viewing and editing these directives are described in the Cisco SIP Proxy Server Administrator Guide. The following notes provide additional descriptions of how the directives are used and how to choose appropriate values for each directive:

PreAuthorization—Preauthorizes new INVITE requests. Valid values are On and Off. Default is Off. For preauthentication to occur, the value must be On.

PreAuthRequestType—Preauthentication request type. The only valid value with this release is Query.

RPMS_ServerIpPortSecret—List of RPMS IP addresses, port numbers, and secrets (passwords) for up to 10 servers. By default, none are specified. Values for at least one RPMS must be added for preauthentication to work properly.

PreAuthPreviousHop—IP address, hostname, or domain for up to 100 different hops, or the keyword ALL. The format of an entry is the same as that for an access list entry. For for information, see the Cisco SIP Proxy Server Administrator Guide. By default, the list is empty. For preauthentication to occur, at least one PreAuthPreviousHop must be defined.

Preauthentication-Related SIP Server Core Directives

The following directives reside in the SIP server core module, but these directives affect the authentication operation of Cisco SPS. These directives are shared across the accounting, authentication, and preauthentication modules. Reasonable default values are assigned when possible; however, it is advisable to carefully set and/or review the values of all these directives. The mechanisms for viewing and editing these directives are described in the Cisco SIP Proxy Server Administrator Guide. Additional descriptions of how the directives are used and how to choose appropriate values for each of them follow:

StatefulServer—Determines whether Cisco SPS is a transaction-stateful or transaction-stateless server. A transaction includes received request, request or requests (if forked) forwarded downstream, responses received from downstream hosts, and best response returned upstream. Valid values are:

On (stateful)—Cisco SPS remembers incoming and outgoing requests, provides reliable retransmission of proxied requests, and returns the best final responses.

Off (stateless)—Cisco SPS forgets all information once a request or response has been processed. Cisco SPS forwards requests and responses.

The default is On. If you change the value of this directive, you must restart the server. For preauthentication to work properly, this directive must be set to On.

RadiusRetransmissionInterval—Time (in milliseconds) between retransmissions to the RADIUS server. The default is 2000.

RadiusRetransmissionCount—Number of times to retransmit the current RADIUS request before deciding that a given RADIUS server is unreachable and trying the other RADIUS server. Default is 2.

RadiusRetransmissionAfterFailure—Number of retransmission attempts to send the RADIUS request if all attempts to send the previous request failed. The default is 0.

RadiusRetryTime—Time (in seconds) before retrying the first RPMS server if the server is out of service, or before trying to send a request to any RPMS server. The default is 300 (5 minutes).

Configuration Example and Call Flows with Debugging Enabled

The following sections illustrate various call scenarios and the associated SIP and RADIUS messaging for each scenario:

INVITE-Accepted Scenario

INVITE-Rejected Scenario

The components involved in the scenarios are listed in Table 12.

Table 12 Call Scenario Components

Component
Names
IP Address
Hostname

Cisco SIP Proxy Server

Cisco SPS

b.19.174.239

vvs-vitra

FreeRadius RADIUS Server

FreeRADIUS

b.19.174.128

n/a

IP Phone (Cisco 7905)

Cisco 7905

a.22.76.101

n/a

IP Phone (Cisco 7963)

Cisco 7963

a.22.77.248

n/a


INVITE-Accepted Scenario

In this example, Cisco 7963 calls a Cisco 7905 through Cisco SPS. The IP address of Cisco 7963 corresponds to the customer for whom the SLAs have not been exceeded. The INVITE is accepted, and the call succeeds.

Configuring the INVITE-Accepted Scenario

Cisco SPS is configured with preauthentication enabled for a single RPMS server. This is accomplished by modifying the default configuration with which Cisco SPS was initially installed. Table 13 provides a summary of the required modifications to the default configuration. Please refer to the "Cisco SPS Interface Reference Appendix" for screen examples showing configuration options for RADIUS-implementation.

Table 13 Cisco SPS Directives Modifications for RADIUS-based Implementation for the INVITE-Accepted Scenario

Cisco SPS Configuration Option Screen
Cisco SPS Directive
Default Value
Modified Value
RPMS

Preauthentication

Off

On

ServerIpPortSecret

Not Set

Added a row with the IP address, port, and secret of the RPMS server.

PreviousHop

Not Set

Added a row with all, specifying preauthentication should be done for INVITEs from all IP addresses.

     
     
Debug and Logs

StateMachine

Off

On

Radius

Off

On

RPMS

Off

On

LogLevel

warn

debug


Call Flow

The call flow is as shown in Figure 14.

Figure 14 INVITE-Accepted Call Flow

RADIUS Debugging File

FreeRADIUS server does not support preauthentication. There is no example for this case.

Cisco SPS error_log File

FreeRADIUS server does not support preauthentication. There is no example for this case.

INVITE-Rejected Scenario

In this example, Cisco 7963 is calling Cisco 7905 through Cisco SPS. The IP address of Cisco 7963 corresponds to the customer for which the SLAs have been exceeded, so the INVITE is rejected.

Configuration

Same as the "Configuring the INVITE-Accepted Scenario" section.

Call Flow

The call flow is shown in Figure 15.

Figure 15 INVITE Rejected