bdisk/docs/manual/further/PASSWORDS.adoc

== Passwords
NOTE: If you're specifying passwords, be sure to use a https://www.schneier.com/blog/archives/2014/03/choosing_secure_1.html[strong password^]!

=== `build.ini` Password Value Examples
Passwords work a little interestingly in BDisk. These aspects all apply to both <<__code_root_password_code,the root password>> and <<__code_passwowrd_code,the user password>> (if you enable a regular user).

CAUTION: DO *NOT* USE A PLAINTEXT PASSWORD IN THE `build.ini`! This is _by design_; plaintext passwords are much more insecure. If you use a plaintext password, it *will not work*.

WARNING: Remember to <<_escaping_the_salted_hash,escape your hash>> before placing it in your `build.ini`!

.Password Value Scheme
[frame="topbot",options="header,footer"]
|======================
|If you have...|BDisk will...
|the string `BLANK`|give the user a blank password, allowing you to just hit `<Enter>` to log in
|nothing set|lock the account (e.g. no non-SSH login is possible)
|a properly hashed, salted, and escaped string|set the account to the password used to generate that hash.
||
|======================

.Password Value Examples
[frame="topbot",options="header,footer"]
|======================
|If the value is...|Then BDisk...
|`root_password = BLANK`|will let you log into the TTY as the root user by just hitting the `<Enter>` key.
|`root_password =`|will not allow the root user to log into the TTY at all.
|`root_password = <some salted, hashed, escaped string created from 'test'>`|will let you log into the root user on a TTY with the password `test`.
||
|======================


NOTE: I specify "TTY login" because SSH login may still be possible. By default, SSH will allow password logins for non-root users (root user SSH password login is prohibited by default; only pubkey login for root is allowed.) -- this can be overridden, however, by customization.

=== Generating a Password Salt/Hash
First, if you are not familiar with a http://man7.org/linux/man-pages/man3/crypt.3.html#NOTES[salted hash^] that GNU/Linux uses, you may want to learn about it.

That said, there are utilities in `extra/bin/` that should generate a salted hash for you. Currently only `hashgen.py` is distributed, but additions/examples for other languages are welcome.

....
 $ ./hashgen.py 
 
 What password would you like to hash/salt?
 (NOTE: will NOT echo back!)
 
 
 Your salted hash is:
 	$6$t92Uvm1ETLocDb1D$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/
 
....

The password `test` was used above. In `crypt(3)`-salted hashes, there are specific sections separated by USD dollar symbols (`$`). The first section (containing `6`) marks the *hash algorithm* -- in this case, _SHA512_. (The http://man7.org/linux/man-pages/man3/crypt.3.html#NOTES[crypt man page^] mentions all supported hash types and their corresponding ID.) The next section, `t92Uvm1ETLocDb1D`, is the *salt*. The last section is the *hash*. How salted hashes work is an original piece of data is given (in our case, the word `test`). This data is then sent through a one-way cryptographic process that generates a new string that makes it difficult to know what the original data was. THEN a salt is added- a random string- and the process repeats. In our format, this is done _5000_ times in a row. When you log in with your password, the salt is fetched and the same process is done again- predictably, the data that process goes through should then match the salted hash string stored in the password system (in this case, the https://linux.die.net/man/5/shadow[`/etc/shadow`] file).

Whew! Got all that? Good.

=== Escaping the Salted Hash
One last thing, and this is *very* important -- failure to perform this step will cause all sorts of strange Python errors -- is to escape the salted hash. Thankfully, however, this is a lot easier than it sounds.

So we have our salted hash: `$6$t92Uvm1ETLocDb1D$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/`. In order to get it into a usable format, we need to make sure the configuration parsing won't try to read sections of it as variables. To do this, we do something called *escaping*.

All you need to do is take the salted hash and replace every `$` you see -- there should be exactly three -- with `$$`. That's it! Count them to be sure; you should now have *6* `$` symbols present instead of three. Once you've escaped the salted hash, you're ready to roll.

=== Cheating/The Easy Way
Feeling overwhelmed? There's an easy way to do all of this.

First, while logged into your local computer, change your password to what you want ether `root_password` or `password` to be:

 passwd

NOTE: Remember, changing your password won't echo the password back on the screen for security reasons!

Then get your shadow entry. This has to be done with sudo, as only the root user has access to the hashed passwords on the system. The following command will combine all steps necessary; the string it returns will be a string you can use directly in your `build.ini`.

 sudo grep "^${SUDO_USER}:" /etc/shadow | awk -F':' '{print $2}' | sed -e 's/\$/$$/'

Don't forget to change your password back to what it was before!

 passwd

That's it!