There are two types of PEAP-TLVs used by IAS and WPS:

Status-Result PEAP-TLV with Type=3. The Status-Result PEAP-TLV is sent by the IAS server and provides client computers with an authentication response (either accept or reject).

URL PEAP-TLV with Type=8. The URL PEAP-TLV is sent by an IAS extension DLL that you create and install on your IAS servers. The URL PEAP-TLV provides client computers with the location of the provisioning server so that the client can download XML files from the server.

IAS always sends a Status-Result PEAP-TLV containing an authentication response. Depending upon circumstances outlined below, your IAS extension DLL might include a URL PEAP-TLV inside the same message as the Status-Result PEAP-TLV.

The process for providing your IAS servers with an extension DLL capable of processing messages is as follows:

Create an IAS extension DLL that can identify and act upon access requests that should be provisioned and allowed, while passing through all other access requests without any modifications.

Add the DLL to the Windows registry, so that IAS calls the DLL during the processing of each message. After your DLL identifies an access request upon which it needs to act, it changes the access request into a successful attempt (if the access request was previously marked for rejection), and the DLL will inject the URL PEAP-TLV into the response. In addition, the DLL might also add RADIUS Tunnel attributes or otherwise request that a network restriction be enforced for the current client. The PEAP-TLVs are sent inside the last PEAP Access-Challenge message; the overall authentication result, along with any RADIUS Tunnel attributes, is sent in the final Access-Accept message. The client uses the specified URL PEAP-TLV, which contains an HTTPS URL and an action parameter, to contact a provisioning server and obtain XML files.

The value of the URL PEAP-TLV, which is sent in the PEAP channel and is encrypted and integrity-checked, provides the client with the following information:

The location of the provisioning information, in the form of an HTTPS URL, which is needed by the client to access the provisioning server. An example URL is: https://www.example.com/provisioning/master.xml.

The action parameter, which represents the action the WISP requires of the client to access the WISP. This action and the pound sign character (#) are appended to the HTTPS URL sent in the URL PEAP-TLV. There are four possible actions that can be configured in a URL PEAP-TLV:

Sign up. This value is passed by IAS to the client when the customer has authenticated as guest or attempts authentication as an unknown user and does not have a valid user account. An example value for the URL PEAP-TLV is: https://www.example.com/provisioning/master.xml#signup, where #signup is the parameter for this action.

Renewal. This value is passed by IAS to the client when the customer's user account is expired and needs renewal before network access can be granted. An example value for the URL PEAP-TLV is: https://www.example.com/provisioning/master.xml#renewal, where #renewal is the parameter for this action.

Password change. This value is passed by IAS to the client when the customer is required to change the account password. An example value for the URL PEAP-TLV is: https://www.example.com/provisioning/master.xml#passwordchange, where #passwordchange is the parameter for this action.

Force update. This value is passed by IAS to the client when the WISP requires the Windows XP-based client to download an updated XML master file. This method of updating the XML master file on the client should be used only to correct errors; otherwise, the TTL expiry time in the XML master file is used to provide background updates. An example value for the URL PEAP-TLV is: https://www.example.com/provisioning/master.xml#forceupdate, where #forceupdate is the parameter for this action.

WPS technology on client computers running Windows XP with SP2 evaluates which URL PEAP-TLV values sent by the IAS server are valid based upon whether the client has authenticated as guest or has authenticated with credentials for a valid user account.

When the client has authenticated as guest, WPS technology on the client accepts and utilizes a URL PEAP-TLV that includes the sign-up action parameter (#signup). This allows customers who do not yet have an account to do the following:

Download the XML files that contain the sign-up wizard

Run the sign-up wizard

Create an account

This is the only circumstance under which WPS technology on the client will download and run the sign-up wizard.

When the client has authenticated with credentials for a valid user account, WPS technology on the client ignores a URL PEAP-TLV that contains the sign-up action parameter (#signup). WPS technology on the client will, however, respond to URL PEAP-TLVs that contain the renewal action parameter (#renewal), the password change action parameter (#passwordchange), and the force update action parameter (#forceupdate) by downloading the appropriate XML files and running the wizard specified by the action parameter.

IAS supports both authentication extension DLLs and authorization extension DLLs. Authentication DLLs validate credentials against a user account database; authorization DLLs are processed after authentication DLLs and are used to modify the result sent back to the client computer. IAS extension DLLs for WPS technology are authorization DLLs.

When IAS starts, it automatically loads all registered extension DLLs. Extension DLLs can then inspect and modify every RADIUS message received and sent by IAS.

When you create your IAS extension DLL, make sure that it can perform the following functions within the IAS processing cycle:

Recognize particular types of authentication attempts (both accepted and rejected attempts).

Convert these types of authentication attempts into accepted attempts based on the WPS technology business rules that you have defined in IAS remote access policies and in your sign-up wizard, renewal wizard, and other XML files.

Add provisioning information, such as a URL PEAP-TLV containing the URL of the provisioning server and an action parameter, to the responses sent to client computers connected to your Wi-Fi hotspots.

Provide information that allows IAS to isolate clients to a network where they can access resources, such as the provisioning server and the IAS server, used when signing up for accounts.

As with all extension DLLs, a WPS technology extension DLL must first identify and ignore all RADIUS messages that are not relevant to its function. When the DLL recognizes a message that it might need to modify, it must inspect the following:

The type of message being processed.

The current authentication result.

The user name being authenticated.

Then, based on the business logic appropriate to your deployment of WPS technology, the extension DLL should decide whether the response should:

Be converted into a successful authentication attempt.

Have provisioning information added to the message, and/or:

Indicate to a layer three network device (for example, a wireless access point) that the client computer should be allowed restricted access to the network.

Finally, the WPS technology extension DLL should perform any changes that it determines are appropriate.

As previously described, provisioning information consists of a RADIUS ratEAPTLV attribute (type 273), containing a URL PEAP-TLV whose value contains a URL string and an action parameter.

A WPS Extension DLL must implement the following API functions, which are called by IAS:

RadiusExtensionInit() This API allows the DLL to perform one-time initialization actions.

RadiusExtensionTerm() This API allows the DLL to perform one-time clean-up and termination actions.

RadiusExtensionProcess2() This API is called for every RADIUS message received by IAS.

The following structures, attribute names, and attribute values are defined in the SDK header file authif.h. For more information, see MSDN.

pECB The RADIUS_EXTENSION_CONTROL_BLOCK pointer parameter passed into RadiusExtensionProcess2().

pRequest The RADIUS_ATTRIBUTE_ARRAY pointer containing the RADIUS attributes that make up the RADIUS request packet from the client host.

pResponse(X) The RADIUS_ATTRIBUTE_ARRAY pointer containing the RADIUS attributes that make up the RADIUS response packet of the specified type (e.g., pResponse(REJECT)).

Your WPS technology IAS extension DLL must perform the following actions:

Message Filter. The WPS extension DLL should ignore all messages, except those that match the following criteria:

a.        The message must be at the authorization stage of IAS processing.

pECB->repPoint == repAuthorization

b.        The inbound message must be an ACCESS_REQUEST.

pECB->rcRequestType == rcAccessRequest

c.        The outbound message must be an ACCESS_CHALLENGE.

pECB->rcResponseType == rcAccessChallenge

d.        The response message must contain a RADIUS ratEAPTLV attribute (type 273).

To perform this check, the DLL must scan all RADIUS attributes in the response to discover whether the attribute ratEAPTLV (type 273) is present.

Message Inspection. The WPS extension DLL should obtain the following information about the authentication attempt:

a.        RADIUS connection request policy (CRP) used to process this request (RADIUS attribute ratPolicyName = 270 = remote access policy name; ratCRPPolicyName = 275 = connection request policy name).

b.        Reject Reason Code (RADIUS attribute ratRejectReasonCode (type 274))

c.        Username (checking both ratUserName (type 1) and ratFQUserName (type 269))

d.        Overall authentication result, from the RADIUS ratEAPTLV attribute (type 273) containing the Status-Result TLV (type=3) (possible values: Success(1) or Failure(2))

Message Analysis. The following business logic is recommended, but can be adapted as appropriate:

a.        You can design the DLL to choose to perform completely different business logic based on the RADIUS connection request policy name used to process the request. This allows you to configure the IAS server with remote access policies that identify users based on any supported criteria, then have the extension DLL impose greater or fewer restrictions for different types of accounts based on the remote access policy that was used.

b.        Within a request the Reject Reason Code should take precedence over the other values. If this RADIUS attribute is present, the message should be processed according to the reason code specified. This can have one of the following values:

i rrrcAccountUnknown(1)

The authentication attempt is using a user name that does not correspond to any known account. (Suggested action parameter: 'signup')

ii.   rrrcAccountDisabled(2)

The authentication attempt is using a user name that corresponds to an account that has been disabled by an administrator. (Suggested action parameter: 'signup')

iii.   rrrcAccountExpired(3)

The authentication attempt is using a user name that corresponds to an account that has been expired, either by exceeding its natural expiration lifetime or by administrative action. (Suggested action parameter: 'renew')

iv.   rrrcAuthenticationFailure(4)

The authentication attempt is using a user name and password pair that are incorrect for the corresponding account. (Suggested action parameter: 'signup')

You can design the DLL to choose how to respond to each of these types of failures independently, based on the business logic appropriate to your needs.

The DLL may choose to respond to all types of failures equally, to respond to some types of failures differently than others, or to ignore one or more types of failures. The suggested behavior for the extension DLL is that for each type, the failure is converted to a success and provisioning information is added with the action parameters listed above.

c.        The user name should have the next level of precedence. This is where the DLL can determine whether the current authentication attempt is using a guest account or a valid user account.

i.   Guest account attempts should be handled by both the DLL and an IAS connection request policy - the DLL should add the provisioning information, while the connection request policy should add network restriction information.

ii.   Normal user authentication attempts must be recognized as such, but the DLL must not make a decision until it has considered the overall authentication result.

d.        For Normal user authentication, the overall authentication result must be checked.

i.   If the attempt was successful, the response may be modified as described above; typically, however, it should not be modified.

Adding provisioning information would cause users who are allowed onto the network to also receive a balloon asking for an account sign-up, renewal, or password change. In situations when these behaviors are desired, then provisioning information may be added.

Adding restricted network information would mean that users who have proven that they have valid credentials would only have access to a limited part of the network. In situations when these behaviors are desired, then restricted network information may be added.

ii.   If the attempt was unsuccessful, for a reason not already specified by the Reject Reason Code, then the attempt must not be modified. Attempts that are rejected without a corresponding Reject Reason Code are typically rejected for true error conditions; this can include requests attempting to use an EAP type not configured on the IAS server, corrupted messages, and so forth - all true errors where an Accept response should not be sent to the end user.

Message Modification. The following changes can be performed on the response message:

a.        Convert to success.

Find the RADIUS ratEAPTLV attribute (type 273) that contains the Status-Result TLV (type 3), then directly set its data value to Success(1) (modifying the value in place). Because this data value contains a short int in network byte order, you can use the following line of code for the assignment stage:

pEapTlvIn->Value[1] = MS_PEAP_AVP_VALUE_SUCCESS;

b.        Add provisioning information.

Allocate enough memory for an EAP-TLV structure, set the type to URL PEAP-TLV (type 8), set the length as appropriate, and copy the URL string into the TLV's value buffer. Then, add a RADIUS ratEAPTLV attribute (type 273) whose data value points to the EAP-TLV data structure.

c.        Add restricted-network attributes.

This involves adding RADIUS attributes to the response, to indicate to the Wi-Fi hotspot's network hardware that network restrictions should be associated with the given end-user's client computer. These restrictions can be imposed by the 802.11 wireless access point or by a network switch or router between the access point and the rest of the network.

Different network hardware provides different methods for imposing network restrictions; the attributes to be added will depend on the network hardware in use.

For example, if VLANs are deployed for client isolation then the following RADIUS attributes could be added to the response, to direct the network hardware to place the client on VLAN 0:

ratFramedProtocol (type 7) = PPP(1)

ratTunnelType (type 64) = TUNNEL_TYPE_VLAN(13)

ratMediumType (type 65) = TUNNEL_MEDIUM_TYPE_802(6)

ratTunnelPrivateGroupID (type 81) = '0' (0x30, 0x00)

ratTunnelTag (type 4170) = [obtain value from hardware-specific documentation]

For more information about creating an IAS extension DLL, see the following topics:

RADIUS_EXTENSION_CONTROL_BLOCK (Internet Authentication Service Extensions: Platform SDK) at https://go.microsoft.com/fwlink/?LinkId=20041. The RADIUS_EXTENSION_CONTROL_BLOCK structure provides information about the current RADIUS request. It also provides functions for obtaining the attributes associated with the request, and for setting the disposition of the request.

GetRequest (Internet Authentication Service Extensions: Platform SDK) at https://go.microsoft.com/fwlink/?LinkId=20042. The GetRequest function returns the attributes received in the RADIUS request process and any internal attributes describing the request state.

RadiusExtensionTerm (Internet Authentication Service Extensions: Platform SDK) at https://go.microsoft.com/fwlink/?LinkId=20043. The RadiusExtensionTerm function is called by IAS prior to unloading the Extension DLL. Use RadiusExtensionTerm to perform any clean-up operations for the Extension DLL.

Internet Authentication Service Extensions at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/ias/ias/ias_start_page.asp

To order a Platform Software Development Kit (SDK) CD, see Microsoft Platform SDK at https://go.microsoft.com/fwlink/?LinkId=20044.

The Protected Extensible Authentication Protocol (PEAP), described in RFC 2284, provides a standard mechanism for support of multiple authentication types. Using PEAP-TLV, it is possible for various types of data to be passed directly between the IAS server and the PEAP client, and to provide functionality that is not included in RFC 2284 without defining a multiplicity of new PEAP types. The following table describes PEAP-TLV packet types:

The following section provides detailed descriptions of the PEAP-TLV URI Packet and the PEAP-TLV Result Packet.

PEAP-TLV URI Packet

The PEAP-TLV URI packet contains a Type-Length-Value (TLV) object.

Fields

MandatoryRequirement

Data type: BINARY

Mandatory TLV packet, set to 0.

TLVReserved

Length: 1

Data type: BINARY

Reserved. Value is zero.

TLVType

Length: 14

Data type: BINARY

TLV attribute type.

TLVValueLength

Data type: UCHAR

Length of TLVValue field.

TLVValue

Data type: UCHAR

URI to a master document.

*Meaning definitions

Signup should be returned by the ISP in the TLV when the user name in the authentication is guest or an unknown user name.

Renewal should be returned by the ISP in the TLV when the user name's account needs renewal by the user

Passwordchange should be returned by the ISP in the TLV when the user should change the password for the account.

Forceupdate should be returned by the ISP in the TLV when the ISP needs the client to update the provisioning files as soon as possible. This should not normally be used to update the files; the TTL expiry time in the master file should be used to allow the files to be updated in the background instead. Forceupdate should be used only to correct an error in the XML files.

PEAP-TLV Result Packet

The PEAP-TLV Result Packet provides support for acknowledged success and failure messages.

Fields

MandatoryRequirement

Length: 1

Data type: BINARY

Mandatory TLV packet, set to 1.

TLVReserved

Length: 1

Data type: BINARY

Reserved. Value is zero.

TLVPacketType

Length: 14

Data type: BINARY

TLV packet type. Value is 3.

TLVStatusLength

Data type: USHORT

Length of the TLVStatus field. Value is 2.

TLVStatus

Data type: USHORT

TLV status.

PEAP-TLV is a 'special case' type, more similar to the Identity and Notification types than to the authentication types such as MD5-Challenge (RFC 2284). PEAP-TLV differs from the Identity and Notification types in that a peer may respond to an EAP-TLV request with a Nak Response. This is allowed for backward compatibility with implementations that do not support the PEAP-TLV type.