diff options
Diffstat (limited to 'static/freebsd/man7/sdoc.7 3.html')
| -rw-r--r-- | static/freebsd/man7/sdoc.7 3.html | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/static/freebsd/man7/sdoc.7 3.html b/static/freebsd/man7/sdoc.7 3.html deleted file mode 100644 index 6b5ac4ff..00000000 --- a/static/freebsd/man7/sdoc.7 3.html +++ /dev/null @@ -1,192 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SDOC(7)</td> - <td class="head-vol">Miscellaneous Information Manual</td> - <td class="head-rtitle">SDOC(7)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">sdoc</code> — <span class="Nd">guide to - adding security considerations sections to manual pages</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">This document presents guidelines for adding security - considerations sections to manual pages. It provides two typical - examples.</p> -<p class="Pp">The guidelines for writing <span class="Ux">FreeBSD</span> manual - pages in <a class="Xr">groff_mdoc(7)</a> mandate that each manual page - describing a feature of the <span class="Ux">FreeBSD</span> system should - contain a security considerations section describing what security - requirements can be broken through the misuse of that feature. When writing - these sections, authors should attempt to achieve a happy medium between two - conflicting goals: brevity and completeness. On one hand, security - consideration sections must not be too verbose, or busy readers might be - dissuaded from reading them. On the other hand, security consideration - sections must not be incomplete, or they will fail in their purpose of - instructing the reader on how to avoid all insecure uses. This document - provides guidelines for balancing brevity and completeness in the security - consideration section for a given feature of the - <span class="Ux">FreeBSD</span> system.</p> -<section class="Ss"> -<h2 class="Ss" id="Where_to_Start"><a class="permalink" href="#Where_to_Start">Where - to Start</a></h2> -<p class="Pp">Begin by listing those general security requirements that can be - violated through the misuse of the feature. There are four classes of - security requirements:</p> -<dl class="Bl-hang Bd-indent"> - <dt id="integrity"><a class="permalink" href="#integrity"><i class="Em">integrity</i></a></dt> - <dd>(example: non-administrators should not modify system binaries),</dd> - <dt id="confidentiality"><a class="permalink" href="#confidentiality"><i class="Em">confidentiality</i></a></dt> - <dd>(example: non-administrators should not view the shadow password - file),</dd> - <dt id="availability"><a class="permalink" href="#availability"><i class="Em">availability</i></a></dt> - <dd>(example: the web server should respond to client requests in a timely - fashion), and</dd> - <dt id="correctness"><a class="permalink" href="#correctness"><i class="Em">correctness</i></a></dt> - <dd>(example: the ps program should provide exactly the process table - information listing functionality described in its documentation - no - more, no less.)</dd> -</dl> -<p class="Pp">A good security considerations section should explain how the - feature can be misused to violate each general security requirement in the - list. Each explanation should be accompanied by instructions the reader - should follow in order to avoid a violation. When referencing potential - vulnerabilities described in the Secure Programming Practices manual page, - <a class="Xr">sprog(7)</a>, likewise cross-reference that document rather - than replicating information. Whenever possible, refer to this document - rather than reproducing the material it contains.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Where_to_Stop"><a class="permalink" href="#Where_to_Stop">Where - to Stop</a></h2> -<p class="Pp">Security problems are often interrelated; individual problems - often have far-reaching implications. For example, the correctness of - virtually any dynamically-linked program is dependent on the correct - implementation and configuration of the run-time linker. The correctness of - this program, in turn, depends on the correctness of its libraries, the - compiler used to build it, the correctness of the preceding compiler that - was used to build that compiler, and so on, as described by Thompson (see - <a class="Sx" href="#SEE_ALSO">SEE ALSO</a>, below).</p> -<p class="Pp">Due to the need for brevity, security consideration sections - should describe only those issues directly related to the feature that is - the subject of the manual page. Refer to other manual pages rather than - duplicating the material found there.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">Security considerations sections for most individual functions can - follow this simple formula:</p> -<p class="Pp"></p> -<ol class="Bl-enum Bd-indent Bl-compact"> - <li>Provide one or two sentences describing each potential security - problem.</li> - <li>Provide one or two sentences describing how to avoid each potential - security problem.</li> - <li>Provide a short example in code.</li> -</ol> -<p class="Pp">This is an example security considerations section for the - <a class="Xr">strcpy(3)</a> manual page:</p> -<p class="Pp">The <code class="Fn">strcpy</code>() function is easily misused in - a manner which enables malicious users to arbitrarily change a running - program's functionality through a buffer overflow attack.</p> -<p class="Pp">Avoid using <code class="Fn">strcpy</code>(). Instead, use - <code class="Fn">strncpy</code>() and ensure that no more characters are - copied to the destination buffer than it can hold. Do not forget to - NUL-terminate the destination buffer, as <code class="Fn">strncpy</code>() - will not terminate the destination string if it is truncated.</p> -<p class="Pp">Note that <code class="Fn">strncpy</code>() can also be - problematic. It may be a security concern for a string to be truncated at - all. Since the truncated string will not be as long as the original, it may - refer to a completely different resource and usage of the truncated resource - could result in very incorrect behavior. Example:</p> -<div class="Bd Pp Li"> -<pre>void -foo(const char *arbitrary_string) -{ - char onstack[8]; - -#if defined(BAD) - /* - * This first strcpy is bad behavior. Do not use strcpy()! - */ - (void)strcpy(onstack, arbitrary_string); /* BAD! */ -#elif defined(BETTER) - /* - * The following two lines demonstrate better use of - * strncpy(). - */ - (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1); - onstack[sizeof(onstack - 1)] = '\0'; -#elif defined(BEST) - /* - * These lines are even more robust due to testing for - * truncation. - */ - if (strlen(arbitrary_string) + 1 > sizeof(onstack)) - err(1, "onstack would be truncated"); - (void)strncpy(onstack, arbitrary_string, sizeof(onstack)); -#endif -}</pre> -</div> -<p class="Pp">Security considerations sections for tools and commands are apt to - be less formulaic. Let your list of potentially-violated security - requirements be your guide; explain each one and list a solution in as - concise a manner as possible.</p> -<p class="Pp">This is an example security considerations section for the - <a class="Xr">rtld(1)</a> manual page:</p> -<p class="Pp">Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables, - malicious users can cause the dynamic linker to link shared libraries of - their own devising into the address space of processes running - non-set-user-ID/group-ID programs. These shared libraries can arbitrarily - change the functionality of the program by replacing calls to standard - library functions with calls to their own. Although this feature is disabled - for set-user-ID and set-group-ID programs, it can still be used to create - Trojan horses in other programs.</p> -<p class="Pp">All users should be aware that the correct operation of non - set-user-ID/group-ID dynamically-linked programs depends on the proper - configuration of these environment variables, and take care to avoid actions - that might set them to values which would cause the run-time linker to link - in shared libraries of unknown pedigree.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">groff_mdoc(7)</a>, <a class="Xr">security(7)</a>, - <a class="Xr">sprog(7)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Edward Amoroso, AT&T Bell - Laboratories</span>, <i class="RsB">Fundamentals of Computer Security - Technology</i>, <i class="RsI">P T R Prentice Hall</i>, - <span class="RsD">1994</span>.</cite></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Ken Thompson</span>, - <span class="RsT">Reflections on Trusting Trust</span>, - <i class="RsI">Association for Computing Machinery, Inc.</i>, - <i class="RsJ">Communications of the ACM</i>, <span class="RsN">Vol. 27, No. - 8</span>, <span class="RsP">761-763</span>, <span class="RsD">August, - 1984</span>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">sdoc</code> manual page first appeared in - <span class="Ux">FreeBSD 5.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Tim Fraser</span> - <<a class="Mt" href="mailto:tfraser@tislabs.com">tfraser@tislabs.com</a>>, - NAI Labs CBOSS project - <br/> - <span class="An">Brian Feldman</span> - <<a class="Mt" href="mailto:bfeldman@tislabs.com">bfeldman@tislabs.com</a>>, - NAI Labs CBOSS project</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">September 5, 2005</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |