lib/libc/ssp/ssp.3

   1 .\"     $NetBSD: ssp.3,v 1.5 2010/12/19 08:28:40 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\"
  31 .Dd December 19, 2010
  32 .Dt SSP 3
  33 .Os
  34 .Sh NAME
  35 .Nm ssp
  36 .Nd bounds checked libc functions
  37 .Sh LIBRARY
  38 .Lb libssp
  39 .Sh SYNOPSIS
  40 .In ssp/stdio.h
  41 .Ft int
  42 .Fn sprintf "char *str" "const char *fmt" "..."
  43 .Ft int
  44 .Fn vsprintf "char *str" "const char *fmt" "va_list ap"
  45 .Ft int
  46 .Fn snprintf "char *str" "size_t len" "const char *fmt" "..."
  47 .Ft int
  48 .Fn vsnprintf "char *str" "size_t len" "const char *fmt" "va_list ap"
  49 .Ft char *
  50 .Fn gets "char *str"
  51 .Ft char *
  52 .Fn fgets "char *str" "int len" "FILE *fp"
  53 .In ssp/string.h
  54 .Ft void *
  55 .Fn memcpy "void *str" "const void *ptr" "size_t len"
  56 .Ft void *
  57 .Fn memmove "void *str" "const void *ptr" "size_t len"
  58 .Ft void *
  59 .Fn memset "void *str" "int val" "size_t len"
  60 .Ft char *
  61 .Fn strcpy "char *str" "const char *ptr" "size_t len"
  62 .Ft char *
  63 .Fn strcat "char *str" "const char *ptr" "size_t len"
  64 .Ft char *
  65 .Fn strncpy "char *str" "const char *ptr" "size_t len"
  66 .Ft char *
  67 .Fn strncat "char *str" "const char *ptr" "size_t len"
  68 .In ssp/strings.h
  69 .Ft void *
  70 .Fn bcopy "const void *ptr" "void *str" "size_t len"
  71 .Ft void *
  72 .Fn bzero "void *str" "size_t len"
  73 .In ssp/unistd.h
  74 .Ft ssize_t
  75 .Fn read "int fd" "void *str" "size_t len"
  76 .Ft int
  77 .Fn readlink "const char * restrict path" "char * restrict str" "size_t len"
  78 .Ft int
  79 .Fn getcwd "char *str" "size_t len"
  80 .Sh DESCRIPTION
  81 When
  82 .Dv _FORTIFY_SOURCE
  83 bounds checking is enabled as described below, the above functions get
  84 overwritten to use the
  85 .Xr __builtin_object_size 3
  86 function to compute the size of
  87 .Fa str ,
  88 if known at compile time,
  89 and perform bounds check on it in order
  90 to avoid data buffer or stack buffer overflows.
  91 If an overflow is detected, the routines will call
  92 .Xr abort 3 .
  93 .Pp
  94 To enable these function overrides the following should be added to the
  95 .Xr gcc 1
  96 command line:
  97 .Dq \-I/usr/include/ssp
  98 to override the standard include files and
  99 .Dq \-D_FORTIFY_SOURCE=1
 100 or
 101 .Dq \-D_FORTIFY_SOURCE=2 .
 102 .Pp
 103 If
 104 .Dv _FORTIFY_SOURCE is set to
 105 .Dv 1
 106 the code will compute the maximum possible buffer size for
 107 .Fa str ,
 108 and if set to
 109 .Dv 2
 110 it will compute the minimum buffer size.
 111 .Sh SEE ALSO
 112 .Xr gcc 1 ,
 113 .Xr __builtin_object_size 3 ,
 114 .Xr stdio 3 ,
 115 .Xr string 3 ,
 116 .Xr security 8
 117 .Sh HISTORY
 118 The
 119 .Nm ssp
 120 library appeared
 121 .Nx 4.0 .