README.md

# mxshadow

This installs:

* /lib/libnss_mxshadow.so.2 : nss service to query shadow entries via TLS from a server
* /usr/sbin/mxshadowsrv : The server

### Configuration of the nss service

At runtime, the nss service needs these files:

* /etc/mxshadow.conf : Configuration file containing server address and port
* /etc/mxshadow.cert.pem :  Certificate to verify the server

The format of the configuration file is
~~~
# address and port of mxshadow server

server = 141.14.16.131
port = 872
~~~

## Configuration of the server

At runtime, the server needs the certificate file and the related key file. These are specified via its command line:

    mxshadowsrv --key-file FILENAME --cert-file FILENAME [--address ADDRESS] [--port PORT} SHADOW-FILEANME

The server monitors the shadow file for changes and will re-read it if it is changed or replaced.

## Tools

The source package contains these tools, which are build but not installed:

* create-key.sh : Shell script to create key and certificat for the server
* test_server : Standalone program to query the server ( usage: test_server username )
* test_query_shadow: Standalone program to test getspnam (usage: test_query_shadow username )

# Mariux:

* This package is installed from a bee file
* The key and cert files have been generated with `create-key.sh`
* `/etc/mxshadow.conf` and `/etc/mxshadow.cert.pem` are installed from mxtools.
* A systemd service unit `/etc/systemd/system/mxshadow.service` to run the server is also installed from mxtools.
* The Makefile in `/package/nis/src` generates a shadow map `/package/nis/var/shadow`
* The key and certificate files for the server are stored in /package/nis/etc/

## Password authentication overview

1. Tools like login, su or sshd which want to do password authentication, use the PAM library. See pam(8).
2. pam reads config files, e.g. `/etc/pamd.d/sshd`
3. These file deletegate to pam module plugins. E.g. with `auth required pam_unix.so`
4. `pam_unix.so` uses `getpwent()` and `getspent()` from glibc.
5. glibc reads the configuration file `/etc/nsswitch.conf`
6. This file delegates to nss service providers, e.g. `shadow: files mxshadow` for `libnss_files.so.2` and `libnss_mxshadow.so.2`