From 4ba5ae5776c2e9ba4f297115c19923a928cf3e87 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 20 Nov 2017 14:51:36 +0000 Subject: Initial release / rename to utmps --- doc/index.html | 132 +++++++++++++++++++++++++++++++++++++ doc/libutmps/index.html | 171 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/overview.html | 109 ++++++++++++++++++++++++++++++ doc/upgrade.html | 28 ++++++++ doc/utmps-utmpd.html | 77 ++++++++++++++++++++++ doc/utmps-wtmpd.html | 78 ++++++++++++++++++++++ 6 files changed, 595 insertions(+) create mode 100644 doc/index.html create mode 100644 doc/libutmps/index.html create mode 100644 doc/overview.html create mode 100644 doc/upgrade.html create mode 100644 doc/utmps-utmpd.html create mode 100644 doc/utmps-wtmpd.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..8d080da --- /dev/null +++ b/doc/index.html @@ -0,0 +1,132 @@ + + + + + + utmps - a secure utmp implementation + + + + + + +

+Software
+skarnet.org +

+ +

utmps

+ +

What is it ?

+ +

+ utmps is an implementation of the utmp.h and utmpx.h +family of functions performing user accounting on Unix systems. +

+ +

+ Traditionally, utmp functionality is provided by the system's +libc. However, not all libcs implement utmp: for instance the +musl libc, on Linux, does not. The +main reason for it is that utmp functionality is difficult to +implement in a secure way; in particular, it is impossible to implement +without either running a daemon or allowing arbitrary programs to tamper +with user accounting. +

+ +

+ utmps is a secure implementation of user accounting, using +a daemon as the only authority to manage the utmp and wtmp data; programs +running utmp functions are just clients to this daemon. +

+ +
+ + + +
+ +

Installation

+ +

Requirements

+ + + +

Licensing

+ +

+ s6 is free software. It is available under the +ISC license. +

+ +

Download

+ + + +

Compilation

+ + + +

Upgrade notes

+ + + +
+ +

Reference

+ +

Commands

+ + + +

Libraries

+ + + +
+ + +

Related resources

+ + +

utmps discussion

+ + + + + diff --git a/doc/libutmps/index.html b/doc/libutmps/index.html new file mode 100644 index 0000000..0372726 --- /dev/null +++ b/doc/libutmps/index.html @@ -0,0 +1,171 @@ + + + + + + utmps: the utmps library interface + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

The utmps library interface

+ +

General information

+ +

+ libutmps is a client library meant to be used by client +programs needing utmp functionality. It interacts with the +utmps-utmpd and +utmps-wtmpd daemons. +

+ +

+ Application programs can use it directly, but most existing programs +simply use the standard +utmpx.h +interface, which in utmps is implemented as a series of thin wrappers +around the utmps library. +

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

+ Check the utmps/utmps.h header for the exact function list, +and the utmps/utmpx.h header for the definition of the standard +struct utmpx data type. +

+ +

Synchronous functions with a specified maximum execution time

+ +

+ The standard utmpx.h functions are fully synchronous. They were not +initially meant to perform inter-processus communication; however, in +utmps, they do. Their synchronous nature is obviously not changed here, +but the underlying utmps functions use a safety mechanism to bound their +execution time in case daemons fail to respond. This mechanism is described, +for instance, +here. +

+ +

Starting and ending a session

+ +

+int utmps_start (utmps *a, char const *path, tain_t const *deadline, tain_t *stamp)
+Connects to a utmps-utmpd service listening on a Unix domain socket at path. +a must point to a previously allocated utmps object, which is flat and can +be allocated in the stack. This object must have been initialized to UTMPS_ZERO before the call. +a will be a handle describing the session, and must be given to all utmps functions +called in that session. +deadline and stamp are used to bound the execution time as described in the +above link. The function returns 1 if it succeeds; it returns 0, and sets errno, if it fails. +

+ +

+void utmps_end (utmps *a)
+Ends the session described by a, and releases all used resources. +

+ +

Reading from the utmp database

+ +

+ Any user authorized to connect to the utmpd service can call these functions. In other +words, if utmps_start() succeeded, then these functions should not fail due to +insufficient permissions. +

+ +

+int utmps_rewind (utmps *a, tain_t const *deadline, tain_t *stamp)
+Performs the setutxent() functionality on the utmp database addressed via a, +i.e. sets the internal pointer at the start of the database. +On success, stores the result into *b and returns 1. On failure, returns 0 and sets errno. +

+ +

+int utmps_getent (utmps *a, struct utmpx *b, tain_t const *deadline, tain_t *stamp)
+Performs the getutxent() functionality on the utmp database addressed via a. +On success, stores the result into *b and returns 1. On failure, returns 0 and sets errno. +

+ +

+int utmps_getid (utmps *a, unsigned short type, char const *id, struct utmpx *b, tain_t const *deadline, tain_t *stamp)
+Performs the getutxid() functionality on the utmp database addressed via a, +using ut_type type and ut_id id. id must be a null-terminated +string; only its first UTMPS_UT_IDSIZE-1 characters will be taken into account. +On success, the function stores the result into *b and returns 1. On failure, +it returns 0 and sets errno. +

+ +

+int utmps_getline (utmps *a, char const *line, struct utmpx *b, tain_t const *deadline, tain_t *stamp)
+Performs the getutxline() functionality on the utmp database addressed via a, +using ut_line line. line must be a null-terminated +string; only its first UTMPS_UT_LINESIZE-1 characters will be taken into account. +On success, the function stores the result into *b and returns 1. On failure, +it returns 0 and sets errno. +

+ +

Writing to the utmp database

+ +

+ Currently, only the super-user is allowed to use this function. +

+ +

+int utmps_putline (utmps *a, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)
+Performs the pututxline() functionality on the utmp database addressed via a, +i.e. writes the *b structure into the utmp database looking for an appropriate +record to replace, and appending to the database if no such record can be found. +On success, the function returns 1. On failure, it returns 0 and sets errno. +

+ +

Writing to the wtmp database

+ +

+int utmps_updwtmpx (char const *path, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)
+Unlike the previous functions, utmps_updwtmpx() does not use a utmps handle, because +it does not connect to an utmpd service. Instead, it connects to a wtmpd service listening +on Unix domain socket path, once for every call. It appends the *b structure +to the wtmp database, returning 1 on success and 0 (and setting errno) on failure. +

+ +

+ utmps_updwtmpx() will only succeed if the caller is root, or if +b→ut_user resolves (according to getpwnam()) to the +effective uid of the caller. In other words: users can append phony records +for themselves, but not for others, and only root can spoof the whole +wtmp database. +

+ + + diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..22e9210 --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,109 @@ + + + + + + utmps: an overview + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

An overview of utmps

+ +

+ utmps is a secure implementation of the utmp functionality, i.e. +user accounting on Unix systems. It includes full POSIX +utmpx.h +functionality, a few extensions created by GNU, and an underlying +C client library with better error reporting +than the POSIX interface specifies. +

+ +

The issues with traditional utmp

+ +

+ Traditional utmp implementations, as performed by most Unix +libcs, are woefully insecure. The fundamental issue with utmp +is that it requires user programs to write to files (the utmp or wtmp +databases) owned by either root or a specific system user. That means +having the suid bit set on programs using it. +

+ +

The utmps solution

+ +

+ utmps uses the age old Unix client-server model, following the +adage "one resource → one daemon". It provides two daemons, +utmps-utmpd and +utmps-wtmpd, which should be the only +programs allowed to access the utmp and wtmp databases respectively. +It provides the +utmps client library to communicate with +those daemons; and it implements the +utmpx.h +interfaces, and the extensions, as wrappers for this client library. +

+ +

Authentication, local services and superservers

+ +

+utmps-utmpd and +utmps-wtmpd do not listen to the +network themselves. They are designed to serve only one client +connection, following the +UCSPI model - +also known as the inetd model. To implement the utmpd and wtmpd +local services, +a Unix domain superserver such as +s6-ipcserver +is required. s6-ipcserver listens to a socket, and spawns a +utmps-utmpd process when a client +calls setutxent() +for instance. +

+ +

+ The utmpd and wtmpd services must be started at boot time in +order for utmp calls to succeed. The examples/ subdirectory +of the utmps package has examples on how to start those services +when using the +s6 supervision suite, +the s6-rc service manager, or +the OpenRC service manager. +

+ +

+ This model has advantages and drawbacks. The main drawback is that it requires +a daemon to be running in order for the system to provide full POSIX +functionality. The main advantage, on the other hand, is that no program +needs to be suid or sgid, and permissions can actually be quite fine-grained. +

+ + + +

+ All in all, I believe the flexibility it offers overweighs the inconvenience +of having to run services before providing utmp/wtmp. +

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..b5c9db9 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ + + + + + + How to upgrade utmps + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

What has changed in utmps

+ +

in 0.0.1.0

+ +

+ Initial release. +

+ + + diff --git a/doc/utmps-utmpd.html b/doc/utmps-utmpd.html new file mode 100644 index 0000000..57fa6ac --- /dev/null +++ b/doc/utmps-utmpd.html @@ -0,0 +1,77 @@ + + + + + + utmps: the utmps-utmpd program + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

The utmps-utmpd program

+ +

+utmps-utmpd manages the utmp database. It expects to be able to create, read and +modify a file named utmp in the directory it is launched in. +

+ +

+ It is not meant to be called directly; instead, it is expected to be run from +a script as a part of a "utmpd" +local service. +

+ +

+ The examples/ subdirectory of the utmps package provides examples +on how to run such a service. + The simplest way to do so, for testing purposes, is a command line such as: +

+
s6-ipcserver -l0 utmpd-socket utmps-utmpd
+

+ while being in the /run/utmps directory. +

+ +

+/run/utmps/utmpd-socket is the default place where utmps's +implementation of the utmpx.h functions expects the utmpd +service to be. It can be changed at build time by giving the +--with-utmp-socket=PATH option to configure. +

+ +

+ utmps-utmpd does not listen to the socket itself: it reads from its +standard input and writes to its standard output. It relies +on a superserver such as +s6-ipcserver +to manage connections to the socket. An instance of utmps-utmpd is run +for every client connection; +every instance reads the effective uid of the client in an environment +variable set by the superserver, which allows it to filter operations - +for instance, it allows any user to read from the database but it only +allows root to write to it. +

+ +

+ If more fine-grained authorizations are required (only allowing +certain users and groups to connect to the service), the superserver +can be configured to enforce them. +

+ +

+ utmps-utmpd does not need to run as root, provided it can write its file; +it is recommended to create a utmp user and group, dedicated to +utmps-utmpd and +utmps-wtmpd operation, and run the +superserver as this user and group. +

+ + + diff --git a/doc/utmps-wtmpd.html b/doc/utmps-wtmpd.html new file mode 100644 index 0000000..a1e090b --- /dev/null +++ b/doc/utmps-wtmpd.html @@ -0,0 +1,78 @@ + + + + + + utmps: the utmps-wtmpd program + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

The utmps-wtmpd program

+ +

+utmps-wtmpd manages the wtmp database. It expects to be able to create, read and +modify a file named wtmp in the directory it is launched in. +

+ +

+ It is not meant to be called directly; instead, it is expected to be run from +a script as a part of a "wtmpd" +local service. +

+ +

+ The examples/ subdirectory of the utmps package provides examples +on how to run such a service. + The simplest way to do so, for testing purposes, is a command line such as: +

+
s6-ipcserver -l0 utmpd-socket utmps-wtmpd
+

+ while being in the /run/utmps directory. +

+ +

+/run/utmps/wtmpd-socket is the default place where utmps's +implementation of the updwtmpx() function expects the wtmpd +service to be. It can be changed at build time by giving the +--with-wtmp-socket=PATH option to configure. +

+ +

+ utmps-wtmpd does not listen to the socket itself: it reads from its +standard input and writes to its standard output. It relies +on a superserver such as +s6-ipcserver +to manage connections to the socket. An instance of utmps-wtmpd is run +for every client connection; +every instance reads the effective uid of the client in an environment +variable set by the superserver, which allows it to filter operations: +only lines whose ut_user field resolves to the effective uid of +the client will be appended to the database. +

+ +

+ If more fine-grained authorizations are required (only allowing +certain users and groups to connect to the service), the superserver +can be configured to enforce them. For instance, it is possible to +tell s6-ipcserver to only accept connections from root. +

+ +

+ utmps-wtmpd does not need to run as root, provided it can write its file; +it is recommended to create a utmp user and group, dedicated to +utmps-wtmpd and +utmps-utmpd operation, and run the +superserver as this user and group. +

+ + + -- cgit v1.3.1