share/man/man4/ng_mppc.4

   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: src/share/man/man4/ng_mppc.4,v 1.11.2.3 2002/03/20 18:16:36 archie Exp $
  37 .\" $DragonFly: src/share/man/man4/ng_mppc.4,v 1.4 2006/05/26 19:39:39 swildner Exp $
  38 .\"
  39 .Dd December 8, 1999
  40 .Dt NG_MPPC 4
  41 .Os
  42 .Sh NAME
  43 .Nm ng_mppc
  44 .Nd Microsoft MPPC/MPPE compression and encryption netgraph node type
  45 .Sh SYNOPSIS
  46 .In netgraph/mppc/ng_mppc.h
  47 .Sh DESCRIPTION
  48 The
  49 .Nm mppc
  50 node type implements the Microsoft Point-to-Point Compression (MPPC)
  51 and Microsoft Point-to-Point Encryption (MPPE) sub-protocols of
  52 the PPP protocol.
  53 These protocols are often used in conjunction with the Point-to-Point
  54 Tunneling Protocol (PPTP).
  55 .Pp
  56 The node has two hooks,
  57 .Dv "comp"
  58 for compression and
  59 .Dv "decomp"
  60 for decompression.
  61 Typically one or both of these hooks would be connected to the
  62 .Xr ng_ppp 4
  63 node type hook of the same name.
  64 Each direction of traffic flow is independent of the other.
  65 .Sh HOOKS
  66 This node type supports the following hooks:
  67 .Pp
  68 .Bl -tag -compact -width vjc_vjuncomp
  69 .It Dv comp
  70 Connection to
  71 .Xr ng_ppp 4
  72 .Dv "comp"
  73 hook.
  74 Incoming frames are compressed and/or encrypted, and sent
  75 back out the same hook.
  76 .It Dv decomp
  77 Connection to
  78 .Xr ng_ppp 4
  79 .Dv "decomp"
  80 hook.
  81 Incoming frames are decompressed and/or decrypted, and sent
  82 back out the same hook.
  83 .El
  84 .Sh CONTROL MESSAGES
  85 This node type supports the generic control messages, plus the following:
  86 .Bl -tag -width foo
  87 .It Dv NGM_MPPC_CONFIG_COMP
  88 This command resets and configures the node for a session in the
  89 outgoing traffic direction (i.e., for compression and/or encryption).
  90 This command takes a
  91 .Dv "struct ng_mppc_config"
  92 as 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 */
 107 struct 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
 114 The
 115 .Dv enabled
 116 field enables traffic flow through the node.
 117 The
 118 .Dv bits
 119 field contains the bits as negotiated by the Compression Control Protocol
 120 (CCP) in PPP.
 121 The
 122 .Dv startkey
 123 is only necessary if MPPE was negotiated, and must be equal to the
 124 session start key as defined for MPPE.
 125 This key is based on the MS-CHAP credentials used at link authentication time.
 126 .It Dv NGM_MPPC_CONFIG_DECOMP
 127 This command resets and configures the node for a session in the
 128 incoming traffic direction (i.e., for decompression and/or decryption).
 129 This command takes a
 130 .Dv "struct ng_mppc_config"
 131 as an argument.
 132 .It Dv NGM_MPPC_RESETREQ
 133 This message contains no arguments, and is bi-directional.
 134 If an error is detected during decompression, this message is sent by the
 135 node to the originator of the
 136 .Dv NGM_MPPC_CONFIG_DECOMP
 137 message that initiated the session.
 138 The receiver should respond by sending a PPP CCP Reset-Request to the peer.
 139 .Pp
 140 This message may also be received by this node type when a CCP Reset-Request
 141 is received by the local PPP entity.
 142 The node will respond by flushing its outgoing compression and encryption
 143 state so the remote side can resynchronize.
 144 .El
 145 .Sh SHUTDOWN
 146 This node shuts down upon receipt of a
 147 .Dv NGM_SHUTDOWN
 148 control message, or when both hooks have been disconnected.
 149 .Sh COMPILATION
 150 The kernel options
 151 .Dv NETGRAPH_MPPC_COMPRESSION
 152 and
 153 .Dv NETGRAPH_MPPC_ENCRYPTION
 154 are supplied to selectively compile in either or both capabilities.
 155 At least one of these must be defined, or else this node type is useless.
 156 .Pp
 157 The MPPC protocol requires proprietary compression code available
 158 from Hi/Fn (formerly STAC).
 159 These files must be obtained elsewhere and added to the kernel
 160 sources before this node type will compile with the
 161 .Dv NETGRAPH_MPPC_COMPRESSION
 162 option.
 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
 191 In PPP, encryption should be handled by the Encryption Control Protocol (ECP)
 192 rather than CCP.
 193 However, Microsoft combined both compression and encryption into their
 194 ``compression'' algorithm, which is confusing.