From alex@kapran.bitmcnit.bryansk.su  Thu Jul 12 08:06:23 2001
Return-Path: <alex@kapran.bitmcnit.bryansk.su>
Received: from rbn-gw.bgtu.debryansk.ru (rbn-gw.bgtu.debryansk.ru [62.76.89.2])
	by hub.freebsd.org (Postfix) with ESMTP id A846C37B401
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 12 Jul 2001 08:05:57 -0700 (PDT)
	(envelope-from alex@kapran.bitmcnit.bryansk.su)
Received: from server.bitmcnit.bryansk.su (root@bitmcnit.bryansk.su [192.168.121.2])
	by rbn-gw.bgtu.debryansk.ru (8.11.2/8.11.2) with ESMTP id f6CF1qD25457;
	Thu, 12 Jul 2001 19:01:52 +0400
Received: (from uucp@localhost)
	by server.bitmcnit.bryansk.su (8.9.3/8.9.3) with UUCP id SAA15873;
	Thu, 12 Jul 2001 18:58:30 +0400
Received: (from alex@localhost)
	by kapran.bitmcnit.bryansk.su (8.11.4/8.11.4) id f6CExeq01850;
	Thu, 12 Jul 2001 18:59:40 +0400 (MSD)
	(envelope-from alex)
Message-Id: <200107121459.f6CExeq01850@kapran.bitmcnit.bryansk.su>
Date: Thu, 12 Jul 2001 18:59:40 +0400 (MSD)
From: Alex Kapranoff <kapr@acm.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc: honig@sprynet.com
Subject: DocBook conversion of doc/articles/ipsec-must
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         28916
>Category:       docs
>Synopsis:       DocBook conversion of doc/articles/ipsec-must
>Confidential:   no
>Severity:       non-critical
>Priority:       high
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 12 08:10:01 PDT 2001
>Closed-Date:    Sun Jul 29 02:47:45 PDT 2001
>Last-Modified:  Sun Jul 29 02:48:00 PDT 2001
>Originator:     Alex Kapranoff
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
Inner Mongolia
>Environment:
System: FreeBSD kapran.bitmcnit.bryansk.su 5.0-CURRENT FreeBSD 5.0-CURRENT #5: Sun Jun 24 22:56:52 MSD 2001 root@kapran.bitmcnit.bryansk.su:/usr/src/sys/compile/KAPRAN i386


	
>Description:
	I added some content (mostly removing obsolete info and
	providing additional links) along with converting the text to
	DocBook. A review would be appreciated.
>How-To-Repeat:
	
>Fix:

# This is a shell archive.  Save it in a file, remove anything before
# this line, and then unpack it by entering "sh file".  Note, it may
# create directories; files and directories will be owned by you and
# have default permissions.
#
# This archive contains:
#
#	Makefile
#	article.sgml
#
echo x - Makefile
sed 's/^X//' >Makefile << 'END-of-Makefile'
X# $FreeBSD: doc/en_US.ISO8859-1/articles/ipsec-must/Makefile,v 1.1 2000/06/26 09:10:24 nik Exp $
X
XDOC?= article
X
XFORMATS?= html
X
XINSTALL_COMPRESSED?=gz
XINSTALL_ONLY_COMPRESSED?=
X
XSRCS= article.sgml
X
XDOC_PREFIX?= ${.CURDIR}/../../..
X
X.include "${DOC_PREFIX}/share/mk/doc.project.mk"
END-of-Makefile
echo x - article.sgml
sed 's/^X//' >article.sgml << 'END-of-article.sgml'
X<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
X<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
X%man;
X]>
X
X<!-- $FreeBSD$ -->
X
X<article>
X  <articleinfo>
X    <title>Independent Verification of IPSec Functionality in FreeBSD</title>
X
X    <author>
X      <firstname>David</firstname>
X      <surname>Honig</surname>
X
X      <affiliation>
X        <address><email>honig@sprynet.com</email></address>
X      </affiliation>
X    </author>
X
X    <pubdate>3 May 1999</pubdate>
X
X    <abstract>
X      <para>You installed IPsec and it seems to be working. How do you
X        know?  I describe a method for experimentally verifying that IPsec is
X        working.</para>
X    </abstract>
X  </articleinfo>
X
X  <sect1>
X    <title>The Problem</title>
X
X    <para>First, let's assume you have <link linkend="ipsec-install">
X      installed <emphasis>IPsec</emphasis></link>.  How do you know
X      it's <link linkend="caveat">working</link>?  Sure, your
X      connection won't work if its misconfigured, and it will work
X      when you finally get it right.  &man.netstat.1; will list it.
X      But can you independently confirm it?</para>
X  </sect1>
X
X  <sect1>
X    <title>The Solution</title>
X
X    <para>First, some crypto-relevant info theory:</para>
X
X    <orderedlist>
X      <listitem>
X	<para>encrypted data is uniformly distributed, i.e., has maximal
X	  entropy per symbol;</para>
X      </listitem>
X
X      <listitem>
X	<para>raw, uncompressed data is typically redundant, i.e., has
X	  sub-maximal entropy.</para>
X      </listitem>
X    </orderedlist>
X
X    <para>Suppose you could measure the entropy of the data to- and
X      from- your network interface.  Then you could see the difference
X      between unencrypted data and encrypted data.  This would be true
X      even if some of the data in <quote>encrypted mode</quote> was
X      not encrypted---as the outermost IP header must be, if the
X      packet is to be routable.</para>
X
X    <sect2 id="MUST">
X      <title>MUST</title>
X
X      <para>Ueli Maurer's <quote>Universal Statistical Test for Random
X	Bit Generators</quote>(<ulink
X	url="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">
X	<acronym>MUST</acronym></ulink>) quickly measures the entropy
X	of a sample.  It uses a compression-like algorithm.  <link
X	linkend="code">The code is given below</link> for a variant
X	which measures successive (~quarter megabyte) chunks of a
X	file.</para>
X    </sect2>
X
X    <sect2 id="tcpdump">
X      <title>Tcpdump</title>
X
X      <para>We also need a way to capture the raw network data.  A
X	program called &man.tcpdump.1; lets you do this, if you have
X	enabled the <emphasis>Berkeley Packet Filter</emphasis>
X	interface in your <link linkend="kernel">kernel's config
X	file</link>.</para>
X
X      <para>The command
X
X      <screen>
X      <userinput><command>tcpdump</command> -c 4000 -s 10000 -w <replaceable>dumpfile.bin</replaceable></userinput>
X      </screen>
X
X      will capture 4000 raw packets to
X      <replaceable>dumpfile.bin</replaceable>.  Up to 10,000 bytes per
X      packet will be captured in this example.</para>
X    </sect2>
X
X  <sect1>
X    <title>The Experiment</title>
X
X    <para>Here's the experiment.</para>
X
X    <procedure>
X      <step>
X	<para>Open a window to an IPsec host and another window to an
X	  insecure host.</para>
X      </step>
X
X      <step>
X	<para>Now start <link linkend="tcpdump">capturing
X	  packets</link>.</para>
X      </step>
X
X      <step>
X	<para>In the <quote>secure</quote> window, run the UNIX
X	  command &man.yes.1;, which will stream the <quote>y</quote>
X	  character.  After a while, stop this.  Switch to the
X	  insecure window, and repeat.  After a while, stop.</para>
X      </step>
X
X      <step>
X	<para>Now run <link linkend="code">MUST</link> on the
X	  captured packets.  You should see something like the
X	  following.  The important thing to note is that the secure
X	  connection has 93% (6.7) of the expected value (7.18), and
X	  the <quote>normal</quote> connection has 29% (2.1) of the
X	  expected value.</para>
X
X    <screen>
X&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w <replaceable>ipsecdemo.bin</replaceable></userinput>
X&prompt.user; <userinput>uliscan <replaceable>ipsecdemo.bin</replaceable></userinput>
X
XUliscan 21 Dec 98
XL=8 256 258560
XMeasuring file ipsecdemo.bin
XInit done
XExpected value for L=8 is 7.1836656
X6.9396 --------------------------------------------------------
X6.6177 -----------------------------------------------------
X6.4100 ---------------------------------------------------
X2.1101 -----------------
X2.0838 -----------------
X2.0983 -----------------
X</screen>
X      </step>
X    </procedure>
X  </sect1>
X
X    <sect1 id="caveat">
X      <title>Caveat</title>
X
X    <para>This experiment shows that IPsec <emphasis>does</emphasis>
X      seem to be distributing the payload data
X      <emphasis>uniformly</emphasis>, as encryption should.  However,
X      the experiment described here <emphasis>can not</emphasis>
X      detect many possible flaws in a system (none of which do I have
X      any evidence for).  These include poor key generation or
X      exchange, data or keys being visible to others, use of weak
X      algorithms, kernel subversion, etc.  Study the source; know the
X      code.</para>
X  </sect1>
X
X  <sect1 id="IPsec">
X    <title>IPsec---Definition</title>
X
X    <para>Internet Protocol security extensions to IPv4; required for
X      IPv6.  A protocol for negotiating encryption and authentication
X      at the IP (host-to-host) level.  SSL secures only one application
X      socket; <application>SSH</application> secures only a login;
X      <application>PGP</application> secures only a specified file or
X      message.  IPsec encrypts everything between two hosts.</para>
X  </sect1>
X
X  <sect1 id="ipsec-install">
X    <title>Installing IPsec</title>
X
X    <para>Most of the modern versions of FreeBSD have IPsec support
X      in their base source.  So you'll probably will need to include
X      <option>IPSEC</option> option in your kernel config and, after
X      kernel rebuild and reinstall, configure IPsec connections using
X      &man.setkey.8; command.</para>
X
X    <para>A comprehensive guide on running IPsec on FreeBSD is
X      provided in <ulink
X      url="http://www.freebsd.org/handbook/ipsec.html">FreeBSD
X      Handbook</ulink>.</para>
X  </sect1>
X
X  <sect1 id="kernel">
X    <title>usr/src/sys/i386/conf/KERNELNAME</title>
X
X    <para>This needs to be present in the kernel config file in order
X      to be able to capture network data with &man.tcpdump.1;.  Be sure
X      to run &man.config.8; after adding this, and rebuild and
X      reinstall.</para>
X
X<programlisting>
Xdevice	bpf
X</programlisting>
X  </sect1>
X
X    <sect1 id="code">
X      <title>Maurer's Universal Statistical Test (for block size=8
X        bits)</title>
X
X        <para>You can find the same code at <ulink
X          url="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
X          this link</ulink>.</para>
X
X<programlisting>
X/*
X  ULISCAN.c   ---blocksize of 8
X
X  1 Oct 98
X  1 Dec 98
X  21 Dec 98       uliscan.c derived from ueli8.c
X
X  This version has // comments removed for Sun cc
X
X  This implements Ueli M Maurer's "Universal Statistical Test for Random
X  Bit Generators" using L=8
X
X  Accepts a filename on the command line; writes its results, with other
X  info, to stdout.
X
X  Handles input file exhaustion gracefully.
X
X  Ref: J. Cryptology v 5 no 2, 1992 pp 89-105
X  also on the web somewhere, which is where I found it.
X
X  -David Honig
X  honig@sprynet.com
X
X  Usage:
X  ULISCAN filename
X  outputs to stdout
X*/
X
X#define L 8
X#define V (1&lt;&lt;L)
X#define Q (10*V)
X#define K (100   *Q)
X#define MAXSAMP (Q + K)
X
X#include &lt;stdio.h&gt;
X#include &lt;math.h&gt;
X
Xint main(argc, argv)
Xint argc;
Xchar **argv;
X{
X  FILE *fptr;
X  int i,j;
X  int b, c;
X  int table[V];
X  double sum = 0.0;
X  int iproduct = 1;
X  int run;
X
X  extern double   log(/* double x */);
X
X  printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP);
X
X  if (argc &lt; 2) {
X    printf("Usage: Uliscan filename\n");
X    exit(-1);
X  } else {
X    printf("Measuring file %s\n", argv[1]);
X  }
X
X  fptr = fopen(argv[1],"rb");
X
X  if (fptr == NULL) {
X    printf("Can't find %s\n", argv[1]);
X    exit(-1);
X  }
X
X  for (i = 0; i &lt; V; i++) {
X    table[i] = 0;
X  }
X
X  for (i = 0; i &lt; Q; i++) {
X    b = fgetc(fptr);
X    table[b] = i;
X  }
X
X  printf("Init done\n");
X
X  printf("Expected value for L=8 is 7.1836656\n");
X
X  run = 1;
X
X  while (run) {
X    sum = 0.0;
X    iproduct = 1;
X
X    if (run)
X      for (i = Q; run && i &lt; Q + K; i++) {
X        j = i;
X        b = fgetc(fptr);
X
X        if (b &lt; 0)
X          run = 0;
X
X        if (run) {
X          if (table[b] &gt; j)
X            j += K;
X
X          sum += log((double)(j-table[b]));
X
X          table[b] = i;
X        }
X      }
X
X    if (!run)
X      printf("Premature end of file; read %d blocks.\n", i - Q);
X
X    sum = (sum/((double)(i - Q))) /  log(2.0);
X    printf("%4.4f ", sum);
X
X    for (i = 0; i &lt; (int)(sum*8.0 + 0.50); i++)
X      printf("-");
X
X    printf("\n");
X
X    /* refill initial table */
X    if (0) {
X      for (i = 0; i &lt; Q; i++) {
X        b = fgetc(fptr);
X        if (b &lt; 0) {
X          run = 0;
X        } else {
X          table[b] = i;
X        }
X      }
X    }
X  }
X}
X</programlisting>
X  </sect1>
X</article>
END-of-article.sgml
exit

>Release-Note:
>Audit-Trail:

From: Dima Dorfman <dima@unixfreak.org>
To: Alex Kapranoff <kapr@acm.org>
Cc: FreeBSD-gnats-submit@freebsd.org, honig@sprynet.com
Subject: Re: docs/28916: DocBook conversion of doc/articles/ipsec-must 
Date: Fri, 13 Jul 2001 07:51:40 -0700

 Alex Kapranoff <kapr@acm.org> writes:
 > >Description:
 > 	I added some content (mostly removing obsolete info and
 > 	providing additional links) along with converting the text to
 > 	DocBook. A review would be appreciated.
 
 Could you please
 
 	(1) separate the content changes from the DocBook conversion, and
 	(2) send this in the form of a diff against the old version.
 
 (1) because content changes must be separate from markup changes (if
 not for `cvs diff` convenience, for translators), and (2) because
 sharballs for files already in the repository aren't very convenient
 to work with.

From: Alex Kapranoff <kapr@acm.org>
To: Dima Dorfman <dima@unixfreak.org>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG, honig@sprynet.com
Subject: Re: docs/28916: DocBook conversion of doc/articles/ipsec-must
Date: Mon, 16 Jul 2001 08:39:22 +0400

 * Dima Dorfman <dima@unixfreak.org> [July 13 2001, 18:51]:
 > Alex Kapranoff <kapr@acm.org> writes:
 > > >Description:
 > > 	I added some content (mostly removing obsolete info and
 > > 	providing additional links) along with converting the text to
 > > 	DocBook. A review would be appreciated.
 > 
 > Could you please
 > 
 > 	(1) separate the content changes from the DocBook conversion, and
 > 	(2) send this in the form of a diff against the old version.
 > 
 > (1) because content changes must be separate from markup changes (if
 > not for `cvs diff` convenience, for translators), and (2) because
 > sharballs for files already in the repository aren't very convenient
 > to work with.
 
   Yes, my fault. Thanks for the reminder. Below is the content diff for
 translators (there's a ja_JA.eucJP translation). And markup diff in
 this case is neither human-comprehendable nor space-saving. The main reason
 for me not to submit changes in the diff form was that it won't help
 anybody. You can easily generate it with `cvs diff', however, and see
 that 95% of lines are changed and therefore included in the diff (twice).
 
   And why do you say that sharballs are less convenient to work with?
 Seems that it's true only if the diff is readable.
 
 --- /usr/doc/en_US.ISO8859-1/articles/ipsec-must/article.sgml	Wed Jun 13 18:16:55 2001
 +++ article.html	Mon Jul 16 08:22:26 2001
 @@ -2,12 +2,12 @@
  
  <html>
    <head>
 -    <title>Independent Verification of IPSec Functionality in FreeBSD</title>
 +    <title>Independent Verification of IPsec Functionality in FreeBSD</title>
    </head>
    
    <body text="#000000" bgcolor="#FFFFFF">
      
 -    <h1>Independent Verification of IPsec Functionality Under FreeBSD 3.0</h1>
 +    <h1>Independent Verification of IPsec Functionality in FreeBSD</h1>
      
      <p align="center"><i>You installed IPsec and it seems to be working.&nbsp;
  	How do you know?  I describe a method for experimentally verifying
 @@ -27,12 +27,12 @@
      
      <ol>
        <li>
 -	<p>Encrypted data is uniformly distributed, ie, has maximal entropy
 -	  per symbol.</p>
 +	<p>encrypted data is uniformly distributed, i.e., has maximal entropy
 +	  per symbol;</p>
        </li>
        
        <li>
 -	<p>Raw, uncompressed data is typically redundant, i.e., has
 +	<p>raw, uncompressed data is typically redundant, i.e., has
  	  sub-maximal entropy.</p>
        </li>
      </ol>
 @@ -40,16 +40,17 @@
      <p>Suppose you could measure the entropy of the data to- and from- your
        network interface. Then you could see the difference between unencrypted
        data and encrypted data. This would be true even if some of the data
 -      in "encrypted mode" was not encrypted ---as the outermost IP header must
 +      in "encrypted mode" was not encrypted---as the outermost IP header must
        be, if the packet is to be routable.</p>
      
      <h4><a name="MUST"></a>MUST</h4>
      
      <p>Ueli Maurer's "Universal Statistical Test for Random Bit Generators"
 -      ("MUST") quickly measures the entropy of a sample. It uses a
 -      compression-like algorithm. <a href="#Maurer's Universal Statistical
 -	Test">The code is given below for a variant which measures successive
 -	(~quarter megabyte) chunks of a file</a>.</p>
 +	(<a href="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">MUST</a>)
 +	quickly measures the entropy of a sample. It uses a
 +	compression-like algorithm. <a href="#Maurer's Universal Statistical
 +	Test">The code is given below</a> for a variant which measures successive
 +	(~quarter megabyte) chunks of a file.</p>
      
      <h4><a NAME="Tcpdump"></a>Tcpdump</h4>
      
 @@ -103,15 +104,15 @@
      
      <p>This experiment shows that IPsec <i>does</i> seem to be distributing the
        payload data <i>uniformly</i>, as encryption should. However, the
 -      experiment described here <i>can not </i>detect many possible flaws in a
 +      experiment described here <i>can not</i> detect many possible flaws in a
        system (none of which do I have any evidence for). These include poor
        key generation or exchange, data or keys being visible to others, use of
        weak algorithms, kernel subversion, etc. Study the source; know the
        code.</p>
        
 -    <h2><a NAME="IPsec"></a>IPsec -Definition</h2>
 +    <h2><a NAME="IPsec"></a>IPsec---Definition</h2>
  
 -    <p>Internet Protocol security extensions to IP v 4; required for IP v6.  A
 +    <p>Internet Protocol security extensions to IPv4; required for IPv6.  A
        protocol for negotiating encryption and authentication at the IP
        (host-to-host) level. SSL secures only one application socket; SSH
        secures only a login; PGP secures only a specified file or
 @@ -119,49 +120,34 @@
      
      <h2><a NAME="Installing IPsec"></a>Installing IPsec</h2>
  
 -    <p>Starting from the BSD 3.0 stable release,</p>
 +    <p>Most of the modern versions of FreeBSD have IPsec support
 +	in their base source.  So you'll probably will need to
 +	include <i>IPSEC</i> option in your kernel config
 +	and, after kernel rebuild and reinstall, configure IPsec
 +	connections using <i>setkey</i> command.</p>
      
 -    <ol>
 -      <li>
 -	<p>install IPsec v0.04, rebuild, reinstall</p>
 -      </li>
  
 -      <li>
 -	<p>run the administration tools (e.g, <i>ipsecadm</i>) and distribute
 -	  keys (or use <i>Photuris</i> for key exchange)</p>
 -      </li>
 -
 -      <li>
 -	<p>set the routes (<i>rt</i>) up appropriately</p>
 -      </li>
 -    </ol>
 -    
 -    <p>You may want to make an "ipsec_setup" script containing the
 -      <i>ipsecadm</i> and <i>rt</i> commands which establish your IPsec
 -      tunnel. You can run this script automatically at boottime from your
 -      <i>/etc/rc.local</i> The ipsec_setup script will have to contain at
 -      least two <i>ipsecadm</i> commands and one <i>rt</i> command to be
 -      useful.</p>
 +    <p>A comprehensive guide on running IPsec on FreeBSD is
 +      provided in <a
 +      href="http://www.freebsd.org/handbook/ipsec.html">FreeBSD
 +      Handbook</a>.
  
      <h2><a NAME="KERNELNAME"></a>usr/src/sys/i386/conf/KERNELNAME</h2>
      
 -    <p>This needs to be present in the kernel config file in order to run
 -      IPsec. After adding it, run <i>config</i>, etc. and rebuild and
 +    <p>This needs to be present in the kernel config file in order to be able
 +      to capture network data with <i>tcpdump</i>.
 +      Be sure to run <i>config</i> after adding this, and rebuild and
        reinstall.</p>
  
 -    <pre># The `bpfilter' pseudo-device enables the Berkeley Packet Filter. Be
 -# aware of the legal and administrative consequences of enabling this
 -# option. Heh heh. The number of devices determines the maximum number of
 -# simultaneous BPF clients programs runnable.
 -pseudo-device bpfilter 2 #Berkeley packet filter
 -
 -# IPSEC
 -options IPSEC
 -options "MD5"
 -pseudo-device enc 1</pre>
 +    <pre>device	bpf
 +</pre>
  
      <h2><a name="Maurer's Universal Statistical Test"></a>Maurer's Universal Statistical Test (for block
        size=8 bits)</h2>
 +
 +        <p>You can find the same code at <a
 +          href="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
 +          this link</a>.</p>
  
      <pre><![ CDATA [/*
    ULISCAN.c   ---blocksize of 8
 
 -- 
 Alex Kapranoff,                              Voice: +7(0832)791845
 We've lived 196 days in the brand new millenium...

From: Alex Kapranoff <kapr@acm.org>
To: Dima Dorfman <dima@unixfreak.org>
Cc: freebsd-doc@FreeBSD.ORG, freebsd-gnats-submit@FreeBSD.ORG
Subject: Re: docs/28916: DocBook conversion of doc/articles/ipsec-must
Date: Sat, 21 Jul 2001 10:42:33 +0400

 * Dima Dorfman <dima@unixfreak.org> [July 19 2001, 15:57]:
 > Alex Kapranoff <kapr@acm.org> writes:
 > >    And why do you say that sharballs are less convenient to work with?
 > >  Seems that it's true only if the diff is readable.
 > 
 > Well, for one it *would* be readable, at least for the Makefile.  Two,
 
   Okay, now try to read the diff below. ;)
 
 > it'd be nice to know that you wouldn't be overwriting other people's
 > changes (e.g., chern made a spelling fix, and if I just unshar'd your
 > files it'd be overwritten).  And three, with a diff I can save the
 > e-mail to a file then pass it through patch; I can't just pass a shar
 > archive through sh because of the cruft above the archive (okay, okay,
 > I'm lazy :-) ).
 
   Points taken.
 
 > >  --- /usr/doc/en_US.ISO8859-1/articles/ipsec-must/article.sgml	Wed Jun13 18:16:55 2001
 > >  +++ article.html	Mon Jul 16 08:22:26 2001
 > 
 > I've applied this.  Now that that's done, could you send me a diff
 > that converts this mess to DocBook?  Thanks!
 
   Sorry for confusion. With this patch applied the PR could be closed.
 This is all obtained from FreeBSD Russian Documentation Project.
 
 diff -u /usr/doc/en_US.ISO8859-1/articles/ipsec-must/Makefile ./Makefile
 --- /usr/doc/en_US.ISO8859-1/articles/ipsec-must/Makefile	Mon Jun 26 13:10:24 2000
 +++ ./Makefile	Thu Jul 12 18:55:10 2001
 @@ -2,8 +2,6 @@
  
  DOC?= article
  
 -DOCFORMAT= html
 -
  FORMATS?= html
  
  INSTALL_COMPRESSED?=gz
 diff -u /usr/doc/en_US.ISO8859-1/articles/ipsec-must/article.sgml ./article.sgml
 --- /usr/doc/en_US.ISO8859-1/articles/ipsec-must/article.sgml	Fri Jul 20 18:55:28 2001
 +++ ./article.sgml	Sat Jul 21 10:39:56 2001
 @@ -1,92 +1,138 @@
 -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 +<!--
 +    The FreeBSD Documentation Project
  
 -<html>
 -  <head>
 -    <title>Independent Verification of IPsec Functionality in FreeBSD</title>
 -  </head>
 -  
 -  <body text="#000000" bgcolor="#FFFFFF">
 -    
 -    <h1>Independent Verification of IPsec Functionality in FreeBSD</h1>
 -    
 -    <p align="center"><i>You installed IPsec and it seems to be working.&nbsp;
 -	How do you know?  I describe a method for experimentally verifying
 -	that IPsec is working</i></p>
 -    
 -    <h2>The Problem</h2>
 -    
 -    <p>First, let's assume you have <a href="#Installing IPsec">installed
 -	<i>IPsec</i></a>. How do you know its <a href="#Caveat">working</a>?
 -      Sure, your connection won't work if its misconfigured, and it will work
 -      when you finally get it right. <i>Netstat</i> will list it. But can you
 -      independently confirm it?</p>
 -    
 -    <h2>The Solution</h2>
 -    
 -    <p>First, some crypto-relevent info theory:</p>
 -    
 -    <ol>
 -      <li>
 -	<p>encrypted data is uniformly distributed, i.e., has maximal entropy
 -	  per symbol;</p>
 -      </li>
 -      
 -      <li>
 -	<p>raw, uncompressed data is typically redundant, i.e., has
 -	  sub-maximal entropy.</p>
 -      </li>
 -    </ol>
 -    
 -    <p>Suppose you could measure the entropy of the data to- and from- your
 -      network interface. Then you could see the difference between unencrypted
 -      data and encrypted data. This would be true even if some of the data
 -      in "encrypted mode" was not encrypted---as the outermost IP header must
 -      be, if the packet is to be routable.</p>
 -    
 -    <h4><a name="MUST"></a>MUST</h4>
 -    
 -    <p>Ueli Maurer's "Universal Statistical Test for Random Bit Generators"
 -	(<a href="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">MUST</a>)
 -	quickly measures the entropy of a sample. It uses a
 -	compression-like algorithm. <a href="#Maurer's Universal Statistical
 -	Test">The code is given below</a> for a variant which measures successive
 -	(~quarter megabyte) chunks of a file.</p>
 -    
 -    <h4><a NAME="Tcpdump"></a>Tcpdump</h4>
 -    
 -    <p>We also need a way to capture the raw network data. A program called
 -      "<i>tcpdump</i>" lets you do this, if you have enabled the <i>Berkeley
 -	Packet Filter</i> interface in your <a
 -	href="#KERNELNAME">kernel's config file</a>.</p>
 -    
 -    <p>The command</p>
 -
 -    <blockquote><b>tcpdump</b> <b>-c</b> 4000 <b>-s</b> 10000 <b>-w</b>
 -      <i>dumpfile.bin</i></blockquote>
 -    
 -    <p>will capture 4000 raw packets to <i>dumpfile.bin</i>. Up to 10,000
 -      bytes per packet will be captured in this example.</p>
 -    
 -    <h2>The Experiment</h2>
 -    
 -    <p>Here's the experiment. Open a window to an IPsec host and another
 -      window to an insecure host.</p>
 -    
 -    <p>Now start <a href="#Tcpdump">capturing packets</a>.</p>
 -    
 -    <p>In the "secure" window, run the unix command "yes", which will stream
 -      the "y" character.  After a while, stop this. Switch to the insecure
 -      window, and repeat.  After a while, stop.</p>
 -    
 -    <p>Now run <a href="#Maurer's Universal Statistical Test">MUST</a> on the
 -      captured packets. You should see something like the following.
 -      The important thing to note is that the secure connection has 93% (6.7)
 -      of the expected value (7.18), and the "normal" connection has 29% (2.1)
 -      of the expected value.</p>
 -
 -    
 -    <pre>% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin
 -% uliscan ipsecdemo.bin
 +    $FreeBSD$
 +-->
 +
 +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 +%man;
 +]>
 +
 +<article>
 +  <articleinfo>
 +    <title>Independent Verification of IPSec Functionality in FreeBSD</title>
 +
 +    <author>
 +      <firstname>David</firstname>
 +      <surname>Honig</surname>
 +
 +      <affiliation>
 +        <address><email>honig@sprynet.com</email></address>
 +      </affiliation>
 +    </author>
 +
 +    <pubdate>3 May 1999</pubdate>
 +
 +    <abstract>
 +      <para>You installed IPsec and it seems to be working. How do you
 +        know?  I describe a method for experimentally verifying that IPsec is
 +        working.</para>
 +    </abstract>
 +  </articleinfo>
 +
 +  <sect1>
 +    <title>The Problem</title>
 +
 +    <para>First, let's assume you have <link linkend="ipsec-install">
 +      installed <emphasis>IPsec</emphasis></link>.  How do you know
 +      it's <link linkend="caveat">working</link>?  Sure, your
 +      connection won't work if its misconfigured, and it will work
 +      when you finally get it right.  &man.netstat.1; will list it.
 +      But can you independently confirm it?</para>
 +  </sect1>
 +
 +  <sect1>
 +    <title>The Solution</title>
 +
 +    <para>First, some crypto-relevant info theory:</para>
 +
 +    <orderedlist>
 +      <listitem>
 +	<para>encrypted data is uniformly distributed, i.e., has maximal
 +	  entropy per symbol;</para>
 +      </listitem>
 +
 +      <listitem>
 +	<para>raw, uncompressed data is typically redundant, i.e., has
 +	  sub-maximal entropy.</para>
 +      </listitem>
 +    </orderedlist>
 +
 +    <para>Suppose you could measure the entropy of the data to- and
 +      from- your network interface.  Then you could see the difference
 +      between unencrypted data and encrypted data.  This would be true
 +      even if some of the data in <quote>encrypted mode</quote> was
 +      not encrypted---as the outermost IP header must be, if the
 +      packet is to be routable.</para>
 +
 +    <sect2 id="MUST">
 +      <title>MUST</title>
 +
 +      <para>Ueli Maurer's <quote>Universal Statistical Test for Random
 +	Bit Generators</quote>(<ulink
 +	url="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">
 +	<acronym>MUST</acronym></ulink>) quickly measures the entropy
 +	of a sample.  It uses a compression-like algorithm.  <link
 +	linkend="code">The code is given below</link> for a variant
 +	which measures successive (~quarter megabyte) chunks of a
 +	file.</para>
 +    </sect2>
 +
 +    <sect2 id="tcpdump">
 +      <title>Tcpdump</title>
 +
 +      <para>We also need a way to capture the raw network data.  A
 +	program called &man.tcpdump.1; lets you do this, if you have
 +	enabled the <emphasis>Berkeley Packet Filter</emphasis>
 +	interface in your <link linkend="kernel">kernel's config
 +	file</link>.</para>
 +
 +      <para>The command
 +
 +      <screen>
 +      <userinput><command>tcpdump</command> -c 4000 -s 10000 -w <replaceable>dumpfile.bin</replaceable></userinput>
 +      </screen>
 +
 +      will capture 4000 raw packets to
 +      <replaceable>dumpfile.bin</replaceable>.  Up to 10,000 bytes per
 +      packet will be captured in this example.</para>
 +    </sect2>
 +
 +  <sect1>
 +    <title>The Experiment</title>
 +
 +    <para>Here's the experiment.</para>
 +
 +    <procedure>
 +      <step>
 +	<para>Open a window to an IPsec host and another window to an
 +	  insecure host.</para>
 +      </step>
 +
 +      <step>
 +	<para>Now start <link linkend="tcpdump">capturing
 +	  packets</link>.</para>
 +      </step>
 +
 +      <step>
 +	<para>In the <quote>secure</quote> window, run the UNIX
 +	  command &man.yes.1;, which will stream the <quote>y</quote>
 +	  character.  After a while, stop this.  Switch to the
 +	  insecure window, and repeat.  After a while, stop.</para>
 +      </step>
 +
 +      <step>
 +	<para>Now run <link linkend="code">MUST</link> on the
 +	  captured packets.  You should see something like the
 +	  following.  The important thing to note is that the secure
 +	  connection has 93% (6.7) of the expected value (7.18), and
 +	  the <quote>normal</quote> connection has 29% (2.1) of the
 +	  expected value.</para>
 +
 +    <screen>
 +&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w <replaceable>ipsecdemo.bin</replaceable></userinput>
 +&prompt.user; <userinput>uliscan <replaceable>ipsecdemo.bin</replaceable></userinput>
  
  Uliscan 21 Dec 98
  L=8 256 258560
 @@ -98,58 +144,75 @@
  6.4100 ---------------------------------------------------
  2.1101 -----------------
  2.0838 -----------------
 -2.0983 -----------------</pre>
 -
 -    <h2><a NAME="Caveat"></a>Caveat</h2>
 -    
 -    <p>This experiment shows that IPsec <i>does</i> seem to be distributing the
 -      payload data <i>uniformly</i>, as encryption should. However, the
 -      experiment described here <i>cannot</i>detect many possible flaws in a
 -      system (none of which do I have any evidence for). These include poor
 -      key generation or exchange, data or keys being visible to others, use of
 -      weak algorithms, kernel subversion, etc. Study the source; know the
 -      code.</p>
 -      
 -    <h2><a NAME="IPsec"></a>IPsec---Definition</h2>
 -
 -    <p>Internet Protocol security extensions to IPv4; required for IPv6.  A
 -      protocol for negotiating encryption and authentication at the IP
 -      (host-to-host) level. SSL secures only one application socket; SSH
 -      secures only a login; PGP secures only a specified file or
 -      message. IPsec encrypts everything between two hosts.</p>
 -    
 -    <h2><a NAME="Installing IPsec"></a>Installing IPsec</h2>
 -
 -    <p>Most of the modern versions of FreeBSD have IPsec support
 -	in their base source.  So you'll probably will need to
 -	include <i>IPSEC</i> option in your kernel config
 -	and, after kernel rebuild and reinstall, configure IPsec
 -	connections using <i>setkey</i> command.</p>
 -    
 -
 -    <p>A comprehensive guide on running IPsec on FreeBSD is
 -      provided in <a
 -      href="http://www.freebsd.org/handbook/ipsec.html">FreeBSD
 -      Handbook</a>.
 -
 -    <h2><a NAME="KERNELNAME"></a>usr/src/sys/i386/conf/KERNELNAME</h2>
 -    
 -    <p>This needs to be present in the kernel config file in order to be able
 -      to capture network data with <i>tcpdump</i>.
 -      Be sure to run <i>config</i> after adding this, and rebuild and
 -      reinstall.</p>
 -
 -    <pre>device	bpf
 -</pre>
 -
 -    <h2><a name="Maurer's Universal Statistical Test"></a>Maurer's Universal Statistical Test (for block
 -      size=8 bits)</h2>
 -
 -        <p>You can find the same code at <a
 -          href="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
 -          this link</a>.</p>
 +2.0983 -----------------
 +</screen>
 +      </step>
 +    </procedure>
 +  </sect1>
 +
 +    <sect1 id="caveat">
 +      <title>Caveat</title>
 +
 +    <para>This experiment shows that IPsec <emphasis>does</emphasis>
 +      seem to be distributing the payload data
 +      <emphasis>uniformly</emphasis>, as encryption should.  However,
 +      the experiment described here <emphasis>cannot</emphasis>
 +      detect many possible flaws in a system (none of which do I have
 +      any evidence for).  These include poor key generation or
 +      exchange, data or keys being visible to others, use of weak
 +      algorithms, kernel subversion, etc.  Study the source; know the
 +      code.</para>
 +  </sect1>
 +
 +  <sect1 id="IPsec">
 +    <title>IPsec---Definition</title>
 +
 +    <para>Internet Protocol security extensions to IPv4; required for
 +      IPv6.  A protocol for negotiating encryption and authentication
 +      at the IP (host-to-host) level.  SSL secures only one application
 +      socket; <application>SSH</application> secures only a login;
 +      <application>PGP</application> secures only a specified file or
 +      message.  IPsec encrypts everything between two hosts.</para>
 +  </sect1>
 +
 +  <sect1 id="ipsec-install">
 +    <title>Installing IPsec</title>
 +
 +    <para>Most of the modern versions of FreeBSD have IPsec support
 +      in their base source.  So you'll probably will need to include
 +      <option>IPSEC</option> option in your kernel config and, after
 +      kernel rebuild and reinstall, configure IPsec connections using
 +      &man.setkey.8; command.</para>
 +
 +    <para>A comprehensive guide on running IPsec on FreeBSD is
 +      provided in <ulink
 +      url="http://www.freebsd.org/handbook/ipsec.html">FreeBSD
 +      Handbook</ulink>.</para>
 +  </sect1>
 +
 +  <sect1 id="kernel">
 +    <title>usr/src/sys/i386/conf/KERNELNAME</title>
 +
 +    <para>This needs to be present in the kernel config file in order
 +      to be able to capture network data with &man.tcpdump.1;.  Be sure
 +      to run &man.config.8; after adding this, and rebuild and
 +      reinstall.</para>
 +
 +<programlisting>
 +device	bpf
 +</programlisting>
 +  </sect1>
 +
 +    <sect1 id="code">
 +      <title>Maurer's Universal Statistical Test (for block size=8
 +        bits)</title>
 +
 +        <para>You can find the same code at <ulink
 +          url="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
 +          this link</ulink>.</para>
  
 -    <pre><![ CDATA [/*
 +<programlisting>
 +/*
    ULISCAN.c   ---blocksize of 8
  
    1 Oct 98
 @@ -178,13 +241,13 @@
  */
  
  #define L 8
 -#define V (1<<L)
 +#define V (1&lt;&lt;L)
  #define Q (10*V)
  #define K (100   *Q)
  #define MAXSAMP (Q + K)
  
 -#include <stdio.h>
 -#include <math.h>
 +#include &lt;stdio.h&gt;
 +#include &lt;math.h&gt;
  
  int main(argc, argv)
  int argc;
 @@ -202,7 +265,7 @@
  
    printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP);
  
 -  if (argc < 2) {
 +  if (argc &lt; 2) {
      printf("Usage: Uliscan filename\n");
      exit(-1);
    } else {
 @@ -216,11 +279,11 @@
      exit(-1);
    }
  
 -  for (i = 0; i < V; i++) {
 +  for (i = 0; i &lt; V; i++) {
      table[i] = 0;
    }
  
 -  for (i = 0; i < Q; i++) {
 +  for (i = 0; i &lt; Q; i++) {
      b = fgetc(fptr);
      table[b] = i;
    }
 @@ -236,15 +299,15 @@
      iproduct = 1;
  
      if (run)
 -      for (i = Q; run && i < Q + K; i++) {
 +      for (i = Q; run && i &lt; Q + K; i++) {
          j = i;
          b = fgetc(fptr);
  
 -        if (b < 0)
 +        if (b &lt; 0)
            run = 0;
  
          if (run) {
 -          if (table[b] > j)
 +          if (table[b] &gt; j)
              j += K;
  
            sum += log((double)(j-table[b]));
 @@ -259,16 +322,16 @@
      sum = (sum/((double)(i - Q))) /  log(2.0);
      printf("%4.4f ", sum);
  
 -    for (i = 0; i < (int)(sum*8.0 + 0.50); i++)
 +    for (i = 0; i &lt; (int)(sum*8.0 + 0.50); i++)
        printf("-");
  
      printf("\n");
  
      /* refill initial table */
      if (0) {
 -      for (i = 0; i < Q; i++) {
 +      for (i = 0; i &lt; Q; i++) {
          b = fgetc(fptr);
 -        if (b < 0) {
 +        if (b &lt; 0) {
            run = 0;
          } else {
            table[b] = i;
 @@ -276,8 +339,7 @@
        }
      }
    }
 -}]]></pre>
 -  </body>
 -</html>
 -
 -
 +}
 +</programlisting>
 +  </sect1>
 +</article>
 
 -- 
 Alex Kapranoff,                              Voice: +7(0832)791845
 We've lived 201 days in the brand new millenium...
State-Changed-From-To: open->closed 
State-Changed-By: dd 
State-Changed-When: Sun Jul 29 02:47:45 PDT 2001 
State-Changed-Why:  
Committed, thanks! 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=28916 
>Unformatted:
