![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Top]](icons/top.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
The VxWorks implementation of the PPP (Point-to-Point Protocol) is comprised of several different protocols that work together with the PPP network interface driver. Although PPP can, in theory, support a variety of protocols, the VxWorks implementation supports only the TCP/IP stack. The VxWorks PPP implementation is comprised of three main components:
PPP is one method by which VxWorks can communicate with other operating systems over a serial line connection. PPP supports Internet Protocol (IP) layer networking software over point-to-point configurations, such as long-distance telephone lines or RS-232 serial connections between machines. If either end of a PPP connection has other network interfaces (such as Ethernet) and is able to forward packets to other machines, a PPP connection can serve as a gateway between networks.
The basic functionality provided by PPP is similar to that of the Serial Line Internet Protocol (SLIP), with the advantage that PPP is extensible and offers various configurable options.
PPP provides a standard method for transporting multi-protocol datagrams over point-to-point links. It is designed for simple links which transport packets between two peers. These links provide full-duplex, simultaneous operation and are assumed to deliver packets in the order in which they are sent. It is intended that PPP provide a common solution for easy connectivity among a variety of hosts, bridges, and routers.
The following is a list of relevant Requests for Comments (RFCs) associated with the VxWorks PPP implementation:
The USENET news group, comp.protocols.ppp, is dedicated to the discussion of PPP-related issues. Information presented in this forum is often of a general nature (such as equipment, setup, or troubleshooting), but technical details concerning specific PPP implementations are discussed as well.
For many years, transferring Internet Protocol (IP) packets over serial lines was handled almost exclusively by the Serial Line Internet Protocol (SLIP). SLIP is a simple link-layer driver that is installed between IP stack code and a serial driver. While SLIP uses less object code than PPP and processes packets more efficiently (using compressed headers in CSLIP), it can carry only IP packets and it is not extensible. Furthermore, SLIP has several different protocol implementations that do not always communicate smoothly with each other. Nevertheless, its general ease of use and large installed base has made it the de facto standard for using IP over point-to-point serial lines.
The Point-to-Point Protocol (PPP) was developed to address the shortcomings of SLIP. Unlike SLIP, PPP is being defined and tracked by the Internet Engineering Task Force (IETF), and the protocol specifications have been published in multiple Request For Comments (RFC) documents. Although SLIP is still an attractive choice for systems that only require basic IP-packet transfers, the advantages of PPP are prompting the rapid growth of its installed base.
PPP supports several features that make it more suitable than SLIP for certain applications:
PPP encapsulation provides for simultaneous multiplexing of different network-layer protocols over the same link. The PPP encapsulation has been carefully designed to retain compatibility with most commonly used supporting hardware. The frame format of a standard PPP frame structure is shown in Figure 3-1.
In order to promote versatility and be portable to a wide variety of environments, PPP provides a Link Control Protocol (LCP). LCP is used when establishing links and negotiating a variety of configuration options. It is also used to create automatic agreement on encapsulation format options, to handle variable size limits placed on packets, to detect looped-back links and other common configuration errors, and to terminate links.
Other optional facilities provided by LCP include: authentication of the peer on the link by using authentication protocols such as PAP or CHAP, and determination when a link is functioning properly and when it is failing. After the link is established, PPP also allows an optional authentication. For more information, see RFC 1548.
The IP Control Protocol (IPCP) is the Network Control Protocol (NCP) for IP. IPCP is responsible for configuring, enabling, and disabling the IP protocol modules on both ends of the point-to-point link. It uses the same packet exchange mechanism as LCP. IPCP packets are not exchanged until PPP has established a link. IPCP is also responsible for IP address negotiation between peers. For more information, see RFC 1332.
The Password Authentication Protocol (PAP) provides a simple method by which the peer establishes its identity using a two-way handshake. This is done only upon the initial link creation. Once a link is established, an ID/password pair is sent repeatedly by the peer to the authenticator until authentication is acknowledged or the connection is terminated.
PAP is not a robust authentication protocol. Passwords are sent over the circuit "in the clear," without protection from playback or repeated trial-and-error attacks. The peer is in control of the frequency and timing of the attempts. This authentication method is most appropriately used when a plain-text password must be available to simulate a login at a remote host. For information about using PAP, see Using PAP, or refer to RFC 1334.
Challenge-Handshake Authentication Protocol (CHAP) is a more robust authentication protocol offering better security than PAP. CHAP periodically verifies the identity of a peer using a three-way handshake. This is done after an initial link is established, and can be repeated later at any time.
After a link is established, the authenticator sends a "challenge" message to the peer. The peer responds with a value calculated by a one-way hash function. The authenticator checks the response against its own calculation of the expected hash value. If the values match, the authentication is acknowledged; otherwise the connection is terminated.
CHAP provides protection against playback attack by issuing ever-changing challenges at specified time intervals. The use of repeated challenges is intended to limit the time of exposure to any single attack. The authenticator is in control of the frequency and timing of the challenges.
CHAP authentication for any particular link relies on the use of a "secret" known only to the authenticator and the peer. The secret is not sent over the link; therefore the server and its peer must both have access to it. In Tornado, this is achieved using various methods explained in Using CHAP. For further technical details, refer to RFC 1334.
Configuring your environment for PPP requires both host and target software installation and configuration. See your host's operating system manual for information on installing and configuring PPP on your host.1
To include the default PPP configuration, configure VxWorks with PPP support. The relevant configuration macro is INCLUDE_PPP.
|
CAUTION: A VxWorks image that includes PPP sometimes fails to load. This failure is due to the static maximum size of the VxWorks image allowed by the loader. This problem can be fixed by either reducing the size of the VxWorks image (by removing unneeded options), or by burning new boot ROMs. If you receive a warning from vxsize when building VxWorks, or if the size of your image becomes greater than that supported by the current setting of RAM_HIGH_ADRS, see Creating Bootable Applications in the Tornado User's Guide: Cross-Development for information on how to resolve the problem.
|
||||||||||||||||||
You can include the optional DES cryptographic package for use with the Password Authentication Protocol (PAP). The relevant configuration macro is INCLUDE_PPP_CRYPT. It is not included in the standard Tornado Release; contact your WRS Sales Representative to inquire about the availability of this optional package. The DES package allows user passwords to be stored in encrypted form on the VxWorks target. If the package is installed, then it is useful only when the VxWorks target is acting as a PAP server, that is, when VxWorks is authenticating the PPP peer. Its absence does not preclude the use of PAP. For detailed information about using the DES package with PAP, see Using PAP).
This PPP implementation includes many optional features (approximately 50 in all) that can be configured in to enable the PPP capabilities listed in 3.4.2 PPP Features. There are three methods of configuration:
Each of these methods is described in a section that follows. For brief descriptions of the various PPP options, see Table 3-3.
|
NOTE: See the Tornado User's Guide: Projects for information on how to set some configuration options through a graphical user interface, without directly editing config.h.
|
||||||||||||||||||
First, make sure the PPP_OPTIONS_STRUCT constant is defined in config.h (it is defined by default). Unless PPP_OPTIONS_STRUCT is defined, configuration options in config.h cannot be enabled.
Then, specify the default serial interface that will be used by usrPPPInit( ) by defining the PPP_TTY constant. Configuration options can be selected using configuration constants only when usrPPPInit( ) is invoked to initialize PPP. Specify the number of seconds usrPPPInit( ) will wait for a PPP link to be established between a target and peer by defining the PPP_CONNECT_DELAY constant. Table 3-1 lists the principal configuration constants used with PPP.
Table 3-2 shows the two basic formats used for configuration options in config.h. The full list of options available with PPP appears in column 1 of Table 3-3. By default, all of these options are disabled. To enable any PPP_OPT_option setting, define its value to be 1 (these option constants are boolean values). To set any PPP_STR_optionstring entry, define it by representing the desired value as a string. For example, to set PPP_STR_MTU to 1000, enter:
#define PPP_STR_MTU "1000"
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
Setting PPP_OPTIONS_STRUCT, PPP_TTY, and PPP_CONNECT_DELAY in config.h, as well as any configuration options, constitutes a modification to the configuration file. These changes do not actually take effect until after you have recompiled VxWorks and initialized PPP. To initialize PPP, call usrPPPInit( ). You can make this call manually from a target shell (see Initializing a PPP Link) or can include it in the boot code (see Booting over the Network).
PPP options may be set at run-time by filling in a PPP options structure and passing the structure location to the pppInit( ) routine. This routine is the standard entry point for initializing a PPP link (see Initializing a PPP Link).
The PPP options structure is typedefed to PPP_OPTIONS, and its definition is located in h/netinet/ppp/options.h, which is included through h/pppLib.h.
The first field of the structure is an integer, flags, which is a bit field that holds the ORed value of the OPT_option macros displayed in column 2 of Table 3-3. Definitions for OPT_option are located in h/netinet/ppp/options.h. The remaining structure fields in column 2 are character pointers to the various PPP options specified by a string.
The following code fragment is one way to set configuration options using the PPP options structure. It initializes a PPP interface that uses the target's second serial port (/tyCo/1). The local IP address is 90.0.0.1; the IP address of the remote peer is 90.0.0.10. The baud rate is the default rate for the tty device. The VJ compression and authentication options have been disabled, and LCP (Link Control Protocol) echo requests have been enabled.
PPP_OPTIONS pppOpt; /* PPP configuration options */
void routine ()
{
pppOpt.flags = OPT_PASSIVE_MODE | OPT_NO_PAP | OPT_NO_CHAP |
OPT_NO_VJ;
pppOpt.lcp_echo_interval = "30";
pppOpt.lcp_echo_failure = "10";
pppInit (0, "/tyCo/1", "90.0.0.1", "90.0.0.10", 0, &pppOpt, NULL);
}
PPP options are most conveniently set using an options file. There is one restriction: the options file must be readable by the target without there being an active PPP link. Therefore the target must either have a local disk or RAM disk or an additional network connection. For more information about using file systems, see VxWorks Programmer's Guide: Local File Systems.
This configuration method can be used with either usrPPPInit( ) or pppInit( ). It also can be used to modify the selection of PPP options previously configured using configuration constants in config.h or the option structure PPP_OPTION.
When using usrPPPInit( ) to initialize PPP, define the configuration constant PPP_OPTIONS_FILE to be the absolute path name of the options file (NULL by default). When using pppInit( ), pass in a character string that specifies the absolute path name of the options file.
The options file format is one option per line; comment lines begin with #. For a description of option syntax, see the manual entry for pppInit( ).
The following code fragment generates the same results as the code example in Selecting PPP Options Using an Options Structure. The difference is that the configuration options are obtained from a file rather than a structure.
pppFile = "mars:/tmp/ppp_options"; /* PPP config. options file */
void routine ()
{
pppInit (0, "/tyCo/1", "90.0.0.1", "90.0.0.10", 0, NULL, pppFile);
}
In this example, mars:/tmp/ppp_options is a file that contains the following:
passive no_pap no_chap no_vj lcp_echo_interval 30 lcp_echo_failure 10
A PPP link is initialized by calls to either usrPPPInit( ) or pppInit( ). When either of these routines is invoked, the remote peer should be initialized. When a peer is running in passive mode, it must be initialized first (see PPP Options.)
The usrPPPInit( )routine is in config/all/bootConfig.c and src/config/usrNetwork.c. There are four ways it can be called:
If the boot device is set to ppp, usrPPPInit( ) is called as follows:
Use either syntax when calling usrPPPInit( ):
usrPPPInit ("bootDevice", unitNum, "localIPAddress", "remoteIPAddress")
usrPPPInit ("bootDevice", unitNum, "localHostName", "remoteHostName")
You can use host names in usrPPPInit( ) provided the hosts have been previously added to the host database. For example, you can call usrPPPInit( ) in the following way:
usrPPPInit ("ppp=/tyCo/1,38400", 1, "147.11.90.1", "147.11.90.199")
The usrPPPInit( ) routine calls pppInit( ), which initializes PPP with the configuration options that were specified at compile-time (see Selecting PPP Options By Configuring VxWorks). The pppInit( ) routine can be called multiple times to initialize multiple channels.2 The connection timeout is specified by PPP_CONNECT_DELAY. The return value of this routine indicates whether the link has been successfully established--if the return value is OK, the network connection should be fully operational.
The pppInit( ) routine is the standard entry point for initializing a PPP link. All available PPP options can be set using parameters specified for this routine (see Selecting PPP Options Using an Options Structure). Unlike usrPPPInit( ), the return value of pppInit( ) does not indicate the status of the PPP link; it merely reports whether the link could be initialized. To check whether the link is actually established, call pppInfoGet( ) and make sure that the state of IPCP is OPENED. The following code fragment demonstrates use of this mechanism for PPP unit 2:
PPP_INFO pppInfo;
if ((pppInfoGet (2, &pppInfo) == OK) &&
(pppInfo.ipcp_fsm.state == OPENED))
return (OK); /* link established */
else
return (ERROR); /* link down */
Merely deleting the VxWorks tasks that control PPP or rebooting the target severs the link only at the TCP/IP stack, but does not delete the link on the remote peer end.
The return value of pppDelete( ) does not indicate the status of the PPP link. To check whether the link is actually terminated, call pppInfoGet( ) and make sure the return value is ERROR. The following code fragment demonstrates the usage of this mechanism for PPP unit 4:
PPP_INFO pppInfo;
if (pppInfoGet (4, &pppInfo) == ERROR)
return (OK); /* link terminated */
else
return (ERROR); /* link still up */
Table 3-3 lists all the configuration options supported by PPP. Each option is shown in its three forms, corresponding to the configuration methods explained in the following sections:
A brief description of each option follows the three formats. Configuration options specified in the options file PPP_OPTIONS_FILE take precedence over any previously set in config.h or set by passing the structure PPP_OPTIONS to pppInit( ). For example:
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
PPP provides security through two authentication protocols: PAP (see Password Authentication Protocol (PAP)) and CHAP (see Challenge-Handshake Authentication Protocol (CHAP)). This section introduces the use of PPP link-layer authentication (introduced in Link Control Protocol (LCP)), and describes the format of the secrets files.
In VxWorks, the default behavior of PPP is to provide authentication when requested by a peer but not to require authentication from a peer. If additional security is required, choose PAP or CHAP by enabling the corresponding option. PPP in VxWorks can act as a client (the peer authenticating itself) or a server (the authenticator).
Authentication for both PAP and CHAP is based on secrets, selected from a secrets file or from the secrets database built by the user (which can hold both PAP and CHAP secrets). A secret is represented by a record, which itself is composed of fields. The secrets file and the secrets database contain secrets that authenticate other clients, as well as secrets used to authenticate the VxWorks client to its peer. In the case that a VxWorks target cannot access the secrets file through the file system, use pppSecretAdd( ) to build a secrets database.
Secrets files for PAP and CHAP use identical formats. A secrets record is specified in a file by a line containing at least three words that specify the contents of the fields client, server, and secret, in that order. For PAP, secret is a password which must match the password entered by the client seeking PAP authentication. For CHAP, both client and server must have identical secrets records in their secrets files; the secret consists of a string of one or more words (for example, "an unguessable secret").
Table 3-4 is an example of a secrets file. It could be either a PAP or CHAP secrets file, since their formats are identical.
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
At the time of authentication, for a given record, PPP interprets any words following client, server, and secret as acceptable IP addresses for the client and secret specified. If there are only three words on the line, it is assumed that any IP address is acceptable; to disallow all IP addresses, use a dash (-). If the secret starts with an @, what follows is assumed to be the name of a file from which to read a secret. An asterisk (*) as the client or server name matches any name. When authentication is initiated, a best-match algorithm is used to find a match to the secret, meaning that, given a client and server name, the secret returned is for the closest match found.
On receiving an authentication request, PPP checks for the existence of secrets either in an internal secrets database or in a secrets file. If PPP does not find the secrets information, the connection is terminated.
The secrets file contains secrets records used to authenticate the peer, and those used to authenticate the VxWorks client to the peer. Selection of a record is based on the local and remote names. By default, the local name is the host name of the VxWorks target, unless otherwise set to a different name by the option local_auth_name in the options file. The remote name is set to a NULL string by default, unless otherwise set to a name specified by the option remote_auth_name in the options file. (Both local_auth_name and remote_auth_name can be specified in two other forms, as can other configuration options listed in Table 3-3.)
The default behavior of PPP is to authenticate itself if requested by a peer but not to require authentication from a peer. For PPP to authenticate itself in response to a server's PAP authentication request, it only requires access to the secrets. For PPP to act as an authenticator, you must turn on the PAP configuration option.
Secrets can be declared in a file or built into a database. The secrets file for PAP can be specified in one of the following ways:
pap_file /xxx/papSecrets
If the VxWorks target is unable to access the secrets file, call pppSecretAdd( )to build a secrets database.
If PPP requires the peer to authenticate itself using PAP, the necessary configuration option can be set in one of the following ways:
require_pap
Secrets records are first searched in the secrets database; if none are found there, then the PAP secrets file is searched. The search proceeds as follows:
The default behavior of PPP is to authenticate itself if requested by a peer but not to require authentication from a peer. For PPP to authenticate itself in response to a server's CHAP authentication request, it only requires access to the secrets. For PPP to act as an authenticator, you must turn on the CHAP configuration option.
CHAP authentication is instigated when the authenticator sends a challenge request packet to the peer which responds with a challenge response. Upon receipt of the challenge response from the peer, the authenticator compares it with the expected response and thereby authenticates the peer by sending the required acknowledgment. CHAP uses the MD5 algorithm for evaluation of secrets.
The secrets file for CHAP can be specified in any of the following ways:
chap_file /xxx/chapSecrets
If PPP requires the peer to authenticate itself using CHAP, the necessary configuration option can be set in one of the following ways:
require_chap
Secrets are first searched in the secrets database; if none are found there, then the CHAP secrets file is searched. The search proceeds as follows:
PPP provides connect and disconnect hooks for use with user-specific software. Use the pppHookAdd( ) routine to add a connect hook that executes software before initializing and establishing the PPP connection or a disconnect hook that executes software after the PPP connection has been terminated. The pppHookDelete( ) routine deletes connect and disconnect hooks.
The routine pppHookAdd( ) takes three arguments: the unit number, a pointer to the hook routine, and the hook type (PPP_HOOK_CONNECT or PPP_HOOK_DISCONNECT). The routine pppHookDelete( ) takes two arguments: the unit number and the hook type. The hook type distinguishes between the connect hook and disconnect hook routines.
Two arguments are used to call the connect and disconnect hooks: unit, which is the unit number of the PPP connection, and fd, the file descriptor associated with the PPP channel. If the user hook routines return ERROR, then the link is gracefully terminated and an error message is logged.
The code in Example 3-1 demonstrates how to hook the example routines, connectRoutine( ) and disconnectRoutine( ), into the PPP connection establishment mechanism and termination mechanism, respectively.
#include <vxWorks.h>
#include <pppLib.h>
/* type declarations */
void attachRoutine (void);
STATIC int connectRoutine(int unit, int fd);
STATIC int disconnectRoutine(int unit, int fd);
void attachRoutine (void)
{
/* add connect hook to unit 0 */
pppHookAdd (0, connectRoutine, PPP_CONNECT_HOOK);
/* add disconnect hook to unit 0 */
pppHookAdd (0 , disconnectRoutine, PPP_DISCONNECT_HOOK);
}
STATIC int connectRoutine
(
int unit,
int fd
)
{
BOOL connectOk = FALSE;
/* user specfic connection code */
{
..........
connectOk = TRUE;
}
if (connectOk)
return (OK);
else
return (ERROR);
}PPP can be used in two ways in the Tornado environment. The PPP link can serve as an additional network interface apart from the existing default network interface, or it can be the default network interface on the target, causing PPP to serve as a network back end for the target server on the host.
% pppd passive /dev/ttyb 38400
[VxWorks Boot}: c boot device : ppp,38400 processor number : 0 host name : host file name : /usr/wind/target/config/mv177/vxWorks inet on ethernet (e) : 90.0.0.165:ffffff00 host inet (h) : 90.0.0.5 gateway inet (g) : 90.0.0.5 user (u) : thardy flags (f) : 0x4 target name (tn) : luna
Attaching network interface ppp0... ppp0: ppp 2.1.2 started by ppp0: Connect: ppp0 <--> /tyCo/1 ppp0: local IP address 90.0.0.165 ppp0: remote IP address 90.0.0.5 done. Attaching network interface lo0... done. Loading... 361620 + 70448 + 34350 Starting at 0x1000...
You are now ready to start the target server and run Tornado. For more information on starting Tornado refer to the Tornado User's Guide.
The PPP connection is a network back end established on a serial link. When using the PPP link to communicate with the target, all the Tornado tools work in the same way as any other network back end. (See the Tornado User's Guide.)
|
|
CAUTION: System-level debugging is not available when using the PPP link. To perform system-level debugging, use the regular serial back end described in the Tornado User's Guide.
|
||||||||||||||||||
Because of the complex nature of PPP, you may encounter problems using it in conjunction with VxWorks. Give yourself the opportunity to get familiar with running VxWorks configured with PPP by starting out using a default configuration. Additional options for the local peer should be disabled. (These can always be added later.)
Problems with PPP generally occur in either of two areas: when establishing links and when using authentication. The following sections offer checklists for troubleshooting errors that have occurred during these processes. If, however, difficulties using PPP with VxWorks persist, contact the Wind River Systems technical support organization.
The link is the basic operating element of PPP; a proper connection ensures the smooth functioning of PPP, as well as VxWorks. The following steps should help resolve simple problems encountered when establishing a link.
% usrPPPInit
Authentication is one of the more robust features of PPP for VxWorks. The following steps may help you troubleshoot basic authentication problems.
1: If your host operating system does not provide PPP facilities, you can use a publicly available implementation. One popular implementation for SunOS 4.1.x (and several other hosts) is the PPP version 2.1.2 implementation provided in the unsupported/ppp-2.1.2 directory. This code is publicly available and is included only as a convenience. This code is not supported by Wind River Systems.
2: The usrPPPInit( ) routine can specify the unit number as a parameter. If this number is omitted, PPP defaults to 0.