CM_VPNEntries Configuration Service Provider

4/8/2010

The CM_VPNEntries Configuration Service Provider configures the Virtual Private Network (VPN) entries on the device. Users can use VPN to connect to a corporate network using an Internet.

Note

This Configuration Service Provider is managed over the OMA Client Provisioning (formerly WAP Client Provisioning) protocol. To provision devices using the OMA DM protocol, use the VPN Configuration Service Provider instead. Access to this Configuration Service Provider is determined by Security roles. Because OEMs and Mobile Operators can selectively disallow access, ask them about the availability of this Configuration Service Provider. For more information about roles, see Security Roles and Default Roles for Configuration Service Providers.

The nocharacteristic tag will work on the top two levels to delete all, or specific, entries.

The following table shows the default settings. The default security role maps to each subnode unless specific permission is granted to the subnode.

Permissions	Read/Write
Roles allowed to query and update setting	Manager AuthenticatedUser

The following image shows the Configuration Service Provider in tree format as used by OMA Client Provisioning.**

Characteristics

• <entryname>
  The <entryname> characteristic is used as the name of the connection. Fields under this characteristic specify parameters for this connection.

  Note

  The system does not allow duplicate entry names among CM_VPNEntries, CM_PPPEntries, and CM_GPRSEntries.

Parameters

• AltDnsAddr
  This parameter is used in the <entryname> characteristic and is placed in the ipaddrDnsAlt member of the RASENTRY structure.

  Note

  Once configured, the AltDnsAddr parameter cannot be set to null by configuration with a blank string. The only way to change the setting is to pass in the value "0.0.0.0".

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Alternate DNS address

• AltWinsAddr
  Used in the <entryname> characteristic and is placed in the ipaddrWinsAlt member of the RASENTRY structure. .

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Alternate WINS address

• AreaCode
  Used in the <entryname> characteristic. This value specifies the area-code portion of the phone number. This value is placed in the szAreaCode member of the RASENTRY structure.

• CountryCode
  Used in the <entryname> characteristic. This value specifies the country/region code portion of the phone number. This value is placed in the dwCountryCode member of the RASENTRY structure.

• Desc.<langid>
  Used in the <entryname> characteristic. A tag in the format of Desc.<langid> is used as the language-specific identifier for that entry. For example, if the field <parm name="Desc.0409" value="GPRS Connection" /> is set, "GPRS Connection" appears in the UI to identify this connection when the device is set to the English language (language ID 0409).

  Descriptions for multiple languages may be provisioned using this mechanism, and the operating system automatically switches among them if the user changes language preferences on the device. If no <Desc> tag is provisioned for a specific language, the system defaults to the characteristic tag name used to create the entry.

• DestId
  Used in the <entryname> characteristic as a GUID that represents the unique ID of the network to which this entry connects. See the Connmgr.h header for predefined GUID values IID_DestNet*.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Connects to

• DeviceName
  Used in the <entryname> characteristic. This value specifies the local portion of the phone number. This value is placed in the szDeviceName member of the RASENTRY structure. DeviceName contains the name of a TAPI device to use with this phone-book entry, for example, "XYZ Corp 28800 External".

  To enumerate the number of available RAS-capable devices, use the lineInitialize function.

  For Smartphone 2002, by default, this parameter contains the name of the cellular TAPI device (specified in Tsp.h) of "Cellular Line".

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Device name

• DeviceType
  Used in the <entryname> characteristic. This value is placed in the ipaddrDns member of the RASENTRY structure The default value for this parameter is RASDT_Modem.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Device type

• DeviceSpecificRAW
  Used in the <entryname> characteristic to allow querying or setting the TAPI device-specific data structure associated with the RAS entry. This duplicates the functionality of the various XML tags under the <entryname>/DevSpecificCellular and <entryname>/DevSpecificUnimodem characteristics, and also allows the setting of the device-specific information for other non-standard TAPI service providers.

  The string value is interpreted as a hexadecimal byte stream, for example the string "FFFFFFFF" sets the structure to a single DWORD with all bits set. The string should describe the entire data structure and cannot just set the initial section of it. The resulting structure is passed into the TAPI service provider through lineSetDevConfig each time the connection is brought up.

  Note

  Use this parameter with caution because it allows direct manipulation of the underlying data structures used by the TAPI service provider.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String

• DialAsLocalCall
  Used in the <entryname> characteristic to specify the setting of the RASEO_DialAsLocalCall member in the RASENTRY structure. Possible values are 0 or 1. For more information about RASENTRY and the use of this parameter, see MSDN.

  Note

  For cellular devices, this member is typically ignored, and the system is programmed to dial the full canonical number, for example, "+<country/region code><area code><local number>."

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Dial as local call

• DnsAddr
  Used in the <entryname> characteristic and is placed in the ipaddrDns member of the RASENTRY structure. For more information about RASENTRY, see MSDN.

  Note

  Once configured, the DnsAddr parameter cannot be set to null by configuration with a blank string. The only way to change the setting is to pass in the value "0.0.0.0".

  Permissions	Read/Write
  Data type	String
  Label	DNS address

• Domain
  Used in the <entryname> characteristic. This value is placed in the ipaddrDns member of the RASENTRY structure. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Domain:
  Semantic type	url

• Enabled
  This parameter can be used in the <entryname> characteristic to enable or disable a connection entry without removing it from the system. Permitted values are 0 for OFF or 1 for ON.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Enabled

• FrameSize
  Used in the <entryname> characteristic. This value is placed in the dwFrameSize member of the RASENTRY structure. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Integer
  Label	Frame size

• Framing
  Used in the <entryname> characteristic. This value is placed in the dwFramingProtocol member of the RASENTRY structure. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Framing

• IpAddr
  Used in the <entryname> characteristic. This value specifies the IP address to be used while this connection is active. This value is placed in the ipaddr member of the RASENTRY structure. The ipAddr member is ignored unless dwfOptions specifies the RASEO_SpecificIpAddr member. For more information about RASENTRY and the use of this parameter, see MSDN.

  Note

  If your VPN network IP address class belongs to the GPRS IP address class, the VPN network cannot be reached when both GPRS and VPN connections are active (connected).

  The following table shows the default settings for this parameter.

  Permissions	Read/Write
  Data type	String
  Label	IP address:

• IpHeaderCompression
  Used in the <entryname> characteristic to specify the setting of the RASEO_IpHeaderCompression member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Use header compression

• IpSecAuth
  Used in the <entryname> characteristic to specify the authentication mechanism used if L2TP/IPSec is selected as the VPN type. Possible values are:

  • 0 for certificate
  • 1 for pre-shared key

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Authenticate IPSec/L2TP connections using
  Roles allowed to query and update setting	Manager AuthenticatedUser Operator-TPS

• Password
  Used in the <entryname> characteristic. This value specifies the password to be used during authentication. This value is placed in the szPassword member of the RASDIALPARAMS structure. For more information about RASENTRY and the use of this parameter, see MSDN.

  If this parameter is left empty, the operating system optionally automatically prompts for the user name and password when making a connection. Queries of this field return a string that is composed of asterisks (*).

  When setting the password, passing in the same string causes the new password to be ignored and does not change the existing password.

  If the password is left empty, the system optionally automatically prompts for the user name and password when making a connection.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Password:
  Semantic type	alphanumeric-password

• Phone
  Used in the <entryname> characteristic. This value specifies the local portion of the phone number. This value is placed in the szLocalPhoneNumber member of the RASENTRY structure. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Server:
  Semantic type	url

• PresharedKey
  Used in the <entryname> characteristic to store the value of the pre-shared key if this authentication method is selected for IPSec/L2TPP. The preshared key string has a maximum length of 256 characters containing any characters. This string is entered as plain text but appears as asterisks once the user leaves the edit box page.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	A Pre-shared key
  Roles allowed to query and update setting	Manager AuthenticatedUser Operator-TPS

• ReadOnly
  This parameter is used in the <entryname> characteristic and determines whether users are able to modify VPN settings. Permitted values are 0 for false and 1 for true. If the value is set to 1, users will be able to view, but not change, the VPN settings on the device.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Roles allowed to query and update setting	Manager Operator TPS

• RemoteDefaultGateway
  Used in the <entryname> characteristic to specify the setting of the RASEO_RemoteDefaultGateway member in the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more about RASENTRY and the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean

• RequireDataEncryption
  Used in the <entryname> characteristic to specify the setting of the RASEO_RequireDataEncryption member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about RASENTRY and the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Require data encryption

• RequireEncryptedPw
  Used in the <entryname> characteristic to specify the setting of the RASEO_RequireDataEncryption member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Require Microsoft-encrypted password

• RequireMsEncryptedPw
  Used in the <entryname> characteristic to specify the setting of the RASEO_RequireMsEncryptedPw member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Require Microsoft-encrypted password

• RequirePw
  Used in the <entryname> characteristic to specify whether the system should prompt for a user name/password/domain name before dialing the phone number. If set to 1, the system prompts if no password or user name is provisioned. If set to 0, the system does not prompt for a password before dialing even if no password or user name is provisioned. For PPP connections, the default value of this parameter is 1.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Integer
  Label	Require Password Before Connecting

• Script
  Used in the <entryname> characteristic. This value specifies a string containing the name of the script file. This value is placed in the szScript member of the RASENTRY structure. The name of the script file should be a full path. For more information about RASENTRY and the use of this parameter, see MSDN.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String

• SpecificIpAddr
  This parameter is used in the <entryname> characteristic and controls the setting of the RASEO_SpecificIpAddr member in the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	IP address

• SpecificNameServers
  Used in the <entryname> characteristic to specify the setting of the RASEO_SpecificIpAddr member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	Specific name servers

• SrcId
  Used in the <entryname> characteristic as a GUID that represents the unique ID of the network from which this entry connects. See the connmgr.h header file for predefined GUID values IID_DestNet*. Typically, a VPN connection connects from the Internet to a private network, so the value of SrcId would be that of IID_DestNetInternet, which is "{436EF144-B4FB-4863-A041-8F905A62C572}".

  The following table shows the default settings.

  Permissions	read/write
  Data type	string
  Label	Connects from:

• SwCompression
  Used in the <entryname> characteristic to specify the setting of the RASEO_SwCompression member of the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Use software compression

• Type
  Used in the <entryname> characteristic to specify the VPN type. Possible values are:

  • 0 for PPTP
  • 1 for IPSec/L2TP

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Roles allowed to query and update setting	Manager AuthenticatedUser Operator-TPS

• UseCountryAndAreaCodes
  Used in the <entryname> characteristic to control the setting of the RASEO_UseCountryAndAreaCodes member in the RASENTRY structure. Permitted values are 0 for OFF or 1 for ON. See MSDN for more information about the use of this parameter.

  For VPN connections, this parameter is ignored.

  Note

  For cellular devices, this parameter is typically ignored, and the system is programmed to dial the full canonical number, for example, "+<country/region code><area code><local number>".

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	Boolean
  Label	Use country/region and area codes

• UserName
  Used in the <entryname> characteristic. This value specifies the user name to be used during authentication. This value is placed in the szUserName member of the RASDIALPARAMS structure. If this parameter is left empty, the operating system optionally automatically prompts for the user name and password when making a connection.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	User name:

• WinsAddr
  Used in the <entryname> characteristic. This value specifies the IP address of the WINS server to be used while this connection is active. This value is placed in the ipaddrWins member of the RASENTRY structure. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers member.

  The following table shows the default settings.

  Permissions	Read/Write
  Data type	String
  Label	WINS Address
  Roles allowed to query and update setting	Manager AuthenticatedUser

Microsoft Custom Elements

The following table shows the Microsoft custom elements that this Configuration Service Provider supports for OMA Client Provisioning.

Elements	Available
noparm	No
nocharacteristic	Yes
characteristic-query	Yes
parm-query	Yes

Use these elements to build standard OMA Client Provisioning (formerly WAP Client Provisioning) configuration XML. For information about specific elements, see MSPROV DTD Elements. For examples of how to generally use the Microsoft custom elements, see OMA Client Provisioning XML File Examples.

For information about OMA Client Provisioning, see OMA Client Provisioning Files.

See Also

Tasks

CM_VPNEntries Configuration Service Provider Examples for OMA Client Provisioning

Concepts

Configuration Service Provider Reference for Windows Mobile Devices