Content Content Introduction

Transcription

1

2 Content Content Introdction Roles in the provisioning process Server in the provisioning process Gigaset server Provisioning server Provisioning methods Provisioning data Provisioning tool Provisioning methods Manal Gigaset VoIP phone set-p standard procedre Methods for providing the provisioning server URL Setting p redirection information sing the web ser interface Setting p redirection information sing the XML-RPC interface Providing the provisioning server URL via the SIP mlticast mechanism DHCP option (dhcp_rl) File pload via HTTP server MAC based provisioning Message flow HTTP reqest Ato-provisioning via activation code Message flow HTTP reqest Sbscription list spporting mltiple acconts Updating the configration data Ato-provisioning with plain XML content Secrity aspects Certificates in PEM format Download TLS certificates via a link in a profile XML provisioning file Configration file editor (provisioning tool) Starting Creating a configration file XML files XSD schema files Configration parameters XML template example Special parameters Setting p yor own provisioning server Provisioning package editor (provisioning tool) Starting Creating a provisioning package Installing the ato-provisioning application Preparing the file system Reqired libraries Installing the gigaset_profile_gen application Setting the access rights for the ato-provisioning files and script Ato-provisioning example script Testing the installation The gigaset_profile_gen application File system strctre Index

3 Introdction Introdction Gigaset VoIP phones are delivered to the end-ser reqiring minimal ser interaction for set-p and keeping p-to-date. The end-ser experiences the same plg & play behavior as for analoge phones. Unlike classic phones sing a PSTN connection, VoIP phones reqire a variety of configration parameters which have to be loaded atomatically when the device is connected to the Internet. Provisioning Provisioning is the process for ploading the necessary configration and accont data to the phone. This is done by means of profiles. A profile is a configration file that contains Gigaset VoIP phonespecific settings, VoIP provider data as well as ser-specific content. It has to be available on an HTTP provisioning server which is accessible for the phone in the pblic (Internet) or local network. A profile is loaded to the phone via its Ethernet interface. Ato-provisioning Ato-provisioning is defined as the mode of operation by which the Gigaset VoIP phone connects atomatically to a server and downloads both provider-specific parameters (sch as the URL of the SIP server) and ser-specific parameters (sch as the ser name and password) and stores them in its non-volatile memory. Ato-provisioning is not necessarily limited to the parameters reqired for doing VoIP telephony. Ato-provisioning can also be sed to configre other parameters, e.g. the settings, if the Gigaset VoIP phones spport these featres. However, for technical reasons ato-provisioning is not possible for all configration parameters of the phone. XML-provisioning Gigaset offers XML-provisioning to the cstomer, i.e. Gigaset VoIP phones can be spplied with the necessary configration data via XML content. Existing XML-tooling can be sed. There are two procedres to provide Gigaset VoIP phones with configration data: An XML file containing the configration data is directly ploaded onto the phone. The XML file is sed by a profile generation tool to generate a binary file that is spported by the phones. The following Gigaset VoIP phones are spported for ato-provisioning: XML-provisioning with binary Plain XML-provisioning Gigaset DE900 IP PRO Yes 8/2012 Gigaset DE700 IP PRO Yes 8/2012 Gigaset DE410 IP PRO Yes 8/2012 Gigaset DE310 IP PRO Yes 8/2012 Gigaset DX800A all in one Yes No Gigaset C610 IP/N300 IP Yes 8/2012 Gigaset N510 IP PRO Yes 8/2012 Gigaset N720 DECT IP Mlticell System Yes Q3/Q

4 Introdction Roles in the provisioning process Gigaset Provisioner Provider Update server Redirection server Provisioning server SIP server End-ser Network / Internet Roles in the provisioning process Gigaset Commnications GmbH the manfactrer Gigaset is the manfactrer of the VoIP phones which are the sbject of this docment. For Gigaset VoIP phones the MAC address inclding a check sm is sed for identification. Gigaset ensres that this MAC ID is printed on all phone boxes. This is necessary for assigning a specific phone to a specific provider in order to provide the phone with SIP accont data. Each device is preconfigred with the same parameters. By defalt, all Gigaset VoIP phones contact the Gigaset pdate server when they are connected to the Internet for the first time to get frther information, e.g. the URL of the responsible provisioning server. Gigaset provides a web or XML-RPC interface which can be sed by provisioners to deploy redirection data on the Gigaset redirection server ( page 11). Gigaset provides a provisioning tool which can be sed by provisioners to facilitate the provisioning process. It provides an editor to create device-specific valid configration files easily as well as an editor to create provisioning packages which can be ploaded to the phones. The provider The provider hosts the SIP servers reqired to offer a complete VoIP telephony service to the endser. Occasionally, the provider simltaneosly assmes the role of provisioner and can host their own provisioning server. The provisioner The provisioner has direct contact with the end-ser and actally manages the VoIP configration parameters for each individal end-ser VoIP phone. The provisioner has to provide the content and perhaps even operate the server that will be accessed by the phone in order to download the end-ser s configration parameters. When sing the Gigaset redirection service the provisioner can operate their own provisioning server. If not, the provisioner is responsible for creating redirection data on the Gigaset server. The MAC ID printed on the device s box can be read by a barcode scanner by the provisioner who has to deploy this information on the Gigaset redirection database sing the web interface. The provisioner is also responsible for storing the cstom-bilt data on the provisioning server. If a VoIP phone reqests this server, an end-ser specific profile is generated and sent to the device. Last bt not least, the provisioner has to keep the cstom-bilt data p-to-date. 4

5 Introdction The end-ser The end-ser has to connect the VoIP phone to the Internet only. All related information will be downloaded atomatically and there is no need for the end-ser to configre parameters manally. Server in the provisioning process The following servers are part of the provisioning process: Gigaset server Update server The pdate server is responsible for providing the Gigaset VoIP phones with provider profiles (ser-independent data), firmware pdates, langage files for the Web ser interface (optional), help texts (langage-specific) for the Web ser interface (optional). Gigaset VoIP phones establish a connection to the Gigaset server when connected to the Internet for the first time and then periodically in order to check if there is an pdated configration file for the Gigaset VoIP phone-specific settings. By defalt the Gigaset server profile.gigaset.net/device is sed as pdate server. Redirection server When the VoIP phone contacts the Gigaset server, in order to get all the necessary configration data, the redirection server spplies the URL of the provisioning server which is responsible for providing the VoIP phone with the provider data (SIP accont). To enable ato-provisioning (i.e. the end-ser does not need to select the provider manally) the provisioner mst add the redirection information for the VoIP phones to the redirection database. The URL of the Gigaset redirection server is prov.gigaset.net. Provisioning server The provisioning server stores cstom-bilt data for providing the VoIP phones with the VoIP specific data (e.g. SIP accont). For many reasons it is possible to se a cstomised provisioning sever, e.g.: The phone has no possibility to reach the Gigaset server via the web (e.g. closed network withot HTTP proxy). The phone is sed behind a VoIP PBX and the provisioning has to be independent from the LAN/ WAN infrastrctre. The provider wants to handle profiles and firmware himself. The provider wants to se an ato-provisioning procedre to spport the VoIP phones. The Gigaset ato-provisioning methods are scalable over a wide area. This means for example that it is possible to set p a system completely independent from the Gigaset server or to se the Gigaset server for redirecting to a provider-specific provisioning server. 5

6 Introdction Setting p a cstomised provisioning server The following is reqired to set p yor own provisioning server: HTTP server (e.g. Apache) The provisioner has to provide a system with an operative HTTP server, where the specific Gigaset software package can be installed. In the case of binary XML provisioning this mst be a Linx system. Provisioning package provided by Gigaset Gigaset provides the cstomer with a provisioning software package. The package incldes all the necessary files, scripts, tools and the manal for setting p a provisioning server. The provisioner only has to create a connection between the provisioning script and its database containing the ser-specific accont data. For detailed information please refer to the chapter Setting p yor own provisioning server ( page 45). Database (e.g. MySQL) The se of a database is optional bt it is the sal way for providing cstom-bilt data. Frthermore, the se of a database administration tool (e.g. phpmyadmin) is helpfl to manage the database content. Provisioning methods For implementing ato-provisioning of the VoIP phones it mst first be ensred that the device receives the address (URL) of the server responsible for provisioning ( page 5). As the provisioning server location cannot be anticipated in the case of a private PBX it may be located within the phone s local network, in the case of a hosted PBX it may be located somewhere in the Internet the phones se a Gigaset server (profile.gigaset.net/device) by defalt which mst be changed according to the provisioner s reqirements. The following methods are provided for the provisioning server URL pdate, depending on the prevailing network infrastrctre (see figre Provisioning process page 7): Gigaset redirection service ( page 11) The provisioner can se either the Gigaset provider/provisioner portal to enter the provisioning server URL for the phones to be managed or se the XML-RPC interface. SIP mlticast mechanism ( page 23) The phone reqests the provisioning server address from a local network instance via SIP mlticast. This method is predominantly sed by local PBX systems. DHCP option 114 ( page 24) The phone reqests the provisioning server address via a DHCP reqest with option 114 (dhcp_rl). This method is predominantly sed by stand-alone provisioning servers within the same LAN. Manally sing the device s Web UI The following methods are provided for ato-provisioning: MAC-based ato-provisioning ( page 25) The VoIP phone reqests the provisioning data from the provisioning server based on its MAC address. No ser inpt is necessary. This method is sed for VoIP phones connected to (hosted) PBX systems. Ato-provisioning based on an activation code ( page 28) The VoIP phone reqests the provisioning data from the provisioning server based on an activation code manally entered by the ser. This method is sed for devices distribted via retail sales. 6

7 Introdction Profile download can only be started from the VoIP phone, i.e. that the phone mst be triggered to perform an pdate when new configration data is provided. This can be carried ot as follows: VoIP phone restart Manally by the ser via the device s Web UI Reglar version checks initiated daily by the phone SIP check-sync mechanism ( page 33) Connect redirection server SIP mlticast DHCP option Enter redirection data Redirection server Spply provisioning URL 4 )))) Provisioning server MAC address or activation code SIP accont and configration data 5 6 DECT Provisioning process 1 The phone sends a DHCP reqest inclding the DHCP option 114. If an URL is known by the DHCP server, it will be retrned within the DHCP response. Otherwise: 2 The phone sends a SIP mlticast to the local network with a SUBSCRIBE reqest. If a SIP server spporting SIP mlticast is available and the device can be identified, the URL of the provisioning server is spplied. Otherwise: 3 The phone connects to the Gigaset server profile.gigaset.net/device. If redirection information is available for the device (identified by the MAC ID) the URL of the provisioning server is spplied. 4 The URL of the provisioning server is spplied. 5 The phone connects to the provisioning server and reqests the SIP accont and configration data. 6 The provisioning server provides the phone with the reqired data. 7

8 Introdction The following methods are spported by the specific devices: MAC-based atoprovisioning Ato-provisioning with activation code SIP mlticast and check-sync Gigaset DE900 IP PRO Yes Yes Yes Gigaset DE700 IP PRO Yes Yes Yes Gigaset DE410 IP PRO Yes Yes Yes Gigaset DE310 IP PRO Yes Yes Yes Gigaset DX800A all in one Yes Yes Planned 2012 Yes Gigaset C610 IP/N300 IP Yes Yes Yes Yes Gigaset N510 IP PRO Yes Yes Yes Yes Gigaset N720 DECT IP Mlticell System Yes Yes Yes Yes DHCP option 114 Provisioning data The following are provisioning data: Parameters Gigaset VoIP phones have many configration parameters bt only a small sbset is reqired for provisioning. General device data This data is spplied statically via a template and comprises general settings for the SIP accont, e.g. proxy, registration and STUN server address, port nmbers, etc. NTP settings, e.g. a time server address settings for Info services User-specific data It can be extracted from the provisioning database ( page 45) and comprises, for example SIP sername and password LAN settings voice mail settings, e.g mail accont data settings for network directories, e.g. online phone books WebUI texts (optional) For Gigaset DECT IP phones (e.g. Gigaset N510 IP PRO) only the English langage is implemented by defalt in the firmware. All other langages have to be downloaded from the provisioning server when selected by the ser. Firmware pdate files (optional) The provisioner can decide to also host the firmware files on the provisioning server. Gigaset delivers a package with all the crrent firmware files for the VoIP phones. 8

9 Introdction Provisioning tool The provisioning tool is a web interface designed to assist the provisioner when creating a configration file or a provisioning package for Gigaset IP phones. The provisioning tool provides the following components: A link to the Gigaset web interface for entering redirection information, A configration file editor to create a valid XML file, A provisioning package editor to create packages that can be ploaded to the phones. To access the web ser interface yo need a ser accont (ser name and password) which mst be provided by Gigaset Commnications GmbH. Accont reqests can be sent to sys_engineering_ip_pro.gc@gigaset.com. To open the Gigaset provisioning tool: Open the web ser interface: Log in sing the ser name and password provided by Gigaset. Click on the component yo want to se: Redirection portal ( page 11) Configration file editor ( page 38) Provisioing package editor ( page 45) 9

10 Provisioning methods Provisioning methods When the phone is connected to the network for the first time, it needs to connect to a server in the local or pblic network in order to download the necessary data to be able to make VoIP calls. By defalt, this is a Gigaset server bt it cold also be a cstomer provisioning server, e.g. on a PBX. Below, the standard manal procedre is described in short. The following methods are available for atomatic provisioning (see also introdction on page 6): For providing the provisioning server URL Gigaset redirection service ( page 11) SIP mlticast mechanism ( page 23) DHCP option 114 ( page 24) For ato-provisioning Mac-based ato-provisioning ( page 25) Ato-provisioning based on an activation code ( page 28) For profile pdate SIP check-sync mechanism ( page 33) Manal Gigaset VoIP phone set-p standard procedre A Gigaset VoIP phone can be set p manally via the phone s ser interface in the case of a DECT VoIP phone via the handset. The se of a PC is not reqired bt possible sing a Web ser interface which is available for all Gigaset VoIP phones. The defalt manal registration procedre for a Gigaset VoIP phone is as follows: )))) Standard manal registration procedre The end-ser connects the phone to the network 1. Internet access is reqired. The connection assistant is started 2. If available the activation code spplied by the provider is entered 3 ( page 28). 10

11 Provisioning methods If the phone establishes a connection to the Gigaset server to download a provider profile, this download is carried ot in two steps: All contries for which a provider profile is available are listed for the ser to select the location 4. All providers of the selected contry for which a profile is available are displayed for the ser to select the provider 5. The profile is loaded from the Gigaset server onto the VoIP phone. In this case Gigaset acts as a provisioner for general (ser-independent) SIP settings. The ser enters the athentication name 6 and the password 7 according to the rles given by the provider profile. Methods for providing the provisioning server URL The following methods are available to provide the VoIP phones with redirection information: Web ser interface for registering/deregistering and list devices XML-RPC interface ( page 14) SIP mlticast ( page 23) DHCP option 114 ( page 24) Setting p redirection information sing the web ser interface To add the redirection data to the redirection database, Gigaset provides a web ser interface for provisioners. i There is also an XML-RPC interface available to provide redirection data. The XML-RPC calls are described in detail page 14. Open the web ser interface as described on page 9. Open the Redirection portal. Yo are allowed to add new redirection data or delete existing data. The following fnctions are available: Registration, control and deregistration of single devices Display of a device list Upload of prepared XML files 11

12 Provisioning methods Registering devices To register a Gigaset VoIP phone, enter the MAC ID of the device, the URL of the provisioning server and the Provider for the device configration. URL and Provider can be entered manally or selected from a list of known provisioner URLs and providers. Click on the Register btton to save the entry. The corresponding parameters are checked and if approved saved in the Gigaset redirection database. The provisioner is informed accordingly. List devices The List Devices/Deregister tab can be sed to search for redirection data sets of all devices or all devices of a specific provider. Open the List Devices/Deregister tab. Click on the List btton to list the redirection data sets of all devices. or Enter the name of a provider or select it from the list and click on the List btton. 12

13 Provisioning methods For all devices that have ever been ploaded by the provisioner (possibly dependent on the provider name) the list shows the date of the last reqest, the MAC address, the name of the provider, the provisioning URL and the registration date. Sorting and filtering the list Sorting: Click on a colmn title to sort the list in ascending or descending order. Indicates the colmn sed for sorting and whether the list is sorted in ascending or descending order. Filtering: In the Search field enter a search string (characters, digits, special characters). The otpt is filtered accordingly. Downloading device entries as file in CSV format Mark the check boxes to the left of the device entries yo want to download and click on Download. Deregister devices To deregister the redirection data record for one or more devices: Open the List Devices/Deregister tab. Mark the check boxes to the left of the device entries yo want to deregister and click on Deregister. i If the Provisioning URL is not changed, e.g. by resetting it to the defalt vale, the device can no longer be pdated. 13

14 Provisioning methods Uploading an XML File It is also possible to pload an XML file containing many redirection data bndles. This option is most sefl for provisioners whose end-ser profiles are generated atomatically by any script and who want to keep sing the web ser interface instead of direct interfaces for clients. However, more than jst ploading redirection data can be carried ot. Depending on the strctre of the XML file, any fnction provided by the interfaces may be possible. For detailed information on the XML parameter vales please refer to the section Setting p redirection information sing the XML-RPC interface ( page 14). To download examples for valid XML files click on Examples. To pload yor own XML file: Open the Upload tab, browse yor file system for the appropriate XML file and click on the Upload btton. Setting p redirection information sing the XML-RPC interface The most comfortable Gigaset server interface is the XML-RPC interface. XML-RPC is sbject to a procedre call protocol, which means that fnctions can be accessed at different places. XML-RPC reqests are encoded in XML syntax and dispatched via HTTP. The Gigaset XML-RPC web interface is based on Apache XML-RPC libraries and can be accessed by any XML-RPC client. The client can call different remote procedre methods. The parameter vales and the fnction names are converted into XML syntax simltaneosly and transferred to the XML- RPC server via HTTP. The XML file is parsed throgh the Apache XML-RPC libraries and again, the sitable remote method with its corresponding parameter vales is called. The response of this remote method is again converted into XML syntax, sent back to the client and processed by the XML-RPC client libraries. The XML-RPC service can be accessed sing the following address: An XML-RPC call for an XML-RPC client cold be as follows: Object[] params = new Object[]{"#MAC-ID#","#PROVISIONING_URL#", "#PROVIDERNAME#"}; List<Object> list1 = Arrays.asList((Object[])client.execte ("atoprov.registerdevice", params)); On the Gigaset XML-RPC web interface the implementation appears as follows: pblic List<Object> registerdevice(string macid, String rl, String name) {... se parameter vales and create response list... retrn mylist; } 14

15 Provisioning methods The XML files are invisible on both sides, when effecting the remote procedre call on the client as well as on the server becase the XML files are parsed via the XML-RPC libraries. Nevertheless, the plain text (method + parameter) has to be transferred via HTTP in a well- strctred manner which makes XML a perfect alternative. XML syntax Whenever an XML-RPC client reqests a remote method on the Gigaset XML-RPC server, an XML file is created consisting of the method s name and the parameters. Both the file and the response are transferred via HTTP. The pload of XML files via FileUpload has to look exactly like this as well. The ploaded XML file, depending on the method for registering a redirection data set, can for example appear as follows: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.registerdevice</methodname> <params> <param> <vale>ffffffffffff-1234</vale> </param> <param> <vale> </param> <param> <vale>myprovider</vale> </param> </params> </methodcall> After a sccessfl reqest, the corresponding XML response file looks as follows : <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>0</boolean></vale> <vale>mac_already_in_se:ffffffffffff</vale> </data></array></vale> </param> </params> </methodresponse> 15

16 Provisioning methods XML-RPC Commands If an XML-RPC client calls a remote procedre fnction on the Gigaset XML-RPC server, an XML file consisting of the XML-RPC method and the corresponding parameter vales is created and is transferred via HTTP. The response is transferred the same way. The respective XML-RPC methods as well as the relevant parameter vales, retrn vales and XML formats are illstrated below: atoprov.registerdevice Registering a device at the provisioning server: Call: atoprov.registerdevice(string macid, String rl, String name) macid MAC ID of the device rl URL of the provisioning server name Provider name Retrn: Retrn vale (1) (Boolean) = tre, 0 = false Retrn vale (2) (String) if tre: OK:password if false: mac_already_in_se: mac_invalid: rl_invalid: name_invalid: Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.registerdevice</methodname> <params> <param> <vale>ffffffffffff-1234</vale> </param> <param> <vale> </param> <param> <vale>myprovider</vale> </param> </params> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>0</boolean></vale> <vale>mac_already_in_se:ffffffffffff</vale> </data></array></vale> </param> </params> </methodresponse> 16

17 Provisioning methods atoprov.deregisterdevice Deregistering a device from the provisioning server. Call: atoprov.deregisterdevice(string mac) mac MAC ID or MAC address of the device Retrn: Retrn vale (1) (Boolean) = tre, 0 = false Retrn vale (2) (String) if tre: OK if false: mac_not_fond: mac_invalid: Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.deregisterdevice</methodname> <params> <param> <vale>ffffffffffff</vale> </param> </params> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>1</boolean></vale> <vale>ok</vale> </data></array></vale> </param> </params> </methodresponse> 17

18 Provisioning methods atoprov.listdevices - list devices for all providers Spply MAC address, provider name, provisioning server URL and registration date for all registered devices: Call: atoprov.listdevices() Retrn: Retrn vale (0-n) (Object[]) [MAC,NAME,URL,DATE] Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.listdevices</methodname> <params /> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><array><data> <vale>bbbbbbbbbbbb</vale> <vale>myprovider1</vale> <vale> <vale> </vale> </data></array></vale> <vale><array><data> <vale>eeeeeeeeeeee</vale> <vale>myprovider2</vale> <vale> <vale> </vale> </data></array></vale> </data></array></vale> </param> </params> </methodresponse> 18

19 Provisioning methods atoprov.listdevices - list devices of a specific provider Spply MAC address, provider name, provisioning server URL and registration date for all registered devices of a given provider: Call: Retrn: atoprov.listdevices(string name) name Provider name Retrn vale (0-n) (Object[]) [MAC,NAME,URL,DATE] Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.listdevices</methodname> <params /> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><array><data> <vale>bbbbbbbbbbbb</vale> <vale>myprovider1</vale> <vale> <vale> </vale> </data></array></vale> </data></array></vale> </param> </params> </methodresponse> 19

20 Provisioning methods atoprov.checkdevice Spply provider name, provisioning server URL and registration date for a specific device: Call: atoprov.checkdevice(string mac) mac MAC ID or MAC address of the device Retrn: Retrn vale (1) (Boolean) = tre, 0 = false Retrn vale (2) (String) if tre: [MAC] if false: max_not_fond: mac_invalid: Retrn vale (3) (String) if tre: [NAME] Retrn vale (4) (String) if tre: [URL] Retrn vale (5) (String) if tre: [DATE] Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.checkdevice</methodname> <params> <param> <vale>bbbbbbbbbbbb</vale> </param> </params> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>1</boolean></vale> <vale>bbbbbbbbbbbb</vale> <vale>myprovider1</vale> <vale> <vale> </vale> </data></array></vale> </param> </params> </methodresponse> 20

21 Provisioning methods atoprov.registerdevicelist Spply provider name, provisioning server URL and registration date for a list of registered devices: Call: atoprov.registerdevicelist(list<string> maclist, String rl, String name) maclist List of MAC IDs rl URL of the provisioning server name Provider name Retrn: Retrn vale (1) (Boolean) = tre, 0 = false Retrn vale (2-n) (String) if tre: OK: Passwort mac_already_in_se: mac_not_exist: if false: mac_invalid: rl_invalid: name_invalid: Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.registerdevicelist</methodname> <params> <param> <vale><array><data> <vale> abcd</vale> <vale> bcde</vale> <vale> cdef</vale> <vale> defa</vale> </data></array></vale> </param> <param> <vale> </param> <param> <vale>myprovider</vale> </param> </params> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>1</boolean></vale> <vale>ok</vale> </data></array></vale> </param> </params> </methodresponse> 21

22 Provisioning methods Another Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale>mac_already_in_se: </vale> <vale>mac_already_in_se: </vale> </data></array></vale> </param> </params> </methodresponse> atoprov.deregisterdevicelist Deregister a list of registered devices: Call: atoprov.deregisterdevicelist(list<string> maclist) maclist List of MAC IDs or MAC addresses Retrn: Retrn vale (1) (Boolean) = tre, 0 = false Retrn vale (2-n) (String) if tre: OK mac_not_fond: if false: mac_invalid: Reqest: <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>atoprov.deregisterdevicelist</methodname> <params> <param> <vale><array><data> <vale> </vale> <vale> </vale> <vale> </vale> <vale> </vale> </data></array></vale> </param> </params> </methodcall> Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale><boolean>1</boolean></vale> <vale>ok</vale> </data></array></vale> </param> </params> </methodresponse> 22

23 Provisioning methods Another Response: <?xml version="1.0" encoding="utf-8"?> <methodresponse xmlns:ex=" <params> <param> <vale><array><data> <vale>mac_not_fond: </vale> <vale>mac_not_fond: </vale> </data></array></vale> </param> </params> </methodresponse> Providing the provisioning server URL via the SIP mlticast mechanism This mechanism is an easy method for loading the URL of the provisioning server, on which the configration files (profiles) and/or the firmware files of the different Gigaset VoIP phones are located. The mechanism is designed for VoIP PBXs offering their own provisioning server for the connected VoIP phones. Before an answer is sent to the initiator of the SIP mlticast, the PBX (or SoftSwitch) has to identify the phone type. This is done via the SIP User-Agent header which starts with the prodct name. The following example flow chart shows the principle of this mechanism: Gigaset VoIP phone Roter/Network Switch PBX (Provisioning Server) SIP Mlticast to IP: Reqest e.g.: SUBSCRIBE (ser agent header e.g.: C610 IP/ ) SIP NOTIFY e.g.: :5060" The SIP mlticast mechanism is spported by most of the Gigaset VoIP phones and by the Gigaset T300 PRO and Gigaset T500 PRO PBX as well (it is also spported by some prodcts from other companies). 23

24 Provisioning methods DHCP option (dhcp_rl) As an alternative option for assigning the provisioning server URL to the VoIP phones, the DHCP option 114 (dhcp_rl) can be sed. The following example flow chart shows the principle of this mechanism: Gigaset VoIP phone Roter/Network Switch PBX (Provisioning Server) DHCP reqest containing the list with spported options (...,114) DHCP ACK,. Option:(114) URL = provisioning procedre: GET File pload via HTTP server There is also another interface which allows the pload of XML files withot sing the web ser interface. Commons FileUpload is sed ( at the server end. An HTTP client is necessary at the client end. Principally, this process is similar to the remote procedre calls described in section Setting p redirection information sing the XML-RPC interface ( page 14). The difference between the versions is that on the one hand XML-RPC clients reqest remote methods and transfer parameters in order to create an XML file, while on the other hand HTTP clients pload an XML file directly. The latter method like the XML file pload via the web ser interface is sitable for sers whose XML files are created throgh scripts bt who do not want to se the web ser interface. Please refer to paragraph XML syntax ( page 15) for frther details regarding the strctre of XML files. File pload The HTTP XML file pload can be accessed sing the following address: Content type for XML FileUpload The defalt content type sed in most cases is application/x-www-form-rlencoded Bt if a provisioner wants to pload an XML file either via the web ser interface or via an HTTP client it wold be very inefficient to se the defalt content type. For this reason, XML files are ploaded with the content type mltipart/form-data which is sitable for sending large data. Commons FileUpload corresponds exactly to this format. 24

25 MAC based provisioning Provisioning methods User-specific profiles are loaded withot any ser interaction. The database containing the ser-specific data can be hosted on a provider/pbx related server. When the phone contacts the provisioning server, it identifies itself by means of its own MAC address. Each phone has a globally niqe MAC address that was assigned to it in the factory. This method has the advantage that, ideally, the end-ser does not even have to be aware of the need for provisioning: they simply plg in the phone and the rest happens atomatically in the backgrond. For this to be sccessfl, the provisioner has to create the association between the MAC address and the end-ser prior to delivering the phone to the end-ser. This is done efficiently if the MAC ID (containing MAC address and a 4-digit part of a niqe password) is printed on the phone s box as barcode, so that the provisioner can scan the address, assign this with the provisioner's URL on the Gigaset server (optional) and enter it in its database. Becase the phone periodically qeries for configration pdates (every 24h), this method gives the provisioner the means to effectively control the end-ser s phone configration. Gigaset 1 Provisioner MAC address # User Name Password 2 Gigaset Server Redirection Server Update Server Provisioning Server 5 4 Internet 6 End-ser Cstom-bilt data MAC address 8 Ato-provisioning via MAC address Principle of operation MAC-based provisioning with redirection 1 Gigaset prints the MAC address barcode on the hosing and the box. 2 The provisioner scans the MAC address and associates it with the ser data, e.g. the SIP accont. The MAC ID consists of the MAC address pls a random ID (4 characters) that is added to the MAC address and has the following syntax: <MAC-address>-<ID>, e.g ABCD 3 The provisioner enters the redirection data on the Gigaset server. The device s MAC ID and the URL of the provisioning server have to be provided. Gigaset therefore provides a web interface as well as an XML-RPC interface. Redirection data describes a connection between the MAC address, the provisioning server s URL and the provider s name. This configration bndle is created by the provisioner and has to be stored on the Gigaset redirection database. 4 The end-ser connects the phone to the network and the phone contacts the Gigaset server. 25

26 Provisioning methods 5 The Gigaset server checks the MAC ID. If the MAC ID is available in the Gigaset provisioning database of the redirection server it transfers the provisioning server address for this device to the phone. 6 The phone connects to the provisioning server providing its MAC address. 7 The provisioning server ploads the cstom-bilt data to the phone. The provisioner is responsible for creating the cstom-bilt data to store this information on the provisioning server and to keep it p-to-date. 8 The phone is now ready to initiate the first call. 9 Periodically, the phone connects to the provisioning server in order to check if there is new cstom-bilt data available (once a day). Message flow The following diagram shows in a simplified manner the message flow between a Gigaset VoIP phone and the involved servers from the ato-provisioning point of view. Gigaset Update Server Gigaset Redirect. Server Provisioning Server http get profile.gigaset.net/device/42/2/master.bin Upload content Exchange of server index files http get profile.gigaset.net/device/42/2/../../sifs/si_123.bin Binary containing a link to the gigset.net server: https get error 401 Athorisation reqired https get Digest, sername= , algorithm=md5, nonce based on device specific password 307, temporary redirect to http get https get provider_xyz.com/gigaset/cgi/ap?mac=01:23:45:67:89:01 error 401 Athorisation reqired https get provider_xyz.com/gigaset/cgi/ap?mac=01:23:45:67:89:01, Athorisation: Digest, sername= , algorithm=md5, nonce based on device specific password AES 128 encrypted profile with accont / cstomer settings The message flow illstrates the steps 4 to 7 of the image on page

27 Provisioning methods Commnication takes place by means of HTTP reqests. Profiles are stored in a binary format on the provisioning server depending on the device variant. The Gigaset server ses the phone s variant ID to pload the matching configration. For example, profile.gigaset.net/device/42/2/master.bin refers to the configration files of a Gigaset N510 IP PRO phone ( page 59). The Gigaset redirection server ses the phone s MAC ID to search for the responsible provisioning server for this phone. HTTP reqest When the phone contacts the provisioning server in order to download the ato-provisioning file, it performs an for a URL with the following format: domain>/<directory>/<ap>?mac=<mac address> <server domain> <directory> <ap> <mac address> DNS name (or IP address) of the provisioning server. Path to the ato-provisioning script within the server domain. The script is a CGI application, i.e. it rns inside the HTTP server ( page 51). It constrcts a personalised XML configration file for the reqesting phone, then calls an application which creates the binary configration file (gigaset_profile_gen, page 58), and finally retrns the configration data to the phone. Name of the ato-provisioning script: ap (ato-provision). MAC address of the VoIP phone generating the reqest, in the 6 hex digit-pair textal representation, with or withot a colon between each digit pair; for example: 06:55:AF:3A:05:AA or 0655AF3A05AA Example of a reqest: URI format The URL where the ap script is performed is determined by an additional qery to get a so- called URI format string. The server for this qery is the same server which is sed for firmware pdates (normally not necessarily, bt recommended the Gigaset server). The qery is done with a 3-digit provisioner code. This code is preprogrammed in the factory and is sed by the phone to get the file with the format string. This format string is also sed by the phone to bild the command to get the profile from the provisioner s server. The format string contains fixed text (sed for the qery as it is) and format specifier (with a leading %) which will be replaced by the phone. The relevant configration possibilities of the URI-format string are the following: Format specifiers: %DVID Device ID, composed by bild variant and provisioning ID. Example: 42/2 %MACC MAC with colons. Example:.00:01:E3:12:34:56. %MACD MAC withot colons. Example:.0001E %% To represent the percent character. Example: The URI-format string: /%DVID/cgi/ap?mac=%MACC Leads to a reqest with the command: GET 27

28 Provisioning methods Ato-provisioning via activation code With this method the end-ser has to enter a niqe code the activation code on the phone when setting it p. For the provisioner, this method is similar to the MAC address one, bt it has the advantage that the phones does not need to be handled before sending it to end-ser. It jst has to be ensred that a niqe activation code is created by which the end-ser can be identified nambigosly. For the Gigaset VoIP phones the activation code can be a nmeric string with a maximm of 32 characters. Depending on the configration, the phone downloads the configration parameters only once ("one-shot provisioning". The end-ser ths has the freedom to modify all configration parameters and/or load other profiles. Alternatively, the phone downloads the profile periodically sing the activation code entered initially and stores the parameter when the profile is changed. The activation code The activation code is realised as a key. It consists of two parts that are concatenated as follows: Activation Code = <Gigaset part><provisioner part> Gigaset part = Identifies the provisioner for the related phone. 3 decimal nmbers. Provisioner part = <ser id>[#<password>] Max. 29 decimal nmbers. ser id Identifies the end-ser nambigosly. #password Optional password, which is preceded by the # character as separator. The parameter is sed for the HTTP digest athentication algorithm. Examples of activation codes: #0815 provider = 123, ser id = , password = provider = 015, ser id = , no password The end-ser receives the complete activation code directly from the provisioner, by or dring registration at the provisioner s web site, for example. When generating a new activation code, the provisioner mst always prepend the Gigaset part (which is defined by Gigaset Commnications when a new provisioner reqests this featre). Apart from respecting the basic syntax described above, the provisioner is free to design the provisioner part of the code as desired. 28

29 Provisioning methods Provisioner Codes # User Name Athent. name Password merge fdgrqg sgigzw hgkzi 5 Configration file (encrypted) fdgrqg Provisioning Server Provisioner or Gigaset Server 2 4 End-ser 1 3 Internet 2 Gigaset Ato-provisioning via activation code Principle of operation 1 The end-ser bys a phone, installs it and enters the activation code either via the handset procedre (installation assistant) or via the web ser interface. 2 The phone extracts the Gigaset part of the activation code and ses it to reqest the URL of the provisioning server, normally at the central (Gigaset) server, where the download profiles and firmware files are located. The provisioning (Gigaset) server sends the provisioner s URL to the phone. 3 The phone now sends the ser id part of the activation code to the provisioner s URL. 4 If the provisioner reqests athentication of the ser, the reqest is denied with 401 (Unathorised). In this case the phone mst re-isse the reqest and provide the athorisation header the content of which mst be calclated sing the password part of the activation code. The password part is of corse never transmitted directly. 5 The provisioner ses the ser id to feed a CGI application which searches its database for the given sers and then constrcts and retrns the encrypted ser profile. The received profile also contains the name of the profile which is stored in the phone. From now on, the phone will periodically check for a changed profile by sing the stored profile name ("one-shot provisioning"). This means that the profile, (normally) located at the Gigaset server, can be the same one sed for manally downloading the profile. It therefore has to be garanteed that the name of the received profile is identical with the one on the (Gigaset) server. Depending on the configration within the downloaded profile the phone can alternatively download the profile periodically sing the activation code entered initially. 29

30 Provisioning methods Message flow The following diagram shows in a simplified manner the message flow between a Gigaset VoIP phone and the involved servers from the ato-provisioning point of view. Use Case: The VoIP phone is prepared for ato-provisioning with an activation code (locked or nonlocked [One-Shot]) and the cstomer feeds in the activation code #0815 via the handset or WEB-UI. Connect to LAN Gigaset Server http get profile.gigaset.net/device/42/2/master.bin Upload content Gigaset Server and Provisioning Server can be the same Provisioning Server Profile pdate approx. every 24 h Exchange of server index files http get profile.gigaset.net/device/42/2/../../sifs/si_123.bin e.g. content: " http get provider_xyz.com/gigaset/cgi/ap?ac= error 401 athorisation reqired*) http get provider_xyz.com/gigaset/cgi/ap?ac= , Athorisation: Digest, sername: , algorithm=md5, nonce based on password "0815" *) Athorisation: optional bt recommended Profile with cstomer-specific settings (AES 128 encrypted with provider-specific encryption key) The message flow illstrates steps 3 to 7 of the image on page 29. Commnication takes place by means of HTTP reqests. Profiles are stored in a binary format on the provisioning server depending on the phone variant. The Gigaset server ses the phone s variant ID to pload the matching configration. For example, profile.gigaset.net/device/42/2/master.bin refers to the configration files of a Gigaset N510 IP PRO phone ( page 59). 30

31 HTTP reqest Provisioning methods When the phone contacts the provisioning server in order to download the ato-provisioning file, it performs an for a URL with the following format: domain>/<directory>/<ap>?ac=<activation code> <server domain> <directory> <ap> <activation code> DNS name (or IP address) of the provisioning server. Path to the ato-provisioning script within the server domain. The script is a CGI application, i.e. it rns inside the HTTP server ( page 51). It constrcts a personalised XML configration file for the reqesting phone, then calls an application which creates the binary configration file (gigaset_profile_gen, page 58), and finally retrns the configration data to the phone. Name of the ato-provisioning script: ap (ato-provision). Activation code of the VoIP phone generating the reqest. Example: URI format The URL, where the ap script is performed, is determined by an additional qery to get a so- called URI format string. The server for this qery is the same server which is sed for firmware pdates (normally not necessarily, bt recommended the Gigaset server). The qery is done with a 3-digit provisioner code. This code is preprogrammed in the factory or is part of the activation code which was entered manally and is sed by the phone to get the file with the format string. This format string will be sed again by the phone to bild the command to get the profile from the provisioner s server. The format string contains fixed text (sed for the qery as it is) and a format specifier (with a leading %) which will be replaced by the phone. The relevant configration possibilities of the URI-format string are the following: Format specifiers: %ACTC Provisioner part of the activation code. Example: %DVID Device ID, composed of bild variant and provisioning ID. Example: 42/2 %MACC MAC with colons. Example:.00:01:E3:12:34:56. %MACD MAC withot colons. Example:.0001E %% To represent the percent character. Example: The URI-format string: my.server.domain.com/gigaset/cgi/ap?ac=%actc and the activation code #0815 leads to a reqest with the command: GET 31

32 Provisioning methods Sbscription list spporting mltiple acconts For devices which allow mltiple acconts, the optional placeholder %SUBLIST is spported for se within an ato-provisioning URL to inform e.g. a PBX abot the registered handsets. At present, %SUBLIST is spported for the following devices: Gigaset C610 IP/N300 IP Gigaset N510 IP PRO Gigaset N720 DECT IP Mlticell System When this placeholder is available, it will be replaced by a byte seqence (hexadecimal withot spaces) containing the maximm nmber of spported sbscriptions (maxsb), followed by a bitarray. Maximm nmber of sbscriptions The maxsb vale represents the nmber of sbscriptions spported by the device. Gigaset N720 DECT IP Mlticell System = 100, Gigaset N510 IP PRO = 6. maxsb is defined as follows: Short form maxsb is represented by 1 Byte Bit 8 is set to 0 Bit 1-7 contains the maximm nmber of sbscriptions (bits). This means: max. 127 sbscriptions. This is sfficient for the devices crrently spported Long form maxsb is represented by 2 or 3 bytes (p to 127) Bit 8 of the 1st byte is set to "1" Bit 1-7 of the 1st byte contains the nmber of the following bytes (at present: 2) The following bytes (hex, base 256) contain the nmber of spported sbscriptions (bits). Sbscription list, bit array The meaning of the term sbscription depends on the device-specific handset. Gigaset N720 DECT IP Mlticell System Sbscription corresponds to the index of one handset/ VoIP accont pair. Gigaset C610 IP/N300 IP Gigaset N510 IP PRO The bit array contains ((maxsb div 8)+1) bytes. Each bit within the bit array corresponds to one sbscription. A bit which is set to 1 represents a sbscription which is assigned with a handset. The MSB of the 1st byte corresponds to sbscription with index 0. The LSB of the 1st byte corresponds to sbscription with index 7. The LSB of the 2nd byte corresponds to sbscription 8 (MSB = Most Significant Bit, LSB = Least Significant Bit) Sbscription corresponds to the internal nmber of a registered handset. 32

33 Provisioning methods Examples: URL= Max. 100 sbscriptions, 20 handsets are assigned to sbscriptions with index 0-19: sblist=64fffff Max. 20 sbscriptions, index 1 and the last 5 are assigned with a handset: Max. 6 sbscriptions, index 1-3 are assigned with a handset: Max. 100 acconts, each odd sbscription is assigned with a handset: sblist=64aaaaaaaaaa18 AAAAAAAAAAAAAAA0 Updating the configration data For transferring changed settings from e.g. a VoIP PBX to a VoIP phone an additional method is necessary for triggering the provisioning procedre, becase the real profile download can only be started from the VoIP phone. The Gigaset VoIP phones atomatically ask for new pdates when they are restarted. To initiate a configration pdate from the provisioner s side the SIP check-sync mechanism can be sed. SIP check-sync mechanism The check-sync mechanism is sed as a trigger within a SIP NOTIFY message to initiate a profile pdate or to check for new firmware. The following pictres show the principle of this mechanism and protocol details: Gigaset VoIP phone Roter/Network Switch PBX (Provisioning Server) SIP NOTIFY with<event: check-sync> Provisioning is started: http get profile.gigaset.net/device/42/2/master.bin ;.. 33

34 Provisioning methods The defalt for this parameter is set as follows: Gigaset DE900 IP PRO Gigaset DE700 IP PRO Gigaset DE410 IP PRO Gigaset DE310 IP PRO Gigaset DX800A all in one Gigaset C610 IP/N300 IP Gigaset N510 IP PRO Gigaset N720 DECT IP Mlticell System enabled enabled enabled enabled disabled disabled enabled enabled i De to secrity reasons the reboot option within the check-sync command is no longer spported. The REBOOT parameter can be sed instead. REBOOT parameter If an IP phone needs to be rebooted after a profile download in order to pt the changes into effect, the REBOOT parameter can be set optionally within a profile. i Information abot the parameters that reqire a system reboot after being changed can be taken from the paramter description ( page 41). XML syntax <REBOOT vale="tre"/> <!-- possible vales: tre, false, 0, 1 --> Tag Name Vale Meaning REBOOT tre A reboot is performed after the profile was downloaded. 1 false 0 No reboot after profile download. Binary representation The reboot information is encoded as a type-length-vale (TLV): Tag Name Tag Code Contents reboot 0x50 Optional tag: boolean vale coded in one byte. Ths, this TLV has a length of 3 bytes: 0 No reboot after profile download.!=0 A reboot is performed after the profile was downloaded. Binary coding example 0x50, 0x01, 0x01 // reboot, len=1, content = 1 => reboot At present, reboot is spported for the following devices: Gigaset DE900 IP PRO Gigaset DE700 IP PRO Gigaset DE410 IP PRO Gigaset DE310 IP PRO 34

35 Ato-provisioning with plain XML content Provisioning methods The benefit of ploading a file with plain XML content directly to the phone is that the provisioner does not need to install and handle the gigaset_profile_gen application (as described in chapter Setting p yor own provisioning server page 45). To ensre that a wrong XML file content will not reslt in problems concerning the phone fnctions or even disable the phone and to ensre that possible encrypted XML and legacy encrypted binary profiles are identified, the XML content is evalated by the configration client (the phone) itself according to the following rles: Try to analyse the profile by searching for valid XML tags. Sccessfl? Yes Try to analyse the profile by searching for valid binary tags. No Sccessfl? Yes Process profile settings. Decrypt the content sing the ato-provisioning AES key. No The content and the handling of the profiles is the same, regardless of whether the format is a binary or an XML format. Plain XML will be spported only in the profiles themselves. Other server configration files like contry lists, provider lists, etc do not spport the plain XML format. The file ending (*.bin or *.xml) can be chosen freely. It will not be evalated in the configration client (the IP phone), bt it is sensible to choose the file sffix which reflects the file content. 35

36 Provisioning methods Secrity aspects HTTPS (TLS) is spported by most of the Gigaset VoIP phones. Server root certificates are sed. The profile can be encrypted with AES 128 sing a specific encryption key. The MAC address is sent dring the provisioning process and this MAC address can be sed for comparing the address with a data base containing all allowed MAC addresses. Therefore only known phones receive provisioning data. The activation code string contains an optional password. The se of HTTP Digest Athentication is possible. i It is not possible to se TLS client certificates. Client athentication via HTTP Digest Athentication Gigaset VoIP phones can se https (HTTP over TLS) bt withot client certification only. Conseqently, there is no information to check the athenticity of the client. Anyone can send a reqest to the Gigaset redirection server or a provisioning server with a randomly faked MAC address. If the random MAC address is correct, that person wold be redirected to a provisioning server and receive an end-ser profile configration. In order to avoid sch a scenario, an additional HTTP digest athentication as defined in RFC 2617 can be sed by the phones. The se of HTTP digest athentication is strongly recommended for all networks that are easily eavesdropped, becase otherwise a hacker cold easily access the ser accont information by simply recording and replicating the phones GET reqest to the provisioning server. Becase the HTTP digest athentication is based on a shared secret (which is contained in the password component of the activation code), an attacker who wishes to hijack the phone by providing a fake provisioner s URL will still not be able to find ot what the shared secret is becase it is never transmitted in clear text. The HTTP digest athentication algorithm implemented in Gigaset VoIP phones only spports the following context and therefore shold be taken into consideration by the provisioner s HTTP implementation: algorithm = "MD5" and qop = "ath". Frthermore, the ri= part of the athorisation header is bilt in the format described in RFC 2616 (i.e., withot the domain portion of the URI), e.g.: ri="/phone/cgi/ap?ac= " Certificates in PEM format Basically, PEM is a frame (starting with BEGIN CERTIFICATE and ending with END CERTIFICATE) containing a binary X.509 certificate. PEM was intended for the transport of certificates within s. Some servers se this format as the defalt format to store certificates. At present, PEM format is spported for the following devices: Gigaset C610 IP/N300 IP Gigaset N510 IP PRO PEM format can be configred via the phone s WEB UI or by download via ato provisioning. After download, the profile is converted to the DER format (Distingished Encoding Rles) and stored in the Tevero file system. 36

37 Download TLS certificates via a link in a profile Provisioning methods To download a TLS certificate via a link, the CERTIFICATE parameter is spported. This parameter enables e.g. a provider to force a download of a certificate withot any ser interaction. CERTIFICATE is only spported in plain XML profiles. XML syntax <CERTIFICATE class="string" vale=" Tag Name Vale Meaning CERTIFICATE URL The URL which refers to the certificate file. It mst be complete, i.e. contain the host and file name. Only one certificate tag is allowed per profile. Redirection to another location is spported! The certificate can be downloaded via a HTTP server only. At present, the CERTIFICATE tag is spported for the following devices: Gigaset C610 IP/N300 IP Gigaset N510 IP PRO 37

38 XML provisioning file XML provisioning file Configration data for Gigaset VoIP phones is provided by means of XML files. XML files are sed as direct inpt (plain XML provisioning) for Gigaset VoIP phones or as inpt for the gigaset_profile_gen application which converts the configration into a binary format comprehensible for Gigaset VoIP phones ( page 58). XML files can be created sing the Gigaset provisioning tool which provides configration data (a sbset of the available configration parameters) that is specific to the device or manally based on templates provided by Gigaset ( page 41). Configration file editor (provisioning tool) The configration file editor is sed to create a configration file for Gigaset IP phones of a specific device type (XML and binary). The configration files can be ploaded to Gigaset IP phones in the case of plain XML provisioning or can be sed as inpt files for a provisioning package. The reslt of the editing is stored on the Gigaset server. In order to se the file for provisioning, it has to be downloaded and saved on the provisioning server. When downloading the configration file, a ZIP archive is created, that contains: an XML file with configration parameters and parameter placeholders specific to the selected provisioning method (via MAC address or activation code), an XSD scheme file for validation, and a binary file with configration parameters. Starting The configration file editor is provided as a web ser interface. Together with the provisioning package editor it is part of the provisioning tool. Open the web ser interface as described on page 9. To create or edit a configration file, click on Configration file editor. Already existing configration files are listed. For each configration file the following information is available: No. Configration file Comment Changed on The following options are possible: Add new Edit Delete Download Back Nmber of the configration file. Name inclding a timestamp. Comment to identify the file. Date of last change. Create a new configration file. Revise an existing configration file. Delete an existing configration file. Download an existing configration file. Exit the configration file editor and retrn to the main window. If the maximm nmber of configration files is reached, it is not possible to add a new file or to edit an existing one before deleting some file(s). 38

39 XML provisioning file i To navigate within the tool, se the links and bttons available on the pages, e.g. Next or Back. Yo shold not se the browser navigation bttons. To exit the configration se the logot btton which is located top right on each page. Creating a configration file Click Add new to create a new configration file. The editor is opened and will gide yo throgh all necessary steps. Click Next to save the settings and precede to the next step. Click Back to retrn to the previos step. Click Clear all to reset all yor changes on the crrent page. Click Cancel to exit the editor withot saving yor settings and to retrn to the main window. Select device On the first page yo have to select the device type for which a configration is to be created. The page is not shown when an existing configration file is edited. In this case the part nmber and firmware version stay ntoched. Select a device type from the Part nmber drop-down list. The list provides all part nmbers of device types which are available for the spported devices. Once a part nmber is selected the information abot device type, variant and provisioning ID is shown. Select the Firmware version from the drop-down list. Only available versions for the selected part nmber are provided. After starting to edit an already existing configration file, yo can change the firmware version if needed. The part nmber cannot be changed. 39

40 XML provisioning file Editing parameters The configration file editor provides access to all available configration parameters for the selected device type/part nmber. The navigation bar on the left contains the available configration pages. Some pages may have sbpages (e.g. Telephony). Click on an entry to open the desired page. The pages only contain parameters for the selected device type/part nmber. If an existing configration file has been opened, the previosly stored parameter vales are loaded. For a new configration file the parameters are initially in the disabled state (check box nchecked). Defalt vales are set, if available, nless parameters are set in the disabled state. In this case the parameter is not inclded in the reslting configration file (neither XML nor binary). This means that the vale of this parameter will not be changed in the device being provisioned. For the parameters the following elements are available: Parameter name A check box on the left of the parameter vale. It has to be enabled in order to pt the changed vale of the parameter into effect. If the check box is not checked, the reslting configration file will not change the vale for this parameter within the devices. Editor control, depending on the parameter: Radio bttons To enable or disable the parameter. Drop-down list To select one entry from a list. Check box grop To select mltiple options from a option grop. Edit box To enter text, e.g. names, nmbers

41 Information/validation icon, with the following states: Info state: OK state: Error state: A validation hint showing the possible vale range. It shows information abot the allowed range for nmerical parameters and abot the maximm nmber of characters for strings. An Action btton providing the following options: Edit parameter Insert defalt setting Insert placeholder XML provisioning file Shown when the parameter is not enabled. Shown when the parameter is enabled and the vale/state is valid. Shown when the parameter is enabled and the vale/state is not valid. Note: Only the validity of a single parameter is checked. Cross-checking with other parameter vales to ensre a plasible configration is not performed. Select this option to edit the parameter vale. The defalt vale for the parameter is inserted (if the parameter has a defalt vale). Afterwards the vale can be changed. A placeholder vale for the parameter is inserted. This shold be sed to allow the insertion of ser-specific vales via the ap script ( page 51). Help information Move the crsor over a parameter and wait for a moment. A popp is opened containing information abot the parameter. Click on the information/validation icon to open a popp with additional information regarding the parameter. Saving the configration file If yo have set all configration vales as desired, click Next. Enter a File Name and a comment for the configration. The filename mst not exceed 14 characters. Only lowercase letters, digits and nderscore characters are allowed. The fll file name will be created atomatically sing the file name and a timestamp. If yo have edited an existing file yo can change the file name. Click Save to store the changes. A new configration file containing yor changes will be created. XML files Instead of sing the provisioning tool, yo can also create the XML configration files manally. XML files can be created based on templates that are provided by Gigaset and stored within the gigaset file system. A general template is provided in the sbordinate /gigaset/cgi/shop directory ( page 50). The following template file is available: template.xml Template for ato-provisioning Device-specific templates are available in the device s cgi sbdirectories ( page 59). The XML file syntax may be different depending on the device s fnctionality and date of manfactre. To get information on the correct XML syntax for a specific device please refer to the appropriate template in the device s sbdirectory. Gigaset spplies a template XML file which has to be adapted by the ato-provisioning script to provide the real provisioning data. 41

42 XML provisioning file XSD schema files To make sre that the XML file contains only configration parameters the phone nderstands, it has to be validated against a fixed schema file (referred to inside the XML file). Schema files are also provided by Gigaset and available in the general cgi directory as well as the device-specific cgi directories ( page 59). The following schema file is available: profile.xsd Configration parameters XML schema file for validating the template.xml file. The parameters sed for provisioning are described in general on page 8. Each Gigaset IP phone has a lot of frther configration parameters which can be provided by the XML inpt file additionally to the provider data. Details of the parameters mentioned here and a list of all possible configration parameters are available at i The list of modifiable parameters can change if frther featres are added to the phone in the ftre. Therefore, please refer to the template file (template.xml) and the schema file (profile.xsd) which are spplied. Attention: Yo shold never change the schema file any changes yo might desire in the schema file mst be provided by Gigaset. The schema file is the only garantee that the XML file is compatible with the Gigaset phone yo are marketing. XML template example The following is a short extract from the template.xml file. To view the total file yo can open it from the gigaset/cgi/shop directory ( page 59). The template provided by Gigaset for the XML file contains two types of parameters: A large set of parameters which have to be adapted for a specific provider. A smaller set of parameters intended to be adapted (by the provisioner s ap.cgi script) to tailor the file for an individal end cstomer. The latter set of parameters has been highlighted in the fragment shown below. <?xml version="1.0" encoding="iso "?> <ProviderFrame xmlns:xsi=" xsi:nonamespaceschemalocation="profile.xsd"> <Provider> <MAC_ADDRESS vale="insert MAC_ADDRESS here"/> <ACTIVATION_CODE vale="insert ACTIVATION_CODE here"/> <VERSION vale="insert VERSION here"/> <PROFILE_NAME class="string" vale="mgmt"/> <SYMB_ITEM ID="BS_IP_Data.cB_USE_CITY_CODE" class="symb_item" vale="0"/> <SYMB_ITEM ID="BS_AE_SwConfig.cContryCodeTone" class="symb_item" vale="0"/> </Provider> </ProviderFrame> 42

43 XML provisioning file Special parameters VERSION identifying configration changes The VERSION parameter in the XML file is somewhat special becase it is not really a configration item, bt instead is sed by the phone to detect whether there have been any changes in the configration since the last time it was changed. The parameter is a time string with the following mandatory format: ddmmyyhhmm where dd, mm, yy, hh and mm represent the decimal nmeric vales for day, month, year, hors and mintes respectively. Becase the phone converts this string into an eqivalent integer vale, it is important to choose valid date & time vales. In the phone, the change detection algorithm works as follows: Whenever the phone has reqested and processed an ato-provisioning file, it converts the string contained in the VERSION parameter into an integer, which is saved in the non-volatile RAM. In ftre, the phone compares this saved integer with the vale of the integer calclated from the VERSION parameter contained in any newly reqested ato-provisioning file. As long as the two integers are eqal, the phone assmes that the ato-provisioning file is identical with the old one, and will ignore it. If, however, the integers are different, the phone assmes that a new ato-provisioning file has been issed and pdates its configration accordingly, replacing its saved copy of the integer with the one calclated from the new file. For the ato-provisioning system, this means that whenever it wishes the phone to pdate its configration, it mst generate a new vale of the VERSION parameter. The design assmes that the ato-provisioning system will store this version string in the database entry belonging to a given end-cstomer, ths indicating the last time the configration for that particlar end-cstomer was changed. i Changing the VERSION string too often (e.g. on a daily basis or even more often) is not to be recommended, as it will force the phone to pdate its non-volatile memory nnecessarily. As this memory is implemented sing FLASH or EEPROM technology, which has a limited nmber of write cycles, the phone s sefl lifetime will sffer! 43

44 XML provisioning file EXTENDED_PROFILE additional profile download via link in profile The EXTENDED_PROFILE parameter enables providers e.g. to split their profile into ser-specific data from secre storage and common or server-specific data. The parameter is sed in a profile element to refer to another profile. Only one EXTENDED_PROFILE tag is allowed per profile. A maximm of three profiles can be carried ot seqentially, one main profile and two extended profiles. For easier nderstanding the first profile is called main profile and the others are called extended profiles. The EXTENDED_PROFILE parameter will be spported only in plain XML profiles. XML syntax <EXTENDED_PROFILE class="string" vale=" d_freenet_de.xml"/> Tag Name Vale Meaning EXTENDED_PROFILE URL The URL which refers to the next profile. It mst be complete, i.e. contain the host and file name. The extended profile can be downloaded via a HTTP server only. For extended profiles there are some restrictions in contrast to the main profile: Featre tags like MAC_ADDRESS or ACTIVATION_CODE will not be spported. If necessary these parameters mst be listed in the main profile. PROFILE_NAME and PROFILE_VERSION are still mandatory (they can be empty bt the tags itself mst be available). In the case of an error (e.g. file not fond) it is not possible to inform the ser which profile cold not be downloaded. So only one general message is sent. Only if all profiles cold be downloaded correctly the message sccess is sent. In the extended profiles, the new parameters CERTIFICATE and PROFILE_DOWNLOAD will be spported bt only if the extended profile is a plain XML profile. TLS is also possible. Additionally, it is possible to refer from a plain XML profile to a binary coded profile. At present, the EXTENDED_PROFILE tag is spported for the following devices: Gigaset C610 IP/N300 IP Gigaset N510 IP PRO 44

45 Setting p yor own provisioning server Setting p yor own provisioning server The general procedre for setting p ato-provisioning of Gigaset IP phones is as follows: Installing a Linx server Crrently, systems with i386 architectre (and newer, compatible ones) are spported. The installation file is distribted as a Linx RPM file, i.e. the Linx system sed, mst spport this packaging format. Preparing the Linx server Installing an Apache HTTP server The Apache HTTP server is an open sorce web server for UNIX and Windows systems. It is sed to handle the HTTP reqests of the Gigaset IP phones. Adapting the web server configration file for connecting the Gigaset ato-provisioning script To enable the ato-provisioning script ( page 51) to be exected sccessflly the web server configration file has to be adapted as follows: Add the gigaset/cgi directory to the Apache directories. Installing PHP script langage PHP is a general scripting langage designed for web development to prodce dynamic web pages. The code is interpreted by a web server with a PHP processor modle which generates the reslting web page. It also has evolved to inclde a command-line interface capability and can be sed in standalone graphical applications. Setting p a MySQL server (optional) MySQL is the recommended instrment for providing the ato-provisioning script with the ser-related data. Installing the ato-provisioning application Preparing the file system Installing the application Creating the ato-provisioning script or adapting the sample script ( page 51) Provisioning package editor (provisioning tool) The package editor is sed to create a cstomer-specific provisioning package which can be ploaded to Gigaset IP phones. A provisioning package can contain the configration for different device types. If a configration file is to be added to the package it mst have been created previosly ( page 38). The reslt of the editing process is a ZIP archive. It can be sed to set p the file system strctre of a provisioning server. The content depends on the package definition, for details page 48. It is stored on the Gigaset pdate server. In order to se the file for provisioning it has to be downloaded and saved on the provisioning server. Notes on MAC address or activation code-based provisioning mode Dring creation of yor ser accont, a three-digit activation code (the Gigaset part of the activation code page 28) shold be assigned to the accont. If it has been assigned, this code is shown by the tool, and the provisioning packages created with the tool will spport both MAC code- based and activation code-based provisioning. If the code has not been assigned, an appropriate message is otpt and the provisioning packages will spport only MAC code-based provisioning. To have an activation code assigned, please contact sys_engineering_ip_pro.gc@gigaset.com. 45

46 Setting p yor own provisioning server Starting The provisioning package editor is provided as a web ser interface. Together with the configration file editor, it is part of the provisioning tool. Open the web ser interface as described on page 9. To create or edit a provisioning package, click on Provisioning package editor. Already existing provisioning packages are listed. For each provisioning package the following information is available No. Package name Comment Change on Prov. server URL The following options are possible: Add new Edit Delete Download Back Nmber of the provisioning package. Name inclding a timestamp. Comment to identify the package. Date of last change. Address of the provisioning server configred by the ser. Create a new provisioning package. Revise an existing provisioning package. Delete an existing provisioning package. Download an existing provisioning package. Exit the provisioning package editor and retrn to the main window. Information abot created packages is stored on the server. In order to se the package for provisioning it mst be downloaded and saved on the provisioning server. The packages can be downloaded on demand via the Download btton. If the maximm nmber of provisioning packages is reached it is not possible to add a new package or to edit an existing one before deleting some package(s). i To navigate within the tool, se the links and bttons available on the pages, e.g. Next or Back. Yo shold not se the browser navigation bttons. To exit the configration se the logot btton which is located top right on each page. Creating a provisioning package Click Add new to create a new provisioning package. The package editor is opened and will gide yo throgh all necessary steps. Click Next to save the settings on a page and precede to the next step. Click Back to retrn to the previos step. Click Cancel to exit the editor withot saving yor settings and to retrn to the main window. Device-independent settings Enter the Provisioning server address. Yo only need to provide the address (IP or DNS) of the root folder on the server. This address will atomatically be completed with the common part. 46

47 Setting p yor own provisioning server Device Selection On this page the device types spported by the package are listed with the following information: To add a new device type: Select the Part nmber and Firmware version of the device type. Yo may add a Comment if yo wish. If yo want to inclde the firmware, accept the Add selected firmware to the package option. For devices allowing downgrades, yo can additionally define that downgrades shold be spported. Click on Add to add the device type to the package. If there is already a device type with the same variant and provisioning ID the device is not added. All settings apply only to the device type being added. This means that a package can contain device types with firmware inclded and device types withot firmware. Click on Delete to delete a device type from the list. Profile configration files On this page the configration files are assigned to the device types previosly defined. For each device type select the configration file from the drop-down list. The drop-down list contains the configration files already created and stored on the Gigaset server that match the variant and provisioning ID of the selected device type. Only configration files for the selected firmware versions or for older firmware versions are presented. Select None if yo do not want to have a configration file assigned. If there are no matching configration files No profile available is shown and the drop-down list is disabled. Click Edit to open the configration file editor ( page 38) to directly edit the configration file that is assigned to the package. As sal when editing a configration file, a new configration file will be created and the old one will be kept (it can be deleted afterwards if no longer needed). Store provisioning package Enter a File Name and a comment for the package. The version nmber will be created atomatically sing the file name and a timestamp. Click Save to store the package on the Gigaset pdate server. 47