Need help with shadowd?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

362 Stars 30 Forks 117 Commits 2 Opened issues


Secure login distribution service

Services available


Need anything else?

Contributors list


shadow horse

shadowd is the secure login distribution service, which consists of two parts: server and client.

In a typical server configuration case you should manually update the

and copy it on all servers (or via automatic configuration system); afterwards each server will have same hash in the
. Supposed that attacker successfully gained access to one of your servers and found collision to that single hash attacker actually got access to all servers with that hash.

shadowd is summoned to solve that obscure problem.

shadowd solution is to generate hash tables for specified passwords mixed with random salt for specified users and guarantee that a client receive unique hash.

One shadowd instance can be used for securely instanciate thousands of servers with same root password for each one. Without any doubts about possible break-in.

If attacker has user (non-root) access to the one server and try to repeat request to shadowd server and get actual hash during the hash TTL period (one day by default), then shadowd will give him another unique hash entry. Actually, shadowd can give only two unique hash entries for hash TTL period for one client, first hash entry may be received only for first request per hash TTL period, all other requests will be served by another hash.

If attacker has root access to the one server and will try to brute-force hash entry for root from

, it will not give him any access for other servers with same password, because shadowd will give different hashes for each server.

If attacker will gain root access to the shadowd server (worst-case scenario), it's will be very time-consuming to brute-force thousands of hashes without any knowledge about which server is using specific hash entry.

shadowd can act as SSH keys publisher too.

shadowd can also configure with passwords containers or any other type of nodes in your infrastructure.

REST API is used for communication between server and client.



Why not LDAP/AD/SSSD/Whatever?

LDAP/AD/SSSD is monstrous software which requires massive configuration. It's far from just installing package to make it work. LDAP by itself just ugly, it's not so "lightweight" as it supposed to be from it's name.

shadowd is very easy to install and do not even have configuration file.

In comparison to LDAP, shadowd is not a remote authorisation provider, so when network or shadowd host will go down, you still will be able to login on concrete hosts configured with shadowc, because all shadow hashes stored locally on concrete host.

Isn't attacker will brute-force actual password faster instead of finding a collision in SHA?

It is possible indeed, but having sufficiently long password like

( will neglect this probability.

What is actual use case for this?

Local authentication as well as password authentication should be always possible for ops engineers. If something wrong goes with LDAP or any other remote authentication agent, you will blame that day you integrated it into your environment.

There is no way of configuring local root (like, available only through IPMI) on the frontend load-balancing servers through remote authorisation agent.

shadowd can be safely used for setting root password even on load-balancing servers.

shadowd configuration

  1. Generate hash tables
  2. Generate SSL certificates
  3. Start shadowd
  4. Adding SSH keys

Hash Tables

For generating hash table you should run:

shadowd [options] -G  [-n ] [-a ]
shadowd will prompt for a password for specified user token, and after that will generate hash table with 2048 hashed entries of specified password, hash table size can be specified via flag
will be used as default hashing algorithm, but
can be used via
-a sha512

Actually, user token can be same as login, but if you want to use several passwords for same username on different servers, you should specify

 it is name of role (
for example).

Already running instance of shadowd do not require reload to serve newly generated hash-tables.

loading message

SSL certificates

Assume that attacker gained access to your servers, then he can wait for next password update and do man-in-the-middle attack, afterwards passwords on servers will be changed on his password and he will get more access to the servers.

For solving that problem one should use SSL certificates, which confirms authority of the login distribution server.

For generating SSL certificates you should have trusted host (shadowd server DNS name) or trusted ip address, if you will use localhost for shadowd server, you can skip this step and shadowd will automatically specify current hostname and ip address as trusted, in other cases you should pass options for setting trusted hosts/addresses of shadowd.

Possible Options: -

-h --host 
- set specified host as trusted. (default: current hostname) -
-i --address 
- set specified ip address as trusted. (default: current ip address) -
-d --till 
- set time certicicate valid till (default: current date plus one year). -
-b --bytes 
- set specified length of RSA key. (default: 2048)

And for all of this you should run one command:

shadowd [options] -C [-h ...] [-i ...] [-d ] [-b ]


will be stored in
directory, which location can be changed through flag

Since client needs certificate, you should copy

on server with client to

shadowd will generate certificate with default parameters (can be seen in program usage) on it's first run.

Start shadowd

As mentioned earlier, shadowd uses REST API, by default listening on

, but you can set specified address and port through passing argument
shadowd [options] -L  [-s 

For setting hash TTL duration you should pass

argument, by default hash TTL is

TTL is amount of time after which shadowd will serve different unique pair of hash entries to the same requesting client.

General options:

  • -c -certs 
    - use specified directory for storing and reading certificates.
  • -t --tables 
    - use specified directory for storing and reading hash tables. (default: /var/shadowd/ht/)
  • -k --keys 
    - use specified dir for reading ssh-keys. (default: /var/shadowd/ssh/).

Success, you have configured server, but you need to configure client, for this you should see documentation here.

Adding SSH keys

shadowd can act as public ssh keys distribution service. Keys can be added per token by using command:

shadowd -K 

After that command shadowd will wait for public SSH key to be entered on stdin. Then, specified key will be added to keys list, which is stored under the directory, set by

flag (
by default).

Optionally, key file can be truncated by using flag

-r --truncate
to the standard

shadowd will serve that keys by HTTP, as mentioned in following section.


shadowd can work in multiple instance mode, but it requires to use external storage – MongoDB.

shadowd will store/read shadow entries and public ssh key from mongodb, so all of your need is configure mongodb cluster, setup replication and place shadowd configuration file using following syntax:

use = "mongodb"
dsn = "mongodb://[user[:password]@]host[,[user2[:password2]@]host2]/dbname"

shadowd's' configuration file can be specified using

-f --config 


shadowd offers following REST API:

  • /t/
    , where token can be any string, possibly containing slashes. Most common interpretation for
    , e.g.

on this URL will return unique hash for specified
  pre-generated via 
shadowd -G
hash-table. The first requested hash guaranteed to be unique among different hosts, The second and later
requests will return same hash again and again until
 is configured on server by 
flag. Working in that way shadowd offers secure way of transmitting one hash only once, and legitimate client (e.g. shadowc) can always be sure that hash, obtained from shadowd, has not been transferred to someone else on that host.
  • /ssh/
    , where
     is same as above.

on this URL will return SSH keys, that has been added by
shadowd -K
command in
format (e.g. key per line).

No special security restrictions apply on that requests.

  • /v//
    , where
     is same as above, 
    hash of a password, if 
    ) then the last part of URI will be used as

on this URL will return HTTP status
200 OK
if specified hash exists in hash table for specified token, in other case,
404 Not
will be returned.

No special security restrictions apply on that requests.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.