From 585254a8e1745efcb2cd0b199ba4f8754571bae1 Mon Sep 17 00:00:00 2001 From: Philip Guenther Date: Tue, 25 Aug 2015 19:58:05 +0000 Subject: Document kbind(2) --- lib/libc/sys/Makefile.inc | 4 +- lib/libc/sys/kbind.2 | 120 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 lib/libc/sys/kbind.2 (limited to 'lib') diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index fe791fd83ff..d1513a50240 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.126 2015/07/19 02:37:29 deraadt Exp $ +# $OpenBSD: Makefile.inc,v 1.127 2015/08/25 19:58:04 guenther Exp $ # $NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $ # @(#)Makefile.inc 8.1 (Berkeley) 6/17/93 @@ -206,7 +206,7 @@ MAN+= __get_tcb.2 __thrsigdivert.2 __thrsleep.2 _exit.2 accept.2 \ getpeername.2 getpgrp.2 getpid.2 getpriority.2 getrlimit.2 \ getrtable.2 getrusage.2 getsid.2 getsockname.2 getsockopt.2 \ getthrid.2 gettimeofday.2 getuid.2 intro.2 ioctl.2 issetugid.2 \ - kill.2 kqueue.2 ktrace.2 link.2 listen.2 lseek.2 madvise.2 \ + kbind.2 kill.2 kqueue.2 ktrace.2 link.2 listen.2 lseek.2 madvise.2 \ mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 \ mlockall.2 mmap.2 mount.2 mprotect.2 mquery.2 msgctl.2 \ msgget.2 msgrcv.2 msgsnd.2 msync.2 munmap.2 nanosleep.2 \ diff --git a/lib/libc/sys/kbind.2 b/lib/libc/sys/kbind.2 new file mode 100644 index 00000000000..4a9fe239d6a --- /dev/null +++ b/lib/libc/sys/kbind.2 @@ -0,0 +1,120 @@ +.\" $OpenBSD: kbind.2,v 1.1 2015/08/25 19:58:04 guenther Exp $ +.\" +.\" Copyright (c) 2015 Philip Guenther +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 25 2015 $ +.Dt KBIND 2 +.Os +.Sh NAME +.Nm kbind +.Nd update protected memory for lazy-binding +.Sh SYNOPSIS +.In sys/unistd.h +.Bd -literal +struct __kbind { + void *kb_addr; + size_t kb_size; +}; +#define KBIND_BLOCK_MAX 2 /* powerpc, sparc, and sparc64 need 2 blocks */ +#define KBIND_DATA_MAX 24 /* sparc64 needs 6, four-byte words */ +.Ed +.Pp +.Ft int +.Fn kbind "const struct __kbind *param" "size_t psize" "int64_t cookie" +.Sh DESCRIPTION +The +.Nm +syscall updates the contents of one or more blocks of the process's memory +with the supplied replacement data. +This is used to efficiently and securely perform lazy-binding. +.Pp +.Fa param +points to an array of +.Vt __kbind +structures giving the addresses and lengths to update. +The last +.Vt __kbind +structure is immediately followed in the same order by the source +data for the blocks to copy. +.Fa psize +specifies the total length of the parameters: both the +.Vt __kbind +structures and the associated source data. +There may be at most +.Dv KBIND_BLOCK_MAX +.Vt __kbind +structures and each block may be at most +.Dv KBIND_DATA_MAX +bytes in size. +.Pp +.Nm +updates memory +.Do +as if +.Dc +the thread temporarily made the memory writable with +.Xr mprotect 2 . +If the process does not have write access to the underlying memory object, +.Nm +will fail without making the requested change. +.Pp +.Nm +is currently intended for use by +.Xr ld.so 1 +only. +It is therefore not provided as a function and two security checks +are performed to bind it (pun intended) to its use in +.Xr ld.so 1 : +the first time +.Nm +is used, the kernel records both the text address of the call and +the value of the +.Fa cookie +argument. +If those values differ in a latter +.Nm +call, then the process is killed. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn kbind +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Cannot allocate memory when updating a copy-on-write page. +.It Bq Er EINVAL +The parameters are inconsistent or exceed +.Nm +limits. +.It Bq Er EFAULT +Part of the structures or additional data pointed to by +.Fa param +is outside the process's allocated address space, +or the underlying memory object is not writable. +.El +.Sh SEE ALSO +.Xr ld.so 1 , +.Xr mprotect 2 +.Sh STANDARDS +The +.Nm +syscall is specific to the +.Ox +dynamic linker and should not be used in portable applications. +.Sh HISTORY +The +.Nm +syscall appeared in +.Ox 5.8 . -- cgit v1.2.3