xref: /freebsd/share/man/man4/ng_mppc.4 (revision 7aa383846770374466b1dcb2cefd71bde9acf463)
1.\" Copyright (c) 1996-2000 Whistle Communications, Inc.
2.\" All rights reserved.
3.\"
4.\" Subject to the following obligations and disclaimer of warranty, use and
5.\" redistribution of this software, in source or object code forms, with or
6.\" without modifications are expressly permitted by Whistle Communications;
7.\" provided, however, that:
8.\" 1. Any and all reproductions of the source or object code must include the
9.\"    copyright notice above and the following disclaimer of warranties; and
10.\" 2. No rights are granted, in any manner or form, to use Whistle
11.\"    Communications, Inc. trademarks, including the mark "WHISTLE
12.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13.\"    such appears in the above copyright notice or in the software.
14.\"
15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31.\" OF SUCH DAMAGE.
32.\"
33.\" Author: Archie Cobbs <archie@FreeBSD.org>
34.\"
35.\" $Whistle: ng_mppc.8,v 1.1 1999/12/08 20:20:39 archie Exp $
36.\" $FreeBSD$
37.\"
38.Dd December 8, 1999
39.Dt NG_MPPC 4
40.Os
41.Sh NAME
42.Nm ng_mppc
43.Nd Microsoft MPPC/MPPE compression and encryption netgraph node type
44.Sh SYNOPSIS
45.In sys/types.h
46.In netgraph/ng_mppc.h
47.Sh DESCRIPTION
48The
49.Nm mppc
50node type implements the Microsoft Point-to-Point Compression (MPPC)
51and Microsoft Point-to-Point Encryption (MPPE) sub-protocols of
52the PPP protocol.
53These protocols are often used in conjunction with the Point-to-Point
54Tunneling Protocol (PPTP).
55.Pp
56The node has two hooks,
57.Dv "comp"
58for compression and
59.Dv "decomp"
60for decompression.
61Typically one or both of these hooks would be connected to the
62.Xr ng_ppp 4
63node type hook of the same name.
64Each direction of traffic flow is independent of the other.
65.Sh HOOKS
66This node type supports the following hooks:
67.Pp
68.Bl -tag -compact -width vjc_vjuncomp
69.It Dv comp
70Connection to
71.Xr ng_ppp 4
72.Dv "comp"
73hook.
74Incoming frames are compressed and/or encrypted, and sent
75back out the same hook.
76.It Dv decomp
77Connection to
78.Xr ng_ppp 4
79.Dv "decomp"
80hook.
81Incoming frames are decompressed and/or decrypted, and sent
82back out the same hook.
83.El
84.Sh CONTROL MESSAGES
85This node type supports the generic control messages, plus the following:
86.Bl -tag -width foo
87.It Dv NGM_MPPC_CONFIG_COMP
88This command resets and configures the node for a session in the
89outgoing traffic direction (i.e., for compression and/or encryption).
90This command takes a
91.Dv "struct ng_mppc_config"
92as an argument:
93.Bd -literal -offset 0n
94/* Length of MPPE key */
95#define MPPE_KEY_LEN      16
96
97/* MPPC/MPPE PPP negotiation bits */
98#define MPPC_BIT          0x00000001      /* mppc compression bits */
99#define MPPE_40           0x00000020      /* use 40 bit key */
100#define MPPE_56           0x00000080      /* use 56 bit key */
101#define MPPE_128          0x00000040      /* use 128 bit key */
102#define MPPE_BITS         0x000000e0      /* mppe encryption bits */
103#define MPPE_STATELESS    0x01000000      /* use stateless mode */
104#define MPPC_VALID_BITS   0x010000e1      /* possibly valid bits */
105
106/* Configuration for a session */
107struct ng_mppc_config {
108    u_char    enable;                 /* enable */
109    u_int32_t bits;                   /* config bits */
110    u_char    startkey[MPPE_KEY_LEN]; /* start key */
111};
112
113.Ed
114The
115.Dv enabled
116field enables traffic flow through the node.
117The
118.Dv bits
119field contains the bits as negotiated by the Compression Control Protocol
120(CCP) in PPP.
121The
122.Dv startkey
123is only necessary if MPPE was negotiated, and must be equal to the
124session start key as defined for MPPE.
125This key is based on the MS-CHAP credentials used at link authentication time.
126.It Dv NGM_MPPC_CONFIG_DECOMP
127This command resets and configures the node for a session in the
128incoming traffic direction (i.e., for decompression and/or decryption).
129This command takes a
130.Dv "struct ng_mppc_config"
131as an argument.
132.It Dv NGM_MPPC_RESETREQ
133This message contains no arguments, and is bi-directional.
134If an error is detected during decompression, this message is sent by the
135node to the originator of the
136.Dv NGM_MPPC_CONFIG_DECOMP
137message that initiated the session.
138The receiver should respond by sending a PPP CCP Reset-Request to the peer.
139.Pp
140This message may also be received by this node type when a CCP Reset-Request
141is received by the local PPP entity.
142The node will respond by flushing its outgoing compression and encryption
143state so the remote side can resynchronize.
144.El
145.Sh SHUTDOWN
146This node shuts down upon receipt of a
147.Dv NGM_SHUTDOWN
148control message, or when both hooks have been disconnected.
149.Sh COMPILATION
150The kernel options
151.Dv NETGRAPH_MPPC_COMPRESSION
152and
153.Dv NETGRAPH_MPPC_ENCRYPTION
154are supplied to selectively compile in either or both capabilities.
155At least one of these must be defined, or else this node type is useless.
156.Pp
157The MPPC protocol requires proprietary compression code available
158from Hi/Fn (formerly STAC).
159These files must be obtained elsewhere and added to the kernel
160sources before this node type will compile with the
161.Dv NETGRAPH_MPPC_COMPRESSION
162option.
163.Sh SEE ALSO
164.Xr netgraph 4 ,
165.Xr ng_ppp 4 ,
166.Xr ngctl 8
167.Rs
168.%A G. Pall
169.%T "Microsoft Point-To-Point Compression (MPPC) Protocol"
170.%O RFC 2118
171.Re
172.Rs
173.%A G. S. Pall
174.%A G. Zorn
175.%T "Microsoft Point-To-Point Encryption (MPPE) Protocol"
176.%O draft-ietf-pppext-mppe-04.txt
177.Re
178.Rs
179.%A K. Hamzeh
180.%A G. Pall
181.%A W. Verthein
182.%A J. Taarud
183.%A W. Little
184.%A G. Zorn
185.%T "Point-to-Point Tunneling Protocol (PPTP)"
186.%O RFC 2637
187.Re
188.Sh AUTHORS
189.An Archie Cobbs Aq archie@FreeBSD.org
190.Sh BUGS
191In PPP, encryption should be handled by the Encryption Control Protocol (ECP)
192rather than CCP.
193However, Microsoft combined both compression and encryption into their
194``compression'' algorithm, which is confusing.
195