Building an OpenBSD port

=================================================================== RCS file: /cvsrepo/anoncvs/cvs/www/Attic/porting.html,v retrieving revision 1.14 retrieving revision 1.15 diff -c -r1.14 -r1.15 *** www/Attic/porting.html 1998/12/07 23:06:48 1.14 --- www/Attic/porting.html 1998/12/20 17:08:45 1.15 *************** *** 1,17 **** Building an OpenBSD port --- 1,17 ---- Building an OpenBSD port *************** *** 50,56 **** FreeBSD Handbook. This is the FreeBSD porting bible.

OpenBSD porting checklist. !

Porting audio applications to OpenBSD.

The OpenBSD ports mailing list, ports@OpenBSD.ORG. --- 50,56 ---- FreeBSD Handbook. This is the FreeBSD porting bible.

OpenBSD porting checklist. !

Porting audio applications to OpenBSD.

The OpenBSD ports mailing list, ports@OpenBSD.ORG. *************** *** 58,70 ****

OpenBSD does NOT use /usr/local/etc/rc.d.
/usr/local is often shared between several machines ! thanks to NFS. For this reason, configuration files that are specific ! to a given machine can't be stored under /usr/local, ! /etc is the central repository for per machine ! configuration files. Moreover, OpenBSD policy is to never update ! files under /etc automatically. Ports that need some ! specific boot setup should advise the administrator about what to do ! instead of blindly installing files.
OpenBSD does NOT compress man pages.
OpenBSD does NOT require -lcrypt.
DES encryption is part of the standard libc. --- 58,70 ----
- OpenBSD does NOT use /usr/local/etc/rc.d.
  /usr/local is often shared between several machines ! thanks to NFS. For this reason, configuration files that are specific ! to a given machine can't be stored under /usr/local, ! /etc is the central repository for per machine ! configuration files. Moreover, OpenBSD policy is to never update ! files under /etc automatically. Ports that need some ! specific boot setup should advise the administrator about what to do ! instead of blindly installing files.
- OpenBSD does NOT compress man pages.
- OpenBSD does NOT require -lcrypt.
  DES encryption is part of the standard libc. *************** *** 99,107 **** conditions where you don't have proper control. For instance, an attacker who already has user privileges on your machines may replace files in /tmp with symbolic links to more strategic files, such as ! /etc/passwd. For instance, the bsd linker warns about ! mktemp uses. These must be fixed. ! This is not quite as simple as s/mktemp/mkstemp/g.
- Just because you can read it doesn't mean you should. A well-known hole of this nature was the startx problem. As a setuid program, --- 99,116 ---- conditions where you don't have proper control. For instance, an attacker who already has user privileges on your machines may replace files in /tmp with symbolic links to more strategic files, such as ! /etc/passwd. ! !
- For instance, one very common problem is the mktemp ! function. Head the warnings of the bsd linker about its uses. ! These must be fixed. ! This is not quite as simple as s/mktemp/mkstemp/g.
  ! Refer to the mktemp(3) man page of OpenBSD current ! for more indications. ! Correct code using mkstemp includes the source to ! ed or mail. ! A rare instance of code that uses mktemp correctly ! can be found in the rsync port.
- Just because you can read it doesn't mean you should. A well-known hole of this nature was the startx problem. As a setuid program, *************** *** 111,169 **** Pretty handy to grab the first line of a shadow passwd file, considering these often start with root entry. Do not open your file, and then do an fstat on the open descriptor to check if you should have ! been able to open it (or the attacked will play with /dev/rst0 and rewind your tape) -- open it with the correct uid/gid/grouplist set.
- Don't use anything that forks a shell in setuid programs before dropping ! your privileges. This includes popen and system. Use fork, pipe and execve instead. !
- Pass open descriptors instead of filenames to other programs to avoid race ! conditions. Even if a program does not accept file descriptors, you can ! still use /dev/fd/0. !
- Access rights are attached to file descriptors. If you need setuid rights to open a file, open that file, then drop your privileges. You can still access the open descriptor, but you have less to worry about. This is double-edged: even after dropping privileges, you should still watch out for those descriptors.
- Avoid root setuid as much as you can. Basically, root can do anything, ! but root rights are very rarely needed, except maybe to create socket ports with ! a number under 1024. It is arguably better to keep that under inetd control and just add the relevant entries to inetd.conf. You must know the appropriate magic for writing daemons to achieve that. ! It could be argued that you have no business writing setuid programs if you don't ! know how to do that. !
- Use setgid instead of setuid. Apart from those specific files needed by setgid ! programs, most files are not group-writable. Hence, a security problem in a setgid ! program won't compromise your system as much: with only group rights, the worst ! an intruder will be able to do is hack a games score table or some such. See the xkobo port for an instance of such a change. !
- Don't trust group-writable files. Even though they are audited, setgid programs ! are not perceived as important potential security holes. Hence stuff they can tamper ! with shouldn't be considered sensitive information. !
- Don't trust your environment ! This involves simple things such as your PATH ! (never use system with an unqualified name), but also more subtle items ! such as your locale, timezone, termcap, and so on. Be aware of transitivity: even though you're ! taking full precautions, programs you call directly won't necessarily. Never ! use system in privileged programs, build your command line, a controlled environment, ! and call execvp directly. The perlsec man page is a good tutorial on ! such problems. !
- Never used setuid shell-scripts. These are inherently insecure. Wrap them into some C code ! that ensures a proper environment. On the other hand, OpenBSD features secure perl scripts. !
- Beware the dynamic loader. If you are running setuid, it will only use trusted libraries ! that were scanned with ldconfig. Setgid is not enough. !
- Dynamic libraries are tricky. C++ code sets a similar problem. Basically, libraries may take ! some action based upon your environment before your main program even gets to check its setuid ! status. OpenBSD issetugid addresses this problem, from the library writer point ! of view. Don't try to port libraries unless you understand this issue thoroughly.
Generic porting hints
- Don't use anything that forks a shell in setuid programs before dropping ! your privileges. This includes popen and ! system. Use fork, pipe and execve instead. !
- Pass open descriptors instead of filenames to other programs to ! avoid race conditions. Even if a program does not accept file ! descriptors, you can still use /dev/fd/0. !
- Access rights are attached to file descriptors. If you need setuid rights to open a file, open that file, then drop your privileges. You can still access the open descriptor, but you have less to worry about. This is double-edged: even after dropping privileges, you should still watch out for those descriptors.
- Avoid root setuid as much as you can. Basically, root can do anything, ! but root rights are very rarely needed, except maybe to create ! socket ports with a number under 1024. It is arguably better to ! keep that under inetd control and just add the relevant entries to inetd.conf. You must know the appropriate magic for writing daemons to achieve that. ! It could be argued that you have no business writing setuid programs ! if you don't know how to do that. !
- Use setgid instead of setuid. Apart from those specific files needed ! by setgid programs, most files are not group-writable. Hence, a ! security problem in a setgid program won't compromise your system as ! much: with only group rights, the worst an intruder will be able to ! do is hack a games score table or some such. See the xkobo port for an instance of such a change. !
- Don't trust group-writable files. Even though they are audited, ! setgid programs are not perceived as important potential security ! holes. Hence stuff they can tamper with shouldn't be considered ! sensitive information. !
- Don't trust your environment ! This involves simple things such as ! your PATH (never use system with an ! unqualified name, avoid execvp), but also more subtle ! items such as your locale, timezone, termcap, and so on. ! Be aware of transitivity: even though you're taking full precautions, ! programs you call directly won't necessarily. Never ! use system in privileged programs, build your command ! line, a controlled environment, and call execve directly. ! The perlsec man page is a good tutorial on such problems. !
- Never used setuid shell-scripts. These are inherently insecure. ! Wrap them into some C code that ensures a proper environment. ! On the other hand, OpenBSD features secure perl scripts. !
- Beware the dynamic loader. If you are running setuid, it will only ! use trusted libraries that were scanned with ldconfig. ! Setgid is not enough. !
- Dynamic libraries are tricky. C++ code sets a similar problem. ! Basically, libraries may take some action based upon your environment ! before your main program even gets to check its setuid status. ! OpenBSD issetugid addresses this problem, from the ! library writer point of view. Don't try to port libraries unless you ! understand this issue thoroughly.
Generic porting hints
- Test for features, not for specific OSes. In the long run, it is much ! better to test whether tcgetattr works than whether you're running ! under BSD 4.3 or later, or SystemVR4. These kind of tests just confuse the ! issue. The way to go about it is, for instance, to test for one particular ! system, set up a slew of HAVE_TCGETATTR defines, then proceed to ! the next system. This technique separates features tests from specific OSes. ! In a hurry, another porter can just add the whole set of -DHAVE_XXX ! defines to the Makefile. One may also write or add to a configure script to check for ! that feature and add it automatically. As an example not to follow, check nethack 3.2.2 ! source: it assumes loads of things based on the system type. Most of these assumptions ! are obsolete and no longer reflect reality: POSIX functions are more useful than older ! BSD versus SystemV differences, to the point that some traditional bsd functions are now only supported through compatibility libraries.
- Avoid include files that include other includes that... First, because ! this is inefficient. Your project will end up including a file that includes ! everything. Also, because it makes some problems difficult to correct. It ! becomes harder to not include one particular file at a given point.
- Avoid bizarre macro tricks. Undefining a macro that was defined by a header file is a bad idea. Defining macros to get some specific behavior ! from an include file is also a bad idea: compilation modes should be global. ! If you want POSIX behavior, say so, and #define POSIX_C_SOURCE throughout the whole project, not when you feel like it.
- Don't ever write system function prototypes. All modern systems, OpenBSD included, have a standard location for these prototypes. Likely ! places include unistd.h, fcntl.h or termios.h. ! The man page frequently states where the prototype lies. You might need ! another slew of HAVE_XXX macros to procure the right file. ! Don't worry about including the same file twice, include files have guards ! that prevent all kinds of nastiness.
  If some broken system needs you to write the prototype, don't impose ! on all other systems. Roll-your-own prototypes will break because they may ! use types that are equivalent on your system, but are not portable to other ! systems (unsigned long instead of size_t), or get some ! const status wrong. Also, some compilers, such as OpenBSD's own gcc, are able to do a better job with some very frequent functions such as strlen if you include the right header file.
- Don't use the name of a standard system function for anything else. ! If you want to write your own function, give it its own name, and call that ! function everywhere. If you wish to revert to the default system function, ! you just need to comment your code out, and define your own name to the ! system function. Don't do it the other way round. Code should look like this
```
         /* prototype part */
         #ifdef USE_OWN_GCVT
--- 208,265 ----
             #endif
         
```
- Test for features, not for specific OSes. In the long run, it is much ! better to test whether tcgetattr works than whether ! you're running under BSD 4.3 or later, or SystemVR4. These kind of ! tests just confuse the issue. The way to go about it is, for instance, ! to test for one particular system, set up a slew of ! HAVE_TCGETATTR defines, then proceed to the next system. ! This technique separates features tests from specific OSes. ! In a hurry, another porter can just add the whole set of ! -DHAVE_XXX defines to the Makefile. One may also write ! or add to a configure script to check for that feature and add it ! automatically. As an example not to follow, check nethack 3.2.2 ! source: it assumes loads of things based on the system type. Most ! of these assumptions are obsolete and no longer reflect reality: ! POSIX functions are more useful than older BSD versus SystemV ! differences, to the point that some traditional bsd functions are now only supported through compatibility libraries.
- Avoid include files that include other includes that... First, because ! this is inefficient. Your project will end up including a file that ! includes everything. Also, because it makes some problems difficult ! to fix. It becomes harder to not include one particular file ! at a given point.
- Avoid bizarre macro tricks. Undefining a macro that was defined by a header file is a bad idea. Defining macros to get some specific behavior ! from an include file is also a bad idea: compilation modes should be ! global. If you want POSIX behavior, say so, and ! #define POSIX_C_SOURCE throughout the whole project, not when you feel like it.
- Don't ever write system function prototypes. All modern systems, OpenBSD included, have a standard location for these prototypes. Likely ! places include unistd.h, fcntl.h or ! termios.h. ! The man page frequently states where the prototype can be found. ! You might need another slew of HAVE_XXX macros to ! procure the right file. Don't worry about including the same file ! twice, include files have guards that prevent all kinds of nastiness.
  If some broken system needs you to write the prototype, don't impose ! on all other systems. Roll-your-own prototypes will break because they ! may use types that are equivalent on your system, but are not portable ! to other systems (unsigned long instead of ! size_t), or get some const status wrong. ! Also, some compilers, such as OpenBSD's own gcc, are able to do a better job with some very frequent functions such as strlen if you include the right header file.
- Don't use the name of a standard system function for anything else. ! If you want to write your own function, give it its own name, and ! call that function everywhere. If you wish to revert to the ! default system function, you just need to comment your code out, ! and define your own name to the system function. Don't do it the ! other way round. Code should look like this
```
         /* prototype part */
         #ifdef USE_OWN_GCVT
***************
*** 248,255 ****
         #ifdef USE_OWN_GCVT
         char *foo_gcvt(double number, size_t ndigit, char *buf)
            {
! 	  /* proper definition */
! 	  }
  
         /* typical use */
         s = foo_gcvt(n, 15, b);
--- 275,282 ----
         #ifdef USE_OWN_GCVT
         char *foo_gcvt(double number, size_t ndigit, char *buf)
            {
!           /* proper definition */
!           }
  
         /* typical use */
         s = foo_gcvt(n, 15, b);
***************
*** 257,305 ****
    
```
Other Helpful Hints
- Do not assume /usr/local/bin or ! /usr/X11R6/bin is in the installers path. A good ! way to verify this is to create and install your port while ! running as root with only /bin and ! /usr/bin in your path. !
- Do NOT generate shared libraries for ${MACHINE_ARCH} == alpha
- In OpenBSD curses.h/libcurses/libtermlib are the ``new curses''. Change:
  ! ncurses.h ==> curses.h
  ! -lncurses ==> -lcurses
  ! ``old (BSD) curses'' is available by defining _USE_OLD_CURSES_ before including curses.h (usually in a Makefile) and ! linking with -lcurses.
- In OpenBSD, terminal discipline has been upgraded from the older BSD sgtty to the newer POSIX tcgetattr family. ! Avoid the older style in new code. Some code may define tcgetattr ! to be a synonym for the older sgtty, but this is at best a stopgap ! measure on OpenBSD. The xterm source code is a very good example of ! what not to do. ! Try to get your system functionality right: you want a type that remembers ! the state of your terminal (possible typedef), you want a function that ! extracts the current state, and a function that sets the new state. ! Functions that modify this state are more difficult, as they tend to vary ! depending upon the system. Also, don't forget that you will have to handle ! cases where you are not connected to the terminal, and that you need to ! handle signals: not only termination, but also getting put in the background ! you should leave your terminal in a sane state. Do your tests under an ! older shell, such as sh, which does not reset the terminal in any way at program's termination. !
- The newer termcap/terminfo and curses, as included with OpenBSD, include standard sequences ! for controlling color terminals. You should use these if possible, reverting ! to standard ANSI color sequences on other systems. However, some terminal descriptions ! have not been updated yet, and you may need to be able to specify these sequences manually. ! This is the way vim5.1 handles it. This is not strictly necessary. Except for privileged ! programs, it is generally possible to override a termcap definition through the TERMCAP variable and get it to work properly. !
- Signal semantics are tricky, and vary from one system to another. Use sigaction ! to ensure a specific semantics, along with other system calls referenced in its manpage.
www@openbsd.org !
$OpenBSD: porting.html,v 1.14 1998/12/07 23:06:48 espie Exp $ --- 284,337 ----

Other Helpful Hints

Recent versions of bsd.port.mk set the installers ! path. Specifically, they set /usr/bin and ! /bin to be searched before ! /usr/local/bin and /usr/X11R6/bin. !
Do NOT generate shared libraries for ${MACHINE_ARCH} == alpha
In OpenBSD curses.h/libcurses/libtermlib are the ``new curses''. Change:
! ncurses.h ==> curses.h
! -lncurses ==> -lcurses
! ``old (BSD) curses'' is available by defining ! _USE_OLD_CURSES_ before including curses.h (usually in a Makefile) and ! linking with -locurses.
In OpenBSD, terminal discipline has been upgraded from the older BSD sgtty to the newer POSIX tcgetattr family. ! Avoid the older style in new code. Some code may define ! tcgetattr to be a synonym for the older ! sgtty, but this is at best a stopgap measure on OpenBSD. ! The xterm source code is a very good example of ! what not to do. Try to get your system functionality right: you ! want a type that remembers the state of your terminal ! (possible typedef), you want a function that extracts the current ! state, and a function that sets the new state. ! Functions that modify this state are more difficult, as they tend ! to vary depending upon the system. Also, don't forget that you will ! have to handle cases where you are not connected to a terminal, ! and that you need to handle signals: not only termination, but ! also background (SIGTSTP). You should always leave ! the terminal in a sane state. Do your tests under an older shell, ! such as sh, which does not reset the terminal in any way at program's termination. !
The newer termcap/terminfo and curses, as included with OpenBSD, ! include standard sequences for controlling color terminals. You ! should use these if possible, reverting to standard ANSI color ! sequences on other systems. However, some terminal descriptions ! have not been updated yet, and you may need to be able to specify ! these sequences manually. This is the way vim handles it. This is ! not strictly necessary. Except for privileged programs, it is ! generally possible to override a termcap definition through the TERMCAP variable and get it to work properly. !
Signal semantics are tricky, and vary from one system to another. ! Use sigaction to ensure a specific semantics, along ! with other system calls referenced in the corresponding manpage.

www@openbsd.org !
$OpenBSD: porting.html,v 1.15 1998/12/20 17:08:45 espie Exp $

Generic porting hints

Generic porting hints

Other Helpful Hints

Other Helpful Hints