diff --git a/libc/Makefile b/libc/Makefile index 870591cb..7d76ebd7 100644 --- a/libc/Makefile +++ b/libc/Makefile @@ -751,6 +751,9 @@ crtn.o \ MISCOBJ=\ $(CRTOBJ) \ +MANPAGES2=\ +scram/scram.2 + HEADERS:=$(shell find include -type f) LIBK_OBJS:=$(FREEOBJS:.o=.libk.o) @@ -774,7 +777,7 @@ libs: $(BINS) libs-kernel: $(BINSKERNEL) .PHONY: all libs headers clean install install-include-dirs install-headers \ - install-lib-dirs install-libs libs-kernel + install-lib-dirs install-libs install-man libs-kernel FORCE: @@ -834,7 +837,7 @@ clean: rm -f *.o */*.o */*/*.o *.a # Installation into sysroot -install: install-headers install-libs install-libs-kernel +install: install-headers install-libs install-libs-kernel install-man $(DESTDIR)$(LIBDIR): mkdir -p $@ @@ -857,3 +860,7 @@ install-lib-dirs: $(DESTDIR)$(LIBDIR) install-libs: $(INSTALLLIBS) install-libs-kernel: $(INSTALLLIBSKERNEL) + +install-man: + mkdir -p $(DESTDIR)$(MANDIR)/man2 + cp $(MANPAGES2) $(DESTDIR)$(MANDIR)/man2 diff --git a/libc/scram/scram.2 b/libc/scram/scram.2 new file mode 100644 index 00000000..a4cf10eb --- /dev/null +++ b/libc/scram/scram.2 @@ -0,0 +1,113 @@ +.Dd February 8, 2017 +.Dt SCRAM 2 +.Os +.Sh NAME +.Nm scram +.Nd emergency process shutdown +.Sh SYNOPSIS +.In scram.h +.Ft void +.Fn scram "int event" "const void *info" +.Sh DESCRIPTION +.Fn scram +unconditionally terminates the process abnormally due to the specified event. +It is designed for use when the process has potentially been compromised and +therefore can’t possibly continue safely. +Its use does not necessarily mean the process was compromised, but it does imply +a bug was detected. +.Pp +The event information structures are designed to be trivially to filled in +during an emergency with the information that is readily available. +If the process has potentially been compromised, the calling function should not +do any formatting of debug information or perform memory allocations, but just +use existing values or constants as the event information and call +.Fn scram +to terminate the process immediately. +The kernel will use the provided event information to write a formatted error +message to the kernel log. +.Pp +.Fa event +specifies which kind of event occurred and can be one of: +.Pp +.Bl -tag -width "SCRAM_UNDEFINED_BEHAVIOR" -compact -offset indent +.It SCRAM_ASSERT +Assertion failure. +.It SCRAM_STACK_SMASH +Stack smash. +.It SCRAM_UNDEFINED_BEHAVIOR +Undefined behavior. +.El +.Pp +.Fa info +points to the appropriate structure containing further information on the event +or +.Dv NULL +if there is no information available: +.Bd -literal +struct scram_assert { /* SCRAM_ASSERT */ + const char *filename; /* file the assertion failed in */ + unsigned long line; /* line the assertion failed on */ + const char *function; /* function containing the assertion */ + const char *expression; /* assertion expression */ +}; + +/* SCRAM_STACK_SMASH has no information structure */ + +struct scram_undefined_behavior { /* SCRAM_UNDEFINED_BEHAVIOR */ + const char *filename; /* file with undefined behavior */ + unsigned long line; /* line with undefined behavior */ + unsigned long column; /* column on the line with undefined behavior */ + const char *violation; /* description of the undefined behavior */ +}; +.Ed +.Sh RETURN VALUES +The +.Fn scram +function never returns as the process is unconditionally terminated. +.Sh ERRORS +.Fn scram +never fails as the process is always terminated, even on invalid parameters. +The kernel may fail to allocate copies of strings, in which case "" is +used as a replacement in the error message. +.Sh NOTES +.Fn scram +is generally not meant to be used directly by application developers, but is for +internal use by the standard library in the implementation of +.Xr assert 3 , +the stack protector +.Xr ( gcc 1 +.Fl fstack-protector ) , +and the undefined behavior sanitizer +.Xr ( gcc 1 +.Fl fsanitize=undefined ) . +The design of +.Fn scram +is motivated by gcc's upstream libssp and libubsan libraries, which attempt to +print debug information prior to terminating the process abnormally. +Doing so is a risk, as the process may have been compromised and basic things +like stdio cannot be trusted as crucial pointers and state may have been +overwritten, and memory allocations are dangerous because the heap might be +damaged. +Attempting to format debug information may ironically give the attacker another +chance to subvert control flow. +The gcc upstream libubsan library is designed for debugging and should not go +anywhere near production. +.Pp +The +.Fn scram +function avoids all these issues by design by having the kernel print the debug +information. +Sortix uses neither gcc library and the standard library has its own secure +implementations using +.Fn scram . +It is always safe and desirable to use these features in production on Sortix. +.Sh SEE ALSO +.Xr gcc 1 , +.Xr _exit 2 , +.Xr exit_thread 2 , +.Xr assert 3 , +.Xr exit 3 +.Sh HISTORY +The +.Fn scram +system call originally appeared in Sortix 1.0.