docs/125485: [patch] updates to developers handbook: security section

[Gavin Atkinson]

>Number:         125485
>Category:       docs
>Synopsis:       [patch] updates to developers handbook: security section
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 10 20:50:02 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     Gavin Atkinson
>Release:        FreeBSD 7.0-STABLE amd64
>Organization:
>Environment:
System: FreeBSD buffy.york.ac.uk 7.0-STABLE FreeBSD 7.0-STABLE #3: Fri Jun 20 09:21:51 UTC 2008 root at buffy.york.ac.uk:/usr/obj/usr/src/sys/GENERIC amd64

>Description:
	A couple of updates to the "Secure Programming" section of the
developers handbook:
- Remove an example that is sufficiently old to not really be meaningful.
- StackGuard is no more, replace the mention with a section on ProPolice.
- Clarify a use of "jail" to mean a chroot() jail.
Note that this section also has a section on POSIX Process Capabilities
in need of an update, I'll do that on the next sweep.
>How-To-Repeat:
	N/A
>Fix:

--- devh-secure.diff begins here ---
Index: doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml,v
retrieving revision 1.28
diff -u -r1.28 chapter.sgml
--- doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml	4 Aug 2007 08:11:40 -0000	1.28
+++ doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml	10 Jul 2008 20:34:44 -0000
@@ -57,13 +57,7 @@
 
       <indexterm><primary>Morris Internet worm</primary></indexterm>
 
-      effective today.  Of the 17 CERT security advisories of 1999, 10
-
-      <indexterm>
-        <primary>CERT</primary><secondary>security advisories</secondary>
-      </indexterm>
-
-      of them were directly caused by buffer-overflow software bugs.
+      effective today.
       By far the most common type of buffer overflow attack is based
       on corrupting the stack.</para>
 
@@ -259,39 +253,32 @@
         code in public use which blindly copies memory around without
         using any of the bounded copy routines we just discussed.
         Fortunately, there is another solution.  Several compiler
-        add-ons and libraries exist to do Run-time bounds checking in
+        features and libraries exist to do Run-time bounds checking in
         C/C++.</para> 
 
+	<indexterm><primary>ProPolice</primary></indexterm> 
 	<indexterm><primary>StackGuard</primary></indexterm> 
 	<indexterm><primary>gcc</primary></indexterm>  
 
-        <para>StackGuard is one such add-on that is implemented as a
-        small patch to the gcc code generator.  From the <ulink
-          url="http://immunix.org/stackguard.html">StackGuard
-          website</ulink>:
-
-        <blockquote><para>"StackGuard detects and defeats stack
-        smashing attacks by protecting the return address on the stack
-        from being altered.  StackGuard places a "canary" word next to
-        the return address when a function is called.  If the canary
-        word has been altered when the function returns, then a stack
-        smashing attack has been attempted, and the program responds
-        by emitting an intruder alert into syslog, and then
-        halts."</para></blockquote> 
-
-        <blockquote><para>"StackGuard is implemented as a small patch
-        to the gcc code generator, specifically the function_prolog()
-        and function_epilog() routines.  function_prolog() has been
-        enhanced to lay down canaries on the stack when functions
-        start, and function_epilog() checks canary integrity when the
-        function exits.  Any attempt at corrupting the return address
-        is thus detected before the function
-        returns."</para></blockquote>
-        </para>
+	<para>ProPolice is one such compiler feature, and is
+	integrated into &man.gcc.1; version 4.1 and later.  It
+	replaces and extends the earlier StackGuard &man.gcc.1;
+	extension.</para>
+
+	<para>ProPolice helps to protect against stack-based buffer
+	overflows and other attacks by laying pseudo-random numbers
+	in key areas of the stack before calling any function.  On
+	the function return these "canaries" are checked, and if
+	they are found to have been changed the executable is
+	immediately aborted.  Thus any attempt to modify the return
+	address or other variable stored on the stack in an attempt
+	to get malicious code to run is unlikely to succeed, as the
+	attacker would have to also manage to leave the pseudo-random
+	canaries untouched.</para>
 
         <indexterm><primary>buffer overflow</primary></indexterm>
 
-        <para>Recompiling your application with StackGuard is an
+        <para>Recompiling your application with ProPolice is an
         effective means of stopping most buffer-overflow attacks, but
         it can still be compromised.</para>
 
@@ -378,7 +365,8 @@
       should also be noted that a process can easily break out of a
       chroot environment if it has root privilege.  This could be
       accomplished by creating device nodes to read kernel memory,
-      attaching a debugger to a process outside of the jail, or in
+      attaching a debugger to a process outside of the
+      <function>chroot()</function> jail, or in
       many other creative ways.</para>
       
       <para>The behavior of the <function>chroot()</function> system
--- devh-secure.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: