Changeset View
Standalone View
share/man/man9/aslr.9
- This file was added.
.\"- | |||||
rwatson: This man page contains a large number of style violations -- see mdoc(7) for a number of… | |||||
.\" Copyright (c) 2014,2015 Shawn Webb <shawn.webb@hardenedbsd.org> | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd January 31, 2015 | |||||
.Dt ASLR 9 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm aslr | |||||
.Nd Address Space Layout Randomization | |||||
.Sh SYNOPSIS | |||||
.In sys/types.h | |||||
.In sys/pax.h | |||||
.Pp | |||||
In the kernel configuration file: | |||||
.Cd "options PAX_ASLR" | |||||
.Sh DESCRIPTION | |||||
.Ss Introduction | |||||
Security in | |||||
.Fx | |||||
is based primarily in policy-based technologies. | |||||
Existing tools such as jails, Capsicum, vnet/vimage, and the | |||||
rwatsonUnsubmitted Not Done Inline ActionsShould these be cross references -- e.g., capsicum(4), jail(2), and so on? rwatson: Should these be cross references -- e.g., capsicum(4), jail(2), and so on? | |||||
.Xr mac 3 | |||||
framework can make | |||||
.Fx Ns -based systems quite resilient against | |||||
attacks. FreeBSD lacks basic low-level exploit mitigation, such as | |||||
rwatsonUnsubmitted Not Done Inline ActionsAs the patch being reviewed is a commit candidate, it seems contrary to include a note in the new man page on how the feature to be committed isn't present :-) rwatson: As the patch being reviewed is a commit candidate, it seems contrary to include a note in the… | |||||
Not Done Inline Actions'-based' and all following text should be on its own line. gjb: '-based' and all following text should be on its own line. | |||||
Address Space Layout Randomization (ASLR). ASLR Randomizes the address | |||||
space layout of an application, making exploitation difficult for an | |||||
Not Done Inline ActionsNew sentences should start on a new line. gjb: New sentences should start on a new line. | |||||
attacker. This manual page and the associated implementation aim to | |||||
provide a secure, robust, extensible, and easily-managed form of ASLR | |||||
Not Done Inline ActionsNew sentences should start on a new line. gjb: New sentences should start on a new line. | |||||
fit for production use in | |||||
.Fx Ns . | |||||
.Ss History | |||||
Not Done Inline ActionsThe '.Ns' macro here should not be needed if the '.Fx' and '.' do not have a space between them. gjb: The '.Ns' macro here should not be needed if the '.Fx' and '.' do not have a space between them. | |||||
On 14 May 2013, Oliver Pinter published to GitHub an initial patch to | |||||
implement ASLR. His work was inspired by Elad Efrat's work in NetBSD. | |||||
The patch was submitted to FreeBSD as a bug report on 24 Aug 2013. | |||||
Not Done Inline ActionsNew sentences should start on a new line. (Here, and throughout the remainder of the document.) gjb: New sentences should start on a new line. (Here, and throughout the remainder of the document.) | |||||
Independenty of Oliver's work, Shawn Webb posted to his tech blog that | |||||
he was interested in implementing ASLR for FreeBSD. Oliver found his | |||||
post and suggested that he and Shawn work together. On 08 Jun 2014, | |||||
preparatory work was committed to FreeBSD, adding Position-Independent | |||||
Not Done Inline ActionsDates in manual pages should be in '%B %d, %Y' format, from strftime(3). gjb: Dates in manual pages should be in '%B %d, %Y' format, from strftime(3). | |||||
Executable (PIE) support in base. PIE support was removed sometime | |||||
later. On 07 Apr 2014, SoldierX agreed to sponsor the project and | |||||
donated a sparc64 machine and a BeagleBone Black to Shawn Webb. This | |||||
hardware is used for testing and debugging ASLR. | |||||
rwatsonUnsubmitted Not Done Inline ActionsThis is probably too much detail for a History section; I'd be tempted to have just a sentence or two in the HISTORY section later, and suitable names added to the AUTHORS section. rwatson: This is probably too much detail for a History section; I'd be tempted to have just a sentence… | |||||
.Ss General Overview | |||||
When compiled with the PAX_ASLR option, systems will have ASLR | |||||
enabled. For systems with that kernel option enabled, if a user wants | |||||
to disable ASLR for a given application, the user must force that | |||||
application to opt-out. | |||||
Another kernel option, | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
.Cd PAX_SYSCTLS | |||||
.Ns , exposes additional | |||||
.Xr sysctl 8 | |||||
Not Done Inline Actions'.Ns' here is not necesssary. The comma should be on the previous line, with a space between it and 'PAX_SYSCTLS'. gjb: '.Ns' here is not necesssary. The comma should be on the previous line, with a space between… | |||||
tunables, allowing ASLR behavior control without requiring a reboot. | |||||
rwatsonUnsubmitted Not Done Inline ActionsThe term "tunable" usually refers to loader.conf tunables, which aren't quite the same as sysctls (although names can be present in both namespaces). rwatson: The term "tunable" usually refers to loader.conf tunables, which aren't quite the same as… | |||||
By default, the sysctl hardening.pax.aslr.status can only be changed | |||||
at boot time via /boot/loader.conf. Enabling the PAX_SYSCTLS kernel | |||||
option allows a root user to modify hardening.pax.aslr.status. See | |||||
Not Done Inline Actions'/boot/loader.conf' should be on its own line, prefixed with '.Fa', and a space separating the sentence stop. gjb: '/boot/loader.conf' should be on its own line, prefixed with '.Fa', and a space separating the… | |||||
Appendix A for a list of all the tunables. | |||||
ASLR tunables are per-jail and each jail inherits its parent jail's | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
settings. Having per-jail tunables allows more flexibility in | |||||
shared-hosting environments. This structure also allows a user to | |||||
selectively disable ASLR for applications that misbehave. | |||||
ASLR-disabled applications will still have policy-based security | |||||
applied to it by virtue of being jailed. | |||||
.Ss Implementation Details | |||||
A new sysinit subroutine ID, SI_SUB_PAX, initializes ASLR system | |||||
variables. Upon system boot, tunables from /boot/loader.conf are | |||||
checked for validity. Any invalid values generate a warning message to | |||||
Not Done Inline Actions'/boot/loader.conf' should be on its own line, prefixed with '.Fa', and a space separating the sentence stop. gjb: '/boot/loader.conf' should be on its own line, prefixed with '.Fa', and a space separating the… | |||||
the console and the tunable is set to a sensible default. | |||||
For the sake of performance, the ASLR system relies on per-process | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
deltas rather than calling | |||||
.Xr arc4random 3 | |||||
for each mapping. When a process calles | |||||
.Xr execve 2 | |||||
Not Done Inline Actionss/calles/calls/. gjb: s/calles/calls/. | |||||
.Ns , the ASLR deltas are initialized. Deltas are randomly generated | |||||
for the execution base, | |||||
Not Done Inline ActionsSame here with '.Ns', as noted for line 92. gjb: Same here with '.Ns', as noted for line 92. | |||||
.Xr mmap 2 | |||||
.Ns , and stack addresses. Only the execution base of applications | |||||
compiled as Position-Independent Executables (PIEs) is randomized. The | |||||
Not Done Inline ActionsSame here with '.Ns', as noted for line 92. gjb: Same here with '.Ns', as noted for line 92. | |||||
execution base of non-PIE applications is not modified. The mappings | |||||
of shared objects are randomized for both PIE and non-PIE | |||||
applications. | |||||
The deltas are used as a hint to the Virtual Memory (VM) system. The | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
VM system may modify the hint to make a better fit for superpages and | |||||
other alignment constraints. | |||||
The delta applied to the PIE execbase is different than the delta | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
applied to the base address of shared objects. In the Executable and | |||||
Linkable File (ELF) image handler, the execution base of PIE | |||||
applications is randomized by adding the delta controlled by the | |||||
hardening.pax.aslr.exec_len tunable to et_dyn_addr, which is | |||||
initialized to be ET_DYN_LOAD_ADDR (an architecture-dependent macro). | |||||
The base address of shared objects loaded by the dynamic linker are | |||||
randomized by applying the delta controlled by the | |||||
hardening.pax.aslr.mmap_len tunable in | |||||
.Fn sys_mmap | |||||
.Ns . | |||||
Stack randomization is implemented using a stack gap. On executable | |||||
image activation, the stack delta is computed and subtracted from the | |||||
top of the stack. | |||||
.Ss Further Enhancements | |||||
The existing gap-based stack randomization is not optimal. | |||||
Mapping-base stack randomization is more robust, but hard-coded kernel | |||||
structures and addresses, especially PS_STRINGS, will need to be | |||||
modified. The required changes to PS_STRINGS are major and will likely | |||||
touch userland along with the kernel. | |||||
The original PaX implementation, from which the | |||||
Not Done Inline ActionsThis should be '.Pp' instead of a blank line. gjb: This should be '.Pp' instead of a blank line. | |||||
.Fx | |||||
Not Done Inline ActionsShould this be 'PAX'? gjb: Should this be 'PAX'? | |||||
Not Done Inline ActionsNope. "Homepage of The PaX Team", see http://pax.grsecurity.net/ . op: Nope. "Homepage of The PaX Team", see http://pax.grsecurity.net/ . | |||||
implementation is inspired, uses a special ELF process header which | |||||
requires modification of executable files. The authors of the | |||||
.Fx | |||||
implementation have deliberately chosen to go a different route based | |||||
on the | |||||
.Xr mac 3 | |||||
framework. Support for filesystem extended attributes will be added at | |||||
a later time. | |||||
rwatsonUnsubmitted Not Done Inline ActionsUsually reference to future features is found in the BUGS section. rwatson: Usually reference to future features is found in the BUGS section. | |||||
.Sh APPENDIX A | |||||
rwatsonUnsubmitted Not Done Inline ActionsWould a more suitable section name be "Configuration"? rwatson: Would a more suitable section name be "Configuration"? | |||||
NOTE: All tunables can only be changed during boot-time via | |||||
/boot/loader.conf unless the kernel has been compiled with | |||||
.Cd PAX_SYSCTLS | |||||
.Ns . | |||||
.Bl -bullet | |||||
.It | |||||
hardening.pax.aslr.status | |||||
.Bl -dash -compact | |||||
.It | |||||
Type: integer | |||||
.It | |||||
Description: Toggle system-wide ASLR protection. | |||||
.It | |||||
Values: | |||||
.br | |||||
0 - ASLR disabled system-wide. Individual applications may | |||||
.Em NOT | |||||
opt in. | |||||
.br | |||||
1 - ASLR disabled but applications may opt in. | |||||
.br | |||||
2 - ASLR enabled and applications may opt out. | |||||
.br | |||||
3 - ASLR enabled for all applications. Applications may not opt out. | |||||
.It | |||||
Default: 2 | |||||
.El | |||||
.It | |||||
hardening.pax.aslr.exec_len | |||||
.Bl -dash -compact | |||||
.It | |||||
Type: integer | |||||
.It | |||||
Description: Set the number of bits to be randomized for the PIE | |||||
execbase. | |||||
.It | |||||
Values: | |||||
.br | |||||
For 32bit systems, minimum of 8, maximum of 21. For 64bit systems, | |||||
rwatsonUnsubmitted Not Done Inline Actions32-bit should be hyphenated -- here, and many other places, as should 64-bit, etc. rwatson: 32-bit should be hyphenated -- here, and many other places, as should 64-bit, etc. | |||||
minimum of 16, maximum of 42. | |||||
.It | |||||
Default: For 32bit systems: 14. For 64bit systems: 16. | |||||
.El | |||||
.It | |||||
hardening.pax.aslr.mmap_len | |||||
.Bl -dash -compact | |||||
.It | |||||
Type: integer | |||||
.It | |||||
Description: Set the number of bits to be randomized for | |||||
.Xr mmap 2 | |||||
calls. | |||||
.It | |||||
Values: | |||||
.br | |||||
For 32bit systems, minimum of 8, maximum of 21. For 64bit systems, | |||||
minimum of 16, maximum of 42. | |||||
.It | |||||
Default: For 32bit systems: 14. For 64bit systems: 21. | |||||
.El | |||||
.It | |||||
hardening.pax.aslr.stack_len | |||||
.Bl -dash -compact | |||||
.It | |||||
Type: integer | |||||
.It | |||||
Description: Set the number of bits to be randomized for the stack. | |||||
.It | |||||
Values: | |||||
.br | |||||
For 32bit systems, minimum of 8, maximum of 21. For 64bit systems, | |||||
minimum of 16, maximum of 42. | |||||
.It | |||||
Default: For 32bit systems: 8. For 64bit systems: 16. | |||||
.El | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr elf 3 , | |||||
.Xr mac 3 , | |||||
rwatsonUnsubmitted Not Done Inline ActionsDo you mean mac(3) or mac(4)? rwatson: Do you mean mac(3) or mac(4)? | |||||
.Xr mmap 2 | |||||
.Rs | |||||
Not Done Inline ActionsManual page references should be sorted alphabetically and by manual page section. mmap(2) reference here should be first, mac(3) last. gjb: Manual page references should be sorted alphabetically and by manual page section. mmap(2)… | |||||
.%T "PaX ASLR" | |||||
.%U http://pax.grsecurity.net/docs/aslr.txt | |||||
.Re | |||||
.Rs | |||||
.%T "FreeBSD ASLR Bug Report" | |||||
.%U https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=181497 | |||||
rwatsonUnsubmitted Not Done Inline ActionsIt's not clear if bugzilla URLs are a sufficiently permanent to cite in a man page. rwatson: It's not clear if bugzilla URLs are a sufficiently permanent to cite in a man page. | |||||
.Re | |||||
.Rs | |||||
.%T "HardenedBSD" | |||||
.%U http://hardenedbsd.org/ | |||||
.Re | |||||
.Rs | |||||
.%T "secadm" | |||||
.%U https://github.com/HardenedBSD/secadm | |||||
.Re | |||||
.Sh HISTORY | |||||
ASLR was first introduced in HardenedBSD and work is ongoing to | |||||
upstream to | |||||
.Fx 11.0-CURRENT. | |||||
rwatsonUnsubmitted Not Done Inline ActionsI'd shift the above history down here, and remove this bit -- if this is a commit candidate, then it doesn't belong in the patch. rwatson: I'd shift the above history down here, and remove this bit -- if this is a commit candidate… | |||||
.Sh AUTHORS | |||||
Not Done Inline ActionsThis sentence should be fixed prior to committing to the FreeBSD source tree to reflect the first release it was included ('.Fx 11.0-RELEASE'). gjb: This sentence should be fixed prior to committing to the FreeBSD source tree to reflect the… | |||||
This manual page was written by | |||||
.An -nosplit | |||||
.An Shawn Webb . | |||||
The ASLR implementation was written by | |||||
.An Oliver Pinter and | |||||
.An Shawn Webb . | |||||
.Sh BUGS | |||||
No known bugs at this time. | |||||
rwatsonUnsubmitted Not Done Inline ActionsThis is usually where commentary on implementation choices that might change in the future goes. rwatson: This is usually where commentary on implementation choices that might change in the future goes. |
This man page contains a large number of style violations -- see mdoc(7) for a number of suggestions including: