LINKSYS SPA Provisioning Guide

0 (0)

Linksys SPA Provisioning Guide

Version 3.0

Corporate Headquarters

Linksys

121 Theory Drive

Irvine, CA 92617 USA

http://www.linksys.com Tel: 949 823-1200

800 546-5797 Fax: 949 823-1100

Linksys SPA Provisioning Guide

Copyright ©2007 Cisco Systems, Inc. All rights reserved.Specifications are subject to change without notice. Linksys is a registered trademark or trademark of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries. Other brands and product names are trademarks or registered trademarks of their respective holders.

Disclaimer – Please Read:

This document contains implementation examples and techniques using Linksys, a division of Cisco Systems, Inc. and, in some instances, other company’s technology and products and is a recommendation only and does not constitute any legal arrangement between Linksys, a division of Cisco Systems, Inc. and the reader, either written or implied. The conclusions reached and recommendations and statements made are based on generic network, service and application requirements and should be regarded as a guide to assist you in forming your own opinions and decision regarding your particular situation. As well, Linksys reserves the right to change the features and functionalities for products described in this document at any time. These changes may involve changes to the described solutions over time.

Use of Proprietary Information and Copyright Notice:

This document contains proprietary information that is to be used only by Linksys customers. Any unauthorized disclosure, copying, distribution, or use of this information is prohibited.

C O N T E N T S

Preface vii
Document Audience	vii
Linksys VoIP Products		vii
How This Document is Organized viii
Document Conventions		viii
Related Documentation		ix
Technical Support	ix

C H A P T E R 1		Provisioning Linksys VoIP Devices					1-1
		Residential Deployment Provisioning Requirements 1-1
		Remote Endpoint Control				1-2
		Communication Encryption				1-2
		Provisioning Overview			1-2
		Initial Provisioning			1-3
		Deploying RC Units			1-3
		Redundant Provisioning Servers					1-4
		Retail Provisioning			1-4
		Automatic In-House Preprovisioning						1-5
		Configuration Access Control					1-5
		SPA Configuration Profiles				1-5
		SPA Provisioning Flow			1-6
		Using HTTPS 1-8
		How HTTPS Works			1-8
		Server Certificates			1-9
		Client Certificates			1-9
		Linksys Certificate Chain Structure						1-9
		Provisioning Setup		1-10
		License Keys		1-11
		Software Tools		1-11
		Server Configuration			1-11
		TFTP	1-12
		HTTP	1-12
								Linksys SPA Provisioning Guide
								Linksys SPA Provisioning Guide
	Version 3.0								iii
	Version 3.0								iii




	Contents
		Enabling HTTPS		1-13
		Syslog Server		1-15
		Where to Go From Here			1-15
		Creating Provisioning Scripts
C H A P T E R 2		Creating Provisioning Scripts				2-1
		SPA Configuration File			2-1
		Open Format Configuration File				2-2
		Configuration File Compression					2-5
		File Encryption		2-5
		SPA Configuration Profile Compiler					2-6
		Proprietary Plain-Text Configuration File 2-8
		Source Text Syntax			2-8
		Comments	2-9
		Macro Expansion			2-9
		Conditional Expressions				2-10
		Assignment Expressions				2-11
		URL Syntax	2-12
		Optional Resync Arguments 2-12
		key 2-13
		post	2-13
		alias	2-13

			Combining Options			2-14
			Using Provisioning Parameters			2-15
			General Purpose Parameters 2-15
			Enables	2-15
			Triggers	2-16
			Configurable Schedules			2-16
			Profile Rules		2-17
			Report Rule		2-19
			Upgrade Rule		2-19
			Data Types	2-20
			Provisioning Tutorial
C H A P T E R 3			Provisioning Tutorial		3-1
			Preparation	3-1
			Basic Resync	3-2
			TFTP Resync		3-2
			Syslog	3-3
			Automatic Resync 3-4
		Linksys SPA Provisioning Guide
		Linksys SPA Provisioning Guide
	iv					Version 3.0
	iv					Version 3.0

Contents

Unique Profiles and Macro Expansion 3-5
URL Resolution	3-5
HTTP GET Resync	3-6

Secure Resync	3-7
Basic HTTPS Resync		3-7
HTTPS With Client Certificate Authentication			3-9
HTTPS Client Filtering and Dynamic Content			3-9
Profile Formats	3-10
Profile Compression		3-10
Profile Encryption		3-11
Partitioned Profiles		3-12

	Parameter Name Aliases	3-12
	Proprietary Profile Format	3-13
	Provisioning Field Reference
C H A P T E R 4	Provisioning Field Reference	4-1
	Configuration Profile Parameters 4-1
	Firmware Upgrade Parameters	4-4
	General Purpose Parameters	4-6
	Macro Expansion Variables 4-7
	Internal Error Codes 4-9

A P P E N D I X	A	Acronyms
		Glossary
A P P E N D I X	B	Glossary
		Example SPA Configuration Profile
A P P E N D I X	C	Example SPA Configuration Profile

I N D E X

Linksys SPA Provisioning Guide

	Version 3.0	v

Contents

Linksys SPA Provisioning Guide

	vi	Version 3.0

Preface

This guide describes the provisioning of Linksys Voice over IP (VoIP) products. It contains the following sections:

•Document Audience, page vii

•Linksys VoIP Products, page vii

•How This Document is Organized, page viii

•Document Conventions, page viii

•Related Documentation, page ix

•Technical Support, page ix

Document Audience

This document is written for service providers who offer services using Linksys VoIP products and specifically for administrative staff responsible for remote provisioning and preprovisioning Linksys devices.

Linksys VoIP Products

The following summarizes the Linksys VoIP products that can be remotely provisioned or preprovisioned using the information provided in this document.

•SPA9000—IP PBX with Auto-Attendant; can be used with the SPA400, which provides a SIP-PSTN gateway

•Linksys Analog Telephone Adapters (ATAs):

•PAPT2T—Voice adapter with two FXS ports

•SPA1001—Small VoIP adapter

•SPA2102—Voice adapter with router

•SPA3102—Voice adapter with router and PSTN gateway

•RTP300—IP router with two FXS ports

•WRTP54G—Wireless-G IP router with two FXS ports

Linksys SPA Provisioning Guide

	Version 3.0	vii

Preface

How This Document is Organized

•SPA900 Series IP phones:

•SPA901—One line, small, affordable, no display

•SPA921—One-line business phone

•SPA922—One-line business phone with Power over Ethernet (PoE) support and an extra Ethernet port for connecting another device to the LAN

•SPA941—Default is two lines, upgradeable to four lines

•SPA942—Default is two lines, upgradeable to four lines. Power over Ethernet (PoE) support and an extra Ethernet port for connecting another device to the LAN

•SPA962—Six lines, hi-res color display. Power over Ethernet (PoE) support and an extra Ethernet port for connecting another device to the LAN

Note A Linksys VoIP device that supports the remote provisioning options described in this document is referred to generically as a SPA.

How This Document is Organized

This document is divided into the following chapters and appendices.

Chapter	Contents

Chapter 1, “Provisioning	This chapter introduces Linksys VoIP products.
Linksys VoIP Devices”

Chapter 2, “Creating	This chapter describes how to work with Linksys provisioning
Provisioning Scripts”	scripts and configuration profiles.

Chapter 3, “Provisioning	This chapter provides step-by-step procedures for using the
Tutorial”	scripting language to create a configuration profile.

Chapter 4, “Provisioning Field	This chapter provides a systematic reference for each parameter on
Reference”	the Provisioning tab of the administration web server.

Appendix A, “Acronyms”	This appendix provides the expansion of acronyms used in this
	document.

Appendix B, “Glossary”	This appendix defines the terms used in this document.

Document Conventions

The following are the typographic conventions used in this document.

		Typographic Element	Meaning

		Boldface	Indicates an option on a menu or a literal value to be entered in a field.

		<parameter>	Angle brackets (<>) are used to identify parameters that appear on the
			configuration pages of the Linksys device administration web server. The
			index at the end of this document contains an alphabetical listing of each
			parameter, hyperlinked to the appropriate table in Chapter 4, “Provisioning
			Field Reference”

	Linksys SPA Provisioning Guide
	Linksys SPA Provisioning Guide
viii			Version 3.0
viii			Version 3.0

Preface

		Related Documentation

	Typographic Element	Meaning

	Italic	Indicates a variable that should be replaced with a literal value.

	Monospaced Font	Indicates code samples or system output.

Technical Support

Technical support contact information for authorized Linksys Voice System partners is as follows:

•LVS Phone Support (requires an authorized partner PIN)

888 333-0244 Hours: 4am-6pm PST, 7 days a week

•E-mail support voipsupport@linksys.com

Linksys SPA Provisioning Guide

	Version 3.0	ix

Preface

Technical Support

Linksys SPA Provisioning Guide

	x	Version 3.0

C H A P T E R 1

Provisioning Linksys VoIP Devices

This chapter describes the features and functionality available when provisioning Linksys VoIP devices and explains the setup required. It includes the following sections:

•Residential Deployment Provisioning Requirements, page 1-1

•Provisioning Overview, page 1-2

•Configuration Access Control, page 1-5

•Using HTTPS, page 1-8

•Provisioning Setup, page 1-10

•Where to Go From Here, page 1-15

Note A Linksys VoIP device is generically referred to in this document as a SPA. Unless otherwise noted, the instructions in this document apply equally to the SPA9000, Linksys Analog Telephone Adapters (ATAs), and SPA900 Series IP phones.

Residential Deployment Provisioning Requirements

Linksys ATAs, such as the PAP2T, are primarily intended for high-volume deployments by VoIP service providers to residential and small business customers. In this scenario, units are likely to be widely distributed across the Internet, connected through routers and firewalls at the customer premises.

Further, ATAs can also serve as terminal nodes in business or enterprise environments, where the units may be operated within a self-contained LAN environment.

The ATA can be seen as a remote extension of the service provider back-end equipment. In essence, it replaces the traditional physical analog telephone line connection from a customer premise to a central office with a virtual connection, which relies on broadband Internet service to extend the central office phone line termination into the customer premises.

The ATA can assume responsibility for many of the functions that were traditionally handled at the central office. At a minimum, the ATA serves as a media conversion endpoint, offering the consumer a telephone port analogous to a traditional phone line terminal.

Remote management and configuration is required to efficiently ensure proper operation of the ATA at the customer premises. ATA configuration varies according to the individual customer and with the same customer over a period of time.

Linksys SPA Provisioning Guide

	Version 3.0	1-1

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Overview

The ATA must be configured to match the account service parameters for the individual customer. Also, configuration may need to be modified because of newly introduced service provider features, modifications in the service provider network, or firmware upgrades in the endpoint.

This customized, ongoing configuration is supported by the following features of Linksys ATAs:

•Reliable remote control of the endpoint,

•Encryption of the communication controlling the endpoint,

•Streamlined endpoint account binding.

Remote Endpoint Control

The service provider must be able to modify configuration parameters in the ATA after the unit has been deployed to the customer premises. The service provider must also be able to upgrade the endpoint firmware remotely, and both of these operations must be reliable.

In a residential deployment, the endpoint itself is typically connected in a local network, and accesses the Internet through a router using network address translation (NAT). For enhanced security, the router may attempt to block unauthorized incoming packets by implementing symmetric NAT, a packet filtering strategy which severely restricts the packets that are allowed to enter the protected network from the Internet.

Communication Encryption

The configuration parameters communicated to the endpoint may contain authorization codes or other information should not be revealed to the customer. This may be required to protect the service provider from unauthorized activity by the customer. It is also necessary to protect the customer from unauthorized use of the account by other customers.

For this reason, the service provider may wish to encrypt the configuration profile communication between the provisioning server and the endpoint, in addition to restricting access to the ATA administration web server.

Provisioning Overview

Linksys VoIP products support secure remote provisioning and firmware upgrades. Configuration profiles can be generated using common, open source tools, facilitating integration into service provider provisioning systems. Supported transport protocols include TFTP, HTTP, and HTTPS with client certificates. Linksys provisioning solutions are designed for high-volume residential deployment, where each SPA typically resides in a separate LAN environment connected to the Internet with a NAT device.

Note This Provisioning Guide is intended to supplement the product administration guides, which provide definitions and usage guidelines for each parameter available for a specific device.

The SPA can be configured to resync its internal configuration state to a remote profile periodically and on power up. Starting with firmware release 2.0, 256-bit symmetric key encryption of profiles is supported. In addition, an unprovisioned SPA can receive an encrypted profile specifically targeted for that device without requiring an explicit key. Release 2.0 supports a secure first-time provisioning mechanism using SSL functionality.

Linksys SPA Provisioning Guide

1-2	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Overview

Note Remote customization (RC) units are introduced with Release 5.x. RC units are customized by Linksys so when the unit is started, it tries to contact the Linksys provisioning server to download its customized profile.

User intervention is not required to initiate or complete a profile update or firmware upgrade. Remote firmware upgrade is achieved via TFTP or HTTP, but not using HTTPS because the firmware does not contain sensitive information that can be read by a customer. The SPA upgrade logic is capable of automating multi-stage upgrades, if intermediate upgrades are required to reach a future upgrade state from an older release. .A profile resync is only attempted when the SPA is idle, because this may trigger a software reboot.

General purpose parameters are provided to help service providers manage the provisioning process. Each SPA can be configured to periodically contact a normal provisioning server (NPS). Communication wit the NPS does not require the use of a secure protocol because the updated profile is encrypted by a shared secret key. The NPS can be a standard TFTP, HTTP or HTTPS server.

Initial Provisioning

Linksys ATAs provide convenient mechanisms for initial provisioning, based on two deployment models:

•Retail distribution, where the customer purchases the ATA separately from the VoIP service

•Bulk distribution, where the service provider issues the ATA to the customer as part of the VoIP service contract

In the first model, the customer purchases the ATA from a retail outlet, and subsequently requests VoIP service from the service provider, for use with that adapter. The service provider must then support secure remote configuration of the unit.

In the second model, the service provider acquires adapters in bulk quantity, and either preprovisions the adapters in-house or purchases RC units from Linksys.

Deploying RC Units

The in-house preprovisioning step can be eliminated by using RC units. Customization of RC units reduces the need to handle the units prior to shipping to end customers. It also discourages the use of the SPA with a different service.

The MAC address of each RC unit is associated with a customized profile for the customer who purchased each unit on a provisioning server maintained by Linksys. The RC unit is preprovisioned by Linksys with the connection information for the Linksys provisioning server. When the RC unit is started, it tries to contact the Linksys provisioning server and download its customized profile.

The status of customization for an RC unit can be determined by viewing the Customization parameter in the Product Information section of the Info tab. An RC unit that has not been provisioned displays Pending. An RC unit that has been provisioned displays the name of the company that owns the unit. If the unit is not an RC unit the web page displays Not Customized.

Linksys offers RC units to service providers for volume deployments of SPA endpoints. Through customization, the manufacturing default values of a select number of parameters can be customized to meet the needs of individual service providers.

Linksys SPA Provisioning Guide

	Version 3.0	1-3

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Overview

The following is a sample template for an RC unit:

Restricted Access Domain "domain.com, domain1.com, domain2.com";

Primary_DNS	* "x.y.w.z";
Secondary_DNS	* "a.b.c.d";
Provision_Enable	* "Yes";
Resync_Periodic	*	"30";
Resync_Error_Retry_Delay	*	"30";

Profile_Rule * "http://prov.domain.com/sipura/profile?id=$MA";

The Restricted Access Domain parameter is configured with the actual domain names of up to a maximum of five domains. The Primary_DNS and Secondary_DNS parameters are configured with the actual domain names or IP addresses of the DNS servers available to the RC unit.

Redundant Provisioning Servers

The provisioning server may be specified as an IP address or as a fully qualified domain name (FQDN). The use of a FQDN facilitates the deployment of redundant provisioning servers. When the provisioning server is identified through a FQDN, the SPA attempts to resolve the FQDN to an IP address through DNS. Only DNS A-records are supported for provisioning; DNS SRV address resolution is not available for provisioning. The SPA continues to process A-records until the first server responds. If no server associated with the A-records responds, the SPA logs an error to the syslog server.

Retail Provisioning

The SPA firmware includes an administration web server that displays SPA internal configuration and accepts new configuration parameter values. The server also accepts a special URL command syntax for performing remote profile resync and firmware upgrade operations.

In a retail distribution model, a customer purchases a Linksys voice endpoint device, and subsequently subscribes to a particular service. The customer first signs on to the service and establishes a VoIP account, possibly through an online portal. Subsequently, the customer binds the particular device to the assigned service account.

To do so, the unprovisioned SPA is instructed to resync with a specific provisioning server through a resync URL command. The URL command typically includes an account PIN number or alphanumeric code to associate the device with the new account.

In the following example, a device at the DHCP-assigned IP address 192.168.1.102 is instructed to provision itself to the SuperVoIP service:

http://192.168.1.102/admin/resync?https://prov.supervoip.com/linksys-init/1234abcd

In this example, 1234abcd is the PIN number of the new account. The remote provisioning server is configured to associate the SPA that is performing the resync request with the new account, based on the URL and the supplied PIN. Through this initial resync operation, the SPA is configured in a single step, and is automatically directed to resync thereafter to a permanent URL on the server. For example:

https://prov.supervoip.com/linksys

For both initial and permanent access, the provisioning server relies on the SPA client certificate for authentication and supplies correct configuration parameter values based on the associated service account.

Linksys SPA Provisioning Guide

1-4	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Overview

Automatic In-House Preprovisioning

Using the administration web server and issuing a resync URL is convenient for a customer in the retail deployment model, but it is not as convenient for preprovisioning a large number of units.

The SPA supports a more convenient mechanism for in-house preprovisioning. With the factory default configuration, a SPA automatically tries to resync to a specific file on a TFTP server, whose IP address is offered as one of the DHCP-provided parameters. This lets a service provider connect each new SPA to a LAN environment configured to preprovision SPAs. Any new SPA connected to this LAN automatically resyncs to the local TFTP server, initializing its internal state in preparation for deployment. Among other parameters, this preprovisioning step configures the URL of the SPA provisioning server.

Subsequently, when a new customer signs up for service, the preprovisioned SPA can be simply bar-code scanned, to record its MAC address or serial number, before being shipped to the customer. Upon receiving the unit, the customer connects the unit to the broadband link, possibly through a router. On power-up the SPA already knows the server to contact for its periodic resync update.

Configuration Access Control

Besides configuration parameters that control resync and upgrade behavior, the SPA provides mechanisms for restricting end-user access to various parameters.

The SPA firmware provides specific privileges for login to a User account and an Admin account. The Admin account is designed to give the service provider configuration access to the SPA, while the User account is designed to give limited and configurable control to the end user of the device.

The User account provides access to basic interactive voice response (IVR) functions and to a subset of the administration web server parameters. The Admin account provides full access to all IVR functions and to all administration web server parameterse.

The User and Admin accounts can be independently password protected. The configuration parameters available to the User account are completely configurable in the SPA, on a parameter-by-parameter basis. Optionally, user access to the SPA administration web server can be totally disabled. The manufacturing reset control using the IVR can also be disabled, via provisioning.

The Internet domains accessed by the SPA for resync, upgrades, and SIP registration for Line 1 can be restricted. These and other features are described in detail in administration guides for each product.

SPA Configuration Profiles

The SPA configuration profile defines the parameter values for a specific SPA device. The configuration profile can be used in two formats:

•Open (XML-style) format

•Proprietary, plain-text format

The XML-style format lets you use standard tools to compile the parameters and values. To protect confidential information contained in the configuration profile, this type of file is generally delivered from the provisioning server to the SPA over a secure channel provided by HTTPS.

The plain-text configuration file uses a proprietary format, which can be encrypted to prevent unauthorized use of confidential information. By convention, the profile is named with the extension

.cfg (for example, spa2102.cfg). The Linksys Profile Compiler (SPC) tool is provided for compiling the

Linksys SPA Provisioning Guide

	Version 3.0	1-5

Chapter 1 Provisioning Linksys VoIP Devices

SPA Provisioning Flow

plain-text file containing parameter-value pairs into an encrypted CFG file. The SPC tool is available from Linksys for the Win32 environment (spc.exe) and Linux-i386-elf environment (spc-linux-i386-static). Availability of the SPC tool for the OpenBSD environment is available on a case-by-case basis.

SPA Provisioning Flow

Firmware release 1.0 provides basic features in support of secure provisioning. This section describes the high-level provisioning flow supported by release 1.0 in the context of a service provider application. The SPA provisioning flow is illustrated in Figure 1-1.

Figure 1-1 SPA Provisioning Flow

Linksys SPA Provisioning Guide

1-6	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

SPA Provisioning Flow

At a high level, the provisioning process involves four provisioning states described in Table 1-1.

Table 1-1 Provisioning States

Flow Step	Step Description

MFG-RESET	Manufacturing reset
	Performing manufacturing reset on the SPA returns the device to a fully
	unprovisioned state. All configurable parameters regain their manufacturing
	default values.
	Manufacturing reset can be performed from any state through the IVR sequence
	****RESET#1#
	Allowing the end user to perform manufacturing reset guarantees that the device
	can always be returned to an accessible state.

SP-CUST	Service provider customization
	The provisioning parameters are customized for a particular service provider
	network. The Profile_Rule parameter must be configured in this step to point to
	a device specific configuration profile, using a service provider specific
	provisioning server.
	This can be accomplished in one of three ways:
	• Auto-configuration via local DHCP server. A TFTP server name or IPv4
	address is specified by DHCP on he local network. The indicated TFTP
	server carries the desired Profile_Rule entry in the CFG file /spa2102.cfg
	• Enter a resync URL. An end-user opens a browser onto the SPA web server,
	explicitly requesting a resync to a specific TFTP server, using this URL
	syntax: http://x.x.x.x/admin/resync?prvserv/spa2102.cfg where x.x.x.x is
	the IP address of the specific SPA and prvserv is the target TFTP server,
	followed by a profile path.
	• Edit Profile_Rule parameter. Open the provisioning pane on the SPA web
	interface, and enter the TFTP URL in the Profile_Rule parameter: for
	example, prserv/spa2102.cfg.
	The spa2102.cfg file modifies the Profile_Rule to contact a specific TFTP
	server, and request a MAC-address specific CFG file. For example, the
	following entry contacts a specific provisioning server, requesting a new
	profile unique to this unit:
	Profile_Rule tftp.callme.com/profile/$MA/spa2102.cfg;

Linksys SPA Provisioning Guide

	Version 3.0	1-7

Chapter 1 Provisioning Linksys VoIP Devices

Using HTTPS

Table 1-1 Provisioning States (continued)

SEC-PRV-1	Secure Provisioning—Initial Configuration
	The initial device-unique CFG file should be targeted to each SPA by compiling
	the CFG file with the spc --target option. This provides an initial level of
	encryption that does not require the exchange of keys.
	The initial device-unique CFG file should reconfigure the profile parameters to
	enable stronger encryption, by programming a 256-bit encryption key, and
	pointing to a randomly generated TFTP directory. For example, the CFG file
	might contain:
	Profile_Rule [--key $A] tftp.callme.com/profile/$B/spa2102.cfg;
	GPP_A 8e4ca259…;	# 256 bit key
	GPP_B Gp3sqLn…;	# random CFG file path directory

SEC-PRV-2	Secure Provisioning—Full Configuration
	The subsequent profile resync operations retrieve 256-bit encrypted CFG files,
	which maintain the SPA in a state synchronized to the provisioning server.
	All remaining SPA parameters are configured and maintained through this
	strongly encrypted profile. The encryption key and random directory location can
	be changed periodically for extra security.

Using HTTPS

The SPA provides a reliable and secure provisioning strategy based on HTTPS requests from the SPA to the provisioning server, using both server and client certificates for authenticating the client to the server and the server to the client.

To use HTTPS with Linksys SPA units, you must generate a Certificate Signing Request (CSR) and submit it to Linksys. Linksys generates a certificate for installation on the provisioning server that is accepted by the SPA units when they seek to establish an HTTPS connection with the provisioning server. This procedure is described in the “Enabling HTTPS” section on page 1-13.

How HTTPS Works

Starting with firmware release 2.0.6 , the SPA implements SSL, which lets the SPA client to connect to servers using HTTPS.

HTTPS encrypts the communication between the client and the server, protecting the message contents from other intervening network devices. The encryption method for the body of the communication between client and server is based on symmetric key cryptography. With symmetric key cryptography, a single secret key is shared by the client and the server over a secure channel protected by Public/Private key encryption.

Messages encrypted by the secret key can only be decrypted using the same key. HTTPS supports a wide range of symmetric encryption algorithms. The SPA implements up to 256-bit symmetric encryption, using the American Encryption Standard (AES), in addition to 128-bit RC4.

HTTPS also provides for the authentication of the server and the client engaged in a secure transaction. This feature ensures that the provisioning server and an individual client cannot be spoofed by other devices on the network. This is an essential capability in the context of remote endpoint provisioning.

Linksys SPA Provisioning Guide

1-8	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Using HTTPS

Server and client authentication is performed using public/private key encryption, using certificates containing the public key. Text encrypted with a public key can be decrypted only by its corresponding private key (and vice versa). The SPA supports the RSA algorithm for public/private key cryptography.

Certificates are authenticated in the context of a certificate chain. A certificate authority lies at the root of the chain, with all other certificates depending on the root authority for authority.

Server Certificates

Each secure provisioning server is issued an SSL server certificate, directly signed by Linksys. The firmware running on the SPA clients recognizes only these certificates as valid. The clients try to authenticate the server certificate when connecting via HTTPS, and reject any server certificate not signed by Linksys.

This mechanism protects the service provider from unauthorized access to the SPA endpoint, or any attempt to spoof the provisioning server. This might allow the attacker to reprovision the SPA, to gain configuration information, or to use a different VoIP service. Without the private key corresponding to a valid server certificate, the attacker is unable to establish communication with a Linksys SPA.

Client Certificates

In addition to a direct attack on the SPA, an attacker might attempt to contact a provisioning server using a standard web browser, or other HTTPS client, to obtain the SPA configuration profile from the provisioning server. To prevent this kind of attack, each SPA also carries a unique client certificate, also signed by Linksys, including identifying information about each individual endpoint. A certificate authority root certificate capable of authenticating the device client certificate is given to each service provider. This authentication path allows the provisioning server to reject unauthorized requests for configuration profiles.

Linksys Certificate Chain Structure

The combination of server certificates and client certificates ensures the secure communication between a remote SPA and its provisioning server. Figure 1-2 illustrates the relationship and placement of certificates, public/private key pairs, and signing root authorities, among the Linksys client, the provisioning server, and the Linksys certification authority.

The upper half of the diagram shows the Linksys Provisioning Server Root Authority, used to sign individual provisioning server certificates. The corresponding root certificate is compiled into all firmware releases at or above 2.0.6, allowing the SPA endpoints to authenticate authorized provisioning servers.

Linksys SPA Provisioning Guide

	Version 3.0	1-9

Chapter 1 Provisioning Linksys VoIP Devices

Using HTTPS

Figure 1-2 SPA Configuration and Provisioning Certificate Chain

SPA Configuration-Provisioning Certificate Chain

	Sipura Technology, Inc
	Provisioning Server Root Authority 1

	CERT	PKEY

Compiled into			Signs Provisioning
SPA Firmware			Server Certificates

SPA

Provisioning Server

Authenticates Server

Root CA

CERT

PKEY

in HTTPS Connection

Certificate List

VoIP Service Provider

SPA Firmware Load

Provisioning Server Entity

SPA

HTTPS Server Configuration Files

Root CA

Authenticates Client

Certificate List

PKEY

CERT

in HTTPS Connection

Signs SPA	Stored on Service Provider’s
Client Certificates	Provisioning Server

PKEY CERT

Sipura Technology, Inc

Client Certificate Root Authority 1

As indicated in the lower half of the diagram, a Linksys Client Certificate Root Authority signs each unique certificate. The corresponding root certificate is made available to service providers for client authentication purposes.

Linksys SPA Provisioning Guide

1-10	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Setup

This section describes setup requirements for provisioning a SPA and includes the following topics:

•License Keys, page 1-11

•Software Tools, page 1-11

•Server Configuration, page 1-11

•TFTP, page 1-12

•HTTP, page 1-12

•Enabling HTTPS, page 1-13

•Syslog Server, page 1-15

License Keys

Certain products within the SPA product family provide for premium features. Enabling these features requires a license key. This key is unique per feature and device. To enable a premium feature in any device, the corresponding key needs to be programmed into the <License_Keys> parameter. Once programmed, the feature remains enabled permanently. License_Keys is a write-only parameter that always appears empty when read. Contact Linksys for further information or to obtain license keys.

Software Tools

The following software tools are useful for provisioning Linksys ATAs :

•Open source gzip compression utility, used when generating configuration profiles

•Open source OpenSSL software package: for profile encryption and HTTPS operations

•Scripting language with CGI scripting support, such as the open source Perl language tools: to test dynamic generation of profiles and one-step remote provisioning using HTTPS

•Ethernet packet analyzer (such as the freely downloadable Ethereal/Wireshark): to verify secure exchanges between provisioning servers and Linksys voice devices

•The ssldump utility: for monitoring HTTPS transactions

Server Configuration

Provisioning requires the availability of servers, which for testing purposes can be installed and run on a local PC:

•TFTP (UDP port 69)

•HTTP (TCP port 80)

•HTTPS (TCP port 443)

•Syslog (UDP port 514)

To troubleshoot server configuration, it is helpful to install a separate client for each type of server on a different host.

Linksys SPA Provisioning Guide

	Version 3.0	1-11

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Setup

TFTP

TFTP is convenient for managing small deployments of SPA units within an office LAN environment. It is also useful for in-house preprovisioning of SPAs in preparation for remote deployment. However, once deployed remotely, HTTP offers greater provisioning reliability, given NAT and router protection mechanisms.

The SPA is able to obtain a TFTP server IP address directly from the DHCP server through DHCP option 66. If this is done, a Profile_Rule need be configured only with the profile filepath on that TFTP server. The Profile_Rule provided with the factory default configuration is as follows:

/spa$PSN.cfg

For example, on a SPA2102, this expands to /spa2102.cfg, which means that the unit resyncs to this file on the local TFTP server, if that is specified via DHCP option 66. Note that the specified filepath is relative to the TFTP server virtual root directory.

HTTP

The SPA behaves like a browser requesting web pages from any remote Internet site. This provides a reliable means of reaching the provisioning server, even when a customer router implements symmetric NAT or other protection mechanisms. HTTP and HTTPS works more reliably than TFTP in remote deployments, especially when the deployed units are connected behind residential firewalls or NAT-enabled routers.

As an alternative to HTTPS, the SPA can resync to a configuration profile using HTTP. In this case, a separate explicit profile encryption can be used to protect confidential information. The SPA supports 256-bit AES in CBC mode to pre-encrypt individual profiles. These encrypted profiles can be downloaded by the SPA using HTTP without danger of unauthorized use of confidential information in the configuration profile. This resync mode may be useful to reduce the computational load on the provisioning server required when using HTTPS for every resync request.

In a small deployment within a single LAN environment, it is common to rely on a simple TFTP server for provisioning of network devices. Linksys voice devices support TFTP for both provisioning resync and firmware upgrade operations. TFTP is especially useful for the in-house preprovisioning of a large number of un-provisioned devices.

Basic HTTP-based SPA provisioning relies on the HTTP GET method for retrieving configuration profiles. Typically, this means that a configuration file is pre-generated for each deployed SPA, and these files are stored within an HTTP server directory. When the server receives the GET request, it simply returns the file specified in the GET request header.

Alternatively, the requested URL can invoke a CGI script (still using the GET method). In this case, the configuration profile might be generated dynamically, perhaps by querying a customer database and producing the profile on-the-fly.

In the case of CGI handling resync requests, the SPA also supports the HTTP POST method as a mechanism to request the resync configuration data. The SPA can be configured to convey certain status and identification information to the server within the body of the HTTP POST request. The server can use this information to help generate a desired response configuration file, or store the status information for later analysis and tracking.

As part of both GET and POST requests, the SPA automatically includes basic identifying information in the request header, in the User-Agent field. The supplied information conveys manufacturer, product name, current firmware version, and product serial number.

Linksys SPA Provisioning Guide

1-12	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Setup

For example, the following is the User-Agent request field from a SPA2102:

User-Agent: Linksys/SPA-2102-2.0.5 (88012BA01234)

Enabling HTTPS

For increased security managing remotely deployed units, the SPA supports HTTPS for provisioning. To this end, each newly manufactured SPA carries a unique SLL Client Certificate (and associated private key), in addition to a Linksys CA server root certificate. The latter allow the SPA to recognize authorized provisioning servers, and reject non-authorized servers. On the other hand, the client certificate allows the provisioning server to identify the individual SPA issuing the request.

In order for a service provider to manage SPA deployment using HTTPS, a server certificate needs to be generated for each provisioning server to which the SPA resyncs using HTTPS. The server certificate must be signed by the Linksys Server CA Root Key, whose certificate is carried by all deployed units. To obtain a signed server certificate, the service provider must forward a certificate signing request to Linksys, which signs and returns the server certificate for installation on the provisioning server.

The provisioning server certificate must contain in the subject Common Name (CN field) the FQDN of the host running the server. It may optionally contain additional information following the host FQDN, separated by a / character. The following are examples of CN entries that would be accepted as valid by the SPA:

CN=sprov.callme.com

CN=pv.telco.net/mailto:admin@telco.net

CN=prof.voice.com/info@voice.com

In addition to verifying the certificate chain of the provisioning server certificate, the SPA tests the server IP address against a DNS lookup of the server name specified in the server certificate.

A certificate signing request can be generated using the OpenSSL utility. The following shows an example of the openssl command that produces a 1024-bit RSA public/private key pair and a certificate signing request:

openssl req –new –out provserver.csr

This command generates the server private key in privkey.pem and a corresponding certificate signing request in provserver.csr. In this example, the service provider keeps privkey.pem secret and submits provserver.csr to Linksys for signing. Upon receiving the provserver.csr file, Linksys generates provserver.crt, the signed server certificate.

In addition, Linksys also provides a Linksys CA Client Root Certificate to the service provider. This root certificate certifies the authenticity of the client certificate carried by each SPA.

The unique client certificate offered by each SPA during an HTTPS session carries identifying information embedded in its subject field. This information can be made available by the HTTPS server to a CGI script invoked to handle secure requests. In particular, the certificate subject indicates the unit product name (OU element), MAC address (S element), and serial number (L element). The following is an example of these elements from a SPA2102 client certificate subject field:

OU=SPA-2102, L=88012BA01234, S=000e08abcdef

Early SPA units, manufactured before firmware 2.0.x, do not contain individual SSL client certificates. When these units are upgraded to a firmware release in the 2.0.x tree, they become capable of connecting to a secure server using HTTPS, but are only able to supply a generic client certificate if requested to do so by the server. This generic certificate contains the following information in the SPA identifying fields:

OU=Linksys.com, L=Linksysgeneric, S=Linksysgeneric

Linksys SPA Provisioning Guide

	Version 3.0	1-13

Chapter 1 Provisioning Linksys VoIP Devices

Provisioning Setup

To determine if a SPA carries an individualized certificate use the $CCERT provisioning macro variable, whose value expands to either Installed or Not Installed, according to the presence or absence of a unique client certificate. In the case of a generic certificate, it is possible to obtain the serial number of the unit from the HTTP request header, in the User-Agent field.

HTTPS servers can be configured to request SSL certificates from connecting clients. If enabled, the server can verify the client certificate chain using the Linksys CA Client Root Certificate supplied by Linksys. It can then provide the certificate information to a CGI for further processing.

The location for storing certificates may vary. For example, on a Apache installation, the file paths for storing the provisioning server signed certificate, its associated private key, and the Linksys CA client root certificate are likely to be as follows:

# Server Certificate:

SSLCertificateFile /etc/httpd/conf/provserver.crt

# Server Private Key:

SSLCertificateKeyFile /etc/httpd/conf/provserver.key

# Certificate Authority (CA): SSLCACertificateFile /etc/httpd/conf/spacroot.crt

Refer to the documentation provided for an HTTPS server for specific information.

Firmware release 2.0.6 supports the following cipher suites for SSL connection to a server using HTTPS. Future release updates may implement additional cipher suites.

Table 1-2 Cipher Suites Supported for Connecting to an HTTPS Server

Numeric Code	Cipher Suite

0x0039	TLS_DHE_RSA_WITH_AES_256_CBC_SHA

0x0035	TLS_RSA_WITH_AES_256_CBC_SHA

0x0033	TLS_DHE_RSA_WITH_AES_128_CBC_SHA

0x002f	TLS_RSA_WITH_AES_128_CBC_SHA

0x0005	TLS_RSA_WITH_RC4_128_SHA

0x0004	TLS_RSA_WITH_RC4_128_MD5

0x0062	TLS_RSA_EXPORT1024_WITH_RC4_56_SHA

0x0060	TLS_RSA_EXPORT1024_WITH_RC4_56_MD5

0x0003	TLS_RSA_EXPORT_WITH_RC4_40_MD5

Linksys SPA Provisioning Guide

1-14	Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Where to Go From Here

Syslog Server

If a syslog server is configured on the SPA (using the <Syslog_Server> or <Debug_Server> parameters), the resync and upgrade operations log messages to the syslog server. A message can be generated at the start of a remote file request (configuration profile or firmware load), and at the conclusion of the operation (with either success or failure).

The logged messages themselves are configured in the following parameters: For profile resync:

•Log_Resync_Request_Msg

•Log_Resync_Success_Msg

•Log_Resync_Failure_Msg For firmware upgrades:

•Log_Upgrade_Request_Msg

•Log_Upgrade_Success_Msg

•Log_Upgrade_Failure_Msg

These parameters are macro expanded into the actual syslog messages.

Where to Go From Here

The following table summarizes the location of specific information in this document for completing different provisioning tasks.

To Do This ...	Refer to ...

Learn to work with Linksys provisioning scripts	Chapter 2, “Creating Provisioning Scripts”
and configuration profiles.

Review step-by-step procedures for using the	Chapter 3, “Provisioning Tutorial”
scripting language to create a configuration
profile.

Refer to the function and usage of each parameter	Chapter 4, “Provisioning Field Reference”
on the Provisioning tab of the administration web
server.

Look up the expansion for an acronyms use in this	Appendix A, “Acronyms”
document.

Define a term used in this document.	Appendix B, “Glossary”

Linksys SPA Provisioning Guide

	Version 3.0	1-15

Chapter 1 Provisioning Linksys VoIP Devices

Where to Go From Here

Linksys SPA Provisioning Guide

1-16	Version 3.0

C H A P T E R 2

Creating Provisioning Scripts

This chapter describes the Linksys provisioning script and includes the following sections:

•SPA Configuration File, page 2-1

•Open Format Configuration File, page 2-2

•SPA Configuration Profile Compiler, page 2-6

•Proprietary Plain-Text Configuration File, page 2-8

•Using Provisioning Parameters, page 2-15

•Data Types, page 2-20

SPA Configuration File

The SPA configuration profile defines the parameter values for a specific SPA device. The profile lets you determine the value for each parameter used by the SPA and also to determine the user access to each parameter: hidden, read-only, or read-write. Any parameters not specified by a profile are left at the factory default values.

The SPA accepts a configuration profile in two formats:

•Open (XML-style) format

•Proprietary, plain-text format

The XML-style format lets you use standard tools to compile the parameters and values. To protect confidential information contained in the configuration profile, this file is generally delivered from the provisioning server to the SPA over a secure channel, provided by HTTPS. A complete example XML profile can be generated using the Linksys profile compiler tool (see the “SPA Configuration Profile Compiler” section on page 2-6), using the following command:

spc --sample-xml sample.txt

The plain-text configuration file uses a proprietary format, which can be encrypted to prevent unauthorized use of confidential information. By convention, the profile is named with the extension

.cfg (for example, spa2102.cfg). The Linksys Profile Compiler (SPC) tool is used to compile the plain-text file containing parameter-value pairs into an encrypted CFG file. The SPC tool is available from Linksys for the Win32 environment (spc.exe) and Linux-i386-elf environment (spc-linux-i386-static). Availability of the SPC tool for the OpenBSD environment is available on a case-by-case basis.

Linksys SPA Provisioning Guide

	Version 3.0	2-1

Chapter 2 Creating Provisioning Scripts

Open Format Configuration File

A configuration file in open, XML-style format can be sent from the provisioning server to the SPA during a resync operation without compiling them into a binary object.

The SPA can accept configuration formats generated by standard tools. This eases development of back-end provisioning server software to generate SPA configuration profiles from existing databases.

The SPA configuration profile open format consists of a text file (with XML-like syntax), optionally compressed using the gzip deflate algorithm (RFC1951), and further optionally encrypted using 256-bit AES symmetric key encryption.

The XML profile syntax consists of an XML-style hierarchy of elements, with element attributes and values. Opening element tags need to be properly matched by corresponding closing element tags. Empty element tags are allowed. Element tags are case sensitive. Comments are allowed, using standard XML syntax. Leading and trailing white space is removed from the parameter value. New lines within a value are converted to spaces.

The SPA recognizes elements with proper SPA parameter names, when encapsulated in the special <flat-profile> element. In addition, the SPA also recognizes arbitrary, configurable aliases for a limited number of parameter names. The <flat-profile> element itself can in turn be encapsulated within other arbitrary elements.

Unrecognized element names are ignored by the SPA. Any parameters not specified by a profile are left unchanged in the SPA. If the XML file contains multiple occurrences of the same parameter tag, the last such occurrence overrides any earlier ones. To avoid inadvertently overriding configuration values for a parameter, it is recommended that at most one instance of a parameter be specified in any one profile.

Element attributes are allowed. Their value must be enclosed by double quotes. All such attributes are ignored by the SPA, except for the user-access attribute: ua.

The user-access attribute defines access to the administration web server for a specific parameter by the User account. Access by the Admin account is unaffected by this attribute.

The ua attribute, if present, must have one of the following values:

•na—no access

•ro—read-only

•rw—read/write

If the user-access attribute (ua) is not specified in an element tag, the factory default user access is applied for the corresponding parameter.

An XML header of the form <? . . . ?> is allowed, but is ignored by the SPA.

As an example, the following profile would be accepted by the SPA. It supplies the values of three provisioning parameters.

Basic XML Profile FormatBasic XML Profile Format

Example 2-1 Basic XML Profile Format

<flat-profile> <Resync_On_Reset> Yes

</Resync_On_Reset> <Resync_Periodic> 7200 </Resync_Periodic>

<Profile_Rule> tftp://prov.telco.com:6900/Linksys/config/spa2102.cfg

Linksys SPA Provisioning Guide

2-2	Version 3.0

Chapter 2 Creating Provisioning Scripts

Open Format Configuration File

</Profile_Rule> </flat-profile>

The profiles in Example 2-1 and Example 2-2 are functionally equivalent. Example 2-2 contains additional information and comments, which are ignored by the SPA. Also, in Example 2-2 the <flat-profile> element is encapsulating within the <top-level> element. Such extra encapsulation is allowed, and the parameters within it are still recognized.

Example 2-2 XML Profile with Comments

<?xml version=’1.0’?> <top-level>

<generator> Telco Profile Compiler v.1.2

</generator>

<flat-profile device=”Linksys”>

<Resync_On_Reset> Yes

</Resync_On_Reset> <Resync_Periodic> 7200 </Resync_Periodic>

<Profile_Rule> tftp://prov.telco.com:6900/Linksys/config/spa2102.cfg

</Profile_Rule> </flat-profile> </top-level>

The SPA recognizes and translates basic XML character escapes, including escapes for those shown in Table 2-1.

Table 2-1

Special Character	XML Escape Sequence

& (ampersand)	&

< (less than)	<

> (greater than)	>

’ (apostrophe)	'

” (double quote)	"

Numeric character escapes, using decimal and hexadecimal values (s.a. ( and .), are also translated.

Note The SPA firmware does not support the full Unicode character set, but only the ASCII subset.

The profile in Example 2-3illustrates character escapes. This example defines an information hotline dial plan, which sets the Dial_Plan[1] parameter equal to ( S0 <:18005551212> ).

Example 2-3 Dial Plan Example

<flat-profile> <Dial_Plan_1_>

( S0 <:18005551212> ) </Dial_Plan_1_>

Linksys SPA Provisioning Guide

	Version 3.0	2-3

+ 65 hidden pages