LINKSYS SPA Provisioning Guide

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.Speci fications are subject to change without notice. Linksys is a registered trademark or trademar k 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, In c. and, i n some i ns tances, 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.

Preface vii

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

CHAPTER

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

Version 3.0

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

iii

Contents

Enabling HTTPS 1-13 Syslog Server 1-15

Where to Go From Here 1-15

CHAPTER

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

CHAPTER

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

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

Version 3.0

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

Contents

CHAPTER

APPENDIX

NDEX

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 Acronyms

B Glossary

C Example SPA Configuration Profile

Version 3.0

Linksys SPA Provisioning Guide

Contents

Linksys SPA Provisioning Guide

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 informa tion prov ided in th is docume nt.

• 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

Version 3.0

• 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

vii

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

Preface

This document is divided into the following chapters and appendices.

Chapter Contents

Chapter 1, “Provisioning Linksys VoIP Devices”

Chapter 2, “Creating Provisioning Scripts”

Chapter 3, “Provisioning Tutorial”

Chapter 4, “Provisioning Field Reference”

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

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

This chapter introduces Linksys VoIP products.

This chapter describes how to work with Linksys provisioning scripts and configuration profiles.

This chapter provides step-by-step procedures for using the scripting language to create a configuration profile.

This chapter provides a systematic reference for each parameter on the Provisioning tab of the administration web server.

document.

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

Field Reference”

Chapter 4, “Provisioning

viii

Linksys SPA Provisioning Guide

Version 3.0

Preface

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 authoriz ed partner PIN)

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

• E-mail support

voipsupport@linksys.com

Version 3.0

Linksys SPA Provisioning Guide

Technical Support

Preface

Linksys SPA Provisioning Guide

Version 3.0

CHAPTER

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 P AP2T, are primarily intended for high-volume deployments by V oIP 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 br oadband 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. A TA 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

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 co nfiguration 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.

Chapter 1 Provisioning Linksys VoIP Devices

Communication Encryption

The configuration parameters communicated to the endpoint may contain authorization codes or other information should not be revealed to t he 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 cu stomers.

For this reason, the service provider may wish to encrypt the configuration profile communication between the provisioning server and the en dpoint, 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 guideline s for each paramete r 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.

1-2

Linksys SPA Provisioning Guide

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

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 SP A can be configur ed to periodically contact a norm al provisioning server (NPS). Communicati on 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

Provisioning Overview

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 quant ity , and either preprovisions th e 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 en d customers. It also discourages t he 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 disp lays No t Customize d.

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.

Version 3.0

Linksys SPA Provisioning Guide

1-3

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 configur ed 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 quali fied domain name (FQ DN). The use of a FQDN facilitates the deployment of redun dant provisioning ser vers. 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.

Chapter 1 Provisioning Linksys VoIP Devices

Retail Provisioning

The SPA firmware includes an administration web server that displays SPA internal configuration and accepts new configuration parameter values. The ser ver 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 SP A that is performing the resync requ est with the new account , based on the URL and the supplied PIN. Through this initial resync operation, th e 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.

1-4

Linksys SPA Provisioning Guide

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Automatic In-House Preprovisioning

Using the administration web server and issuing a resync URL is conven ient fo r 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

Provisioning Overview

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 SP A configur ation profile defines the parameter valu es 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.

Version 3.0

Linksys SPA Provisioning Guide

1-5

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 applicati on. The SPA provisioning flow is illustrated in

Figure 1-1 SPA Provisioning Flow

Chapter 1 Provisioning Linksys VoIP Devices

Figure 1-1.

1-6

Linksys SPA Provisioning Guide

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

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

SP-CUST Service provider customization

SPA Provisioning Flow

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.

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 S PA 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 uni t:

Profile_Rule tftp.callme.com/profile/$MA/spa2102.cfg;

Version 3.0

Linksys SPA Provisioning Guide

1-7

Using HTTPS

Chapter 1 Provisioning Linksys VoIP Devices

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 direct ory location can be changed periodically for extra security.

Using HTTPS

The SP A pro vides a reliable and secure provisio ning strategy based on HTTP S requests from the SPA to the provisioning server , using both server and client certificat es for authenticating the cli ent 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

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 an d 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.

“Enabling HTTPS” section on page 1-13.

1-8

HTTPS also provides for the authentication of th e 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

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

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 certific ate 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.

Using HTTPS

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 . T o prevent this kind of attack, each SPA also carries a unique client certificate, also signed by Linksys, including identifyi ng informa tion about eac h indiv idual endpoi nt. 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. 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 SP A endpo ints to authenticate authori zed provisioning servers.

Figure 1-2 illustrates the relationship and placement of

Version 3.0

Linksys SPA Provisioning Guide

1-9

Using HTTPS

Chapter 1 Provisioning Linksys VoIP Devices

Figure 1-2 SPA Configuration and Provisioning Certificate Chai n

SPA Configuration-Prov isioning Certificate Chain

Sipura Technology, Inc

Provisioni ng Server Root Authority 1

PKEYCERT

Compiled into SPA Firmware

Signs Provisioning Server Certificates

SPA Prov i s ioning S erver

Root CA

Certificate List

SPA Firmware Load

SPA

CERTPKEY

Signs SPA

Client Certificates

Authenticates Server

in HTTPS Connection

Authenticates Client

in HTTPS Connection

CERT PKEY

VoIP Service Provider

Provisioni ng Server Entity

HTTPS Server Configuration Files

Root CA

Certificate List

Stored on Service Provider’s

Provisioni ng Server

1-10

As indicated in the lower half of the dia gram, 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

PKEY CERT

Sipura Technology, Inc

Client Certificate Root Authority 1

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, pa ge 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.

Provisioning Setup

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)

Version 3.0

T o trou blesh oot server configur at ion, it is helpful to inst al l a separ ate client for each typ e of server on a different host.

Linksys SPA Provisioning Guide

1-11

Provisioning Setup

TFTP

HTTP

Chapter 1 Provisioning Linksys VoIP Devices

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 SP A 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 profil e f ilepath on that TFTP serv er. 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.

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.

1-12

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. T ypically , this means that a config uration file is pre-generated for each deployed SP A, 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 th e GET method). In thi s 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

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

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. T o 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

Provisioning Setup

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 HT TPS session carries identifying information embedded in its subject field. This i nfo rmation 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 follo wing information in the SPA identifying fields:

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

Version 3.0

Linksys SPA Provisioning Guide

1-13

Provisioning Setup

Chapter 1 Provisioning Linksys VoIP Devices

T o determine if a SPA carries an individualized certificate use the $CCER T 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

1-14

Linksys SPA Provisioning Guide

Version 3.0

Chapter 1 Provisioning Linksys VoIP Devices

Syslog Server

If a syslog server is configured on the SP A (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 and configuration profiles.

Review step-by-step procedures for using the scripting language to create a configuration profile.

Refer to the function and usage of each parameter on the Provisioning tab of the administration web server.

Look up the expansion for an acronyms use in this document.

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

Chapter 2, “Creating Provisioning Scripts”

Chapter 3, “Provisioning Tutorial”

Chapter 4, “Provisioning Field Reference”

Appendix A, “Acronyms”

Version 3.0

Linksys SPA Provisioning Guide

1-15

Where to Go From Here

Chapter 1 Provisioning Linksys VoIP Devices

1-16

Linksys SPA Provisioning Guide

Version 3.0

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, pa ge 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.

CHAPTER

Version 3.0

The SPA accepts a configurat ion 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

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

“SPA Configuration Profile

2-1

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 ca n accept co nfiguration fo rmats genera ted by standard t ools. This e ases developm ent 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 ne ed to be properly m atched by correspond ing clos ing elem ent 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 addit ion, 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.

Chapter 2 Creating Provisioning Scripts

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

2-2

Linksys SPA Provisioning Guide

Version 3.0

Chapter 2 Creating Provisioning Scripts

</Profile_Rule> </flat-profile>

The profiles in Example 2-1 and Example 2-2 are functionally eq uivalent . 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>

Open Format Configuration File

The SPA recognizes and translates basic XML character escapes, incl uding 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

Version 3.0

<flat-profile> <Dial_Plan_1_> ( S0 <:18005551212> ) </Dial_Plan_1_>

Linksys SPA Provisioning Guide

2-3

+ 65 hidden pages

LINKSYS SPA Provisioning Guide

Specifications and Main Features

Frequently Asked Questions

User Manual