Bug 28916
| Summary: | DocBook conversion of doc/articles/ipsec-must | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Alex Kapranoff <kapr> | ||||
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | CC: | honig | ||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Alex Kapranoff
2001-07-12 16:10:01 UTC
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. * 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. 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... * 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. - 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<<L) #define Q (10*V) #define K (100 *Q) #define MAXSAMP (Q + K) -#include <stdio.h> -#include <math.h> +#include <stdio.h> +#include <math.h> 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 < 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 < V; i++) { table[i] = 0; } - for (i = 0; i < Q; i++) { + for (i = 0; i < 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 < Q + K; i++) { j = i; b = fgetc(fptr); - if (b < 0) + if (b < 0) run = 0; if (run) { - if (table[b] > j) + if (table[b] > 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 < (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 < Q; i++) { b = fgetc(fptr); - if (b < 0) { + if (b < 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 Committed, thanks! |
