kc.1

.\"Copyright (c) 2011-2024 LEVAI Daniel
.\"All rights reserved.
.\"Redistribution and use in source and binary forms, with or without
.\"modification, are permitted provided that the following conditions are met:
.\"	* Redistributions of source code must retain the above copyright
.\"	notice, this list of conditions and the following disclaimer.
.\"	* Redistributions in binary form must reproduce the above copyright
.\"	notice, this list of conditions and the following disclaimer in the
.\"	documentation and/or other materials provided with the distribution.
.\"THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\"WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\"DISCLAIMED. IN NO EVENT SHALL LEVAI Daniel BE LIABLE FOR ANY
.\"DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\"(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\"LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\"ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\"(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\"SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd $Mdocdate: April 25 2024 $
.Dt KC 1
.Os
.Sh NAME
.Nm kc
.Nd console based username and password management application
.Sh SYNOPSIS
.Nm
.Op Fl k Ar database file
.Op Fl c Ar keychain name/idx
.Op Fl C Ar keychain name
.Op Fl r
.Op Fl A Ar key-type,key-comment Op Ql ,password
.Op Fl Y Ar key-slot Op ,device-index|serial-number Op Ql ,password
.Op Fl p Ar password file
.Op Fl P Ar kdf
.Op Fl K Ar key length
.Op Fl R Ar kdf iterations
.Op Fl e Ar cipher
.Op Fl m Ar cipher mode
.Op Fl 1 Ar parameter
.Op Fl 2 Ar parameter
.Op Fl 3 Ar parameter
.Op Fl 4 Ar parameter
.Op Fl 5 Ar parameter
.Op Fl b
.Op Fl B
.Op Fl v
.Op Fl h
.Sh DESCRIPTION
.Nm
is a console-based username and password management application using an
encrypted XML document as its database.
The database file is encrypted with a key that is generated from a
user-supplied password and/or a security key and/or an SSH agent.
Database encryption
.Po and thus decryption
.Pc can be interactive or
non-interactive in that it could require user input
.Po i.e. a password
.Pc , or a
response for a challenge from a security key or a signature from an SSH agent.
See the
.Em PASSWORDS
section on how these work in terms of generating a password.
.Pp
A database file can contain multiple keychains, and keychains in turn can
contain multiple keys
.Po usernames if you like
.Pc and values
.Po passwords if you like
.Pc .
.Pp
After starting
.Nm
the
.Ic help
command shows the available commands, and usage information for them.
If you're in a hurry, for starters, you create a new entry with the
.Ic new
command and save it with
.Ic write .
You can see the stored keys with the
.Ic list
command, then entering only a number in the command line will display the entry
with the given index.
You quit from the value display with
.Ql q
or EOT
.Po usually CTRL+d
.Pc .
.Pp
The CLI supports tab-completion for commands and keychains.
.Pp
When saving the database
.Po Ic write
command
.Pc
.Nm
will create a temporary file
.Po under the same directory as the opened database file
.Pc , and will first try to save the whole database to that temporary database
file.
When this succeeds, only then will
.Nm
replace the old database with the new one, so you will always have a usable and
intact
.Po but potentially older
.Pc version of your database file.
.Pp
On
.Ox
.Nm
tries to use
.Xr pledge 2
but see also the CAVEATS section.
.Ss PARAMETERS
.Bl -tag -offset ||| -width |
.It Fl k Ar file
Use
.Ar file
as database.
The default is
.Pa ~/.kc/default.kcd .
.It Fl c Ar keychain
Change to the specified keychain after opening the database.
.It Fl C Ar keychain
Same as
.Fl c ,
but force
.Ar keychain
to be the keychain's name, instead of its index number.
More on this is in the
.Ic c
and
.Ic cc
commands' description.
.It Fl r
Open the database in read-only mode.
.Nm
will not try to lock the database file, and commands which could modify the
database will not be available.
.It Fl A Ar key-type,key-comment Op ,password
Use a signature from SSH agent as the database password.
For this,
.Nm
asks
.Xr ssh-agent 1
(using the
.Ev SSH_AUTH_SOCK
environment variable) to sign the IV and the salt of the database (and
optionally a password) with a private key loaded into
.Xr ssh-agent 1 .
This private key is looked up based on the
.Ar key type
and
.Ar key comment
separated by a comma (with no whitespaces around it).
.Pp
Key types supported and tested so far are RSA and ED25519, by using the type
names
.Bl -tag -offset ||| -width |
.It Ar ssh-rsa
.It Ar ssh-ed25519
.El
.Pp
respectively.
Due to the nature of *DSA keys,
.Nm
cannot use them in this specific way for this specific purpose.
.Pp
Key comments cannot contain comma (,) characters.
.Pp
If the word
.Ql password
is appended to the key comment after a comma (with no whitespaces around it),
then
.Nm
will also use the password (along with the IV and salt) as the input for the
SSH agent signature request.
Thus making it interactive (by requesting a password for decryption) instead of
an automatic database opening.
.Pp
E.g.:
.Bl -tag -offset ||| -width |
.It Ar ssh-ed25519,daniel-private,password
Search for an
.Ql ed25519
type key with a comment
.Ql daniel-private
and also ask for a password to use when opening the database.
.El
.Pp
Also worth mentioning that this actually works with agent forwarding as well,
so on a remote machine one doesn't even have to have the actual private key
file \(em just like in any other case when you'd use SSH agent forwarding.
.It Fl Y Ar key-slot Op ,device-index|serial-number Op Ql ,password
Use a YubiKey to utilize its challenge-response mechanism to construct the
password for the database.
This can be either an automatic or an interactive mode of operation (just like
with SSH agent support).
Without the
.Ql password
parameter the challenge will be the database salt value, thus facilitating an
automatic database open.
.Pp
This is a comma-sperated list of parameters, and the only mandatory argument to
this option is the slot number.
If the device index or serial number in the second field is missing, the first
available device
.Po index #0
.Pc is used. The third
.Po or second, if the index or serial is missing
.Pc field can be the literal word
.Ql password .
.Pp
E.g.:
.Bl -tag -offset ||| -width |
.It Ar 2
means slot 2 and implicitly device 0 (the first device).
.It Ar 2,password
means slot 2 and implicitly device 0 (the first device), and also use a
user-supplied password.
.It Ar 1,0
means slot 1 and device 0 (the first device).
.It Ar 2,0
means slot 2 and device 0 (the first device).
.It Ar 2,1
means slot 2 and device 1 (the second device).
.It Ar 2,3,password
means slot 2 and device 3 (the third device), and also use a user-supplied
password.
.It Ar 2,12345678,password
means slot 2 and the device with the serial number 12345678, and also use a
user-supplied password.
.El
.Pp
If the
.Ql password
parameter is specified, then the user-supplied password is used as the
challenge with the security key \(em otherwise the database's salt is the
challenge (stored in the database).
When using this option, the password can be at most 64 bytes long.
E.g.:
.Bl -tag -offset ||| -width |
.It Ar 2,0,password
Use the frist device, the second slot, and ask for a password to use as the
challenge.
.El
.Pp
.Em Using multiple security keys:
.Pp
It's possible to use multiple security keys by specifying this option two or
more times.
In this case
.Nm
will use the specified security keys in the order these options are specified,
and each subsequent device will re-use the previous output
.Po response
.Pc as its challenge, chaining together the security keys.
The database can only be opened when using all of the provided security keys,
and by specifying these options in the same exact order.
To work around the dynamic assignment of device numbers based on the order one
plugs in their security keys, serial numbers can be used instead of the device
index number to explicitly specify which security key to use.
.Pp
When using multiple security keys, any one of the
.Ql password
parameters turns on the usage of the user-supplied password.
.It Fl p Ar file
Read password from
.Ar file .
.It Fl P Ar kdf
KDF to use with the password.
Valid parameters are:
.Bl -tag -offset ||| -width |
.It Ar sha3
OpenSSL's PKCS5 PBKDF2 with SHA-3 512.
.It Ar sha512
OpenSSL's PKCS5 PBKDF2 with SHA-2 512.
This is the default.
.It Ar bcrypt
Bcrypt PBKDF based on Blowfish.
This is slower than the SHA-* or scrypt variants.
On Linux, a bundled bcrypt implementation from
.Ox
is used, and its version is the one that was available at the time of this
.Nm
release.
.It Ar scrypt
If compiled with libscrypt,
.Nm
can use the scrypt KDF.
The speed of this is somewhere between SHA-* and bcrypt.
The
.Fl R
option is ignored when using this.
.It Ar argon2id
If compiled with Argon2 and a new enough OpenSSL,
.Nm
supports the Argon2id KDF.
Argon2 is a memory-hard function.
.Fl R
is used for specifying its iterations (default is 2),
.Fl 1
is used for specifying the number of memory lanes (default is 4), and
.Fl 2
is used for specifying the memory cost (default is 6291456).
.Pp
These defaults have been selected based on the recommendation of its RFC 9106.
.El
.Pp
More information is in the
.Em KDF
section.
.It Fl K Ar key length
Key length in bytes to use for encryption (and decryption).
A valid length is between 16 and 32 (default).
Some combinations of an encryption cipher and key length don't make sense with
low or high values.
If it's not really necessary, I suggest leaving it at the default:
32 bytes == 256 bits.
.It Fl R Ar iterations
Number of iterations or rounds to use with the KDF.
.Pp
More information is in the
.Em KDF
section.
.It Fl e Ar cipher
Encryption cipher for database encryption.
Valid parameters are:
.Bl -tag -offset ||| -width |
.It Ar aes256
This is the default
.It Ar blowfish
.It Ar chacha20
.Ar cipher mode
is ignored when using this.
.El
.It Fl m Ar cipher mode
Cipher mode for database encryption.
Different encryption ciphers can have different modes.
The valid parameters are:
.Bl -tag -offset || -width |
.It When using Ar aes256
.Bl -tag -offset ||| -width |
.It Ar cbc
This is the default
.It Ar cfb
.It Ar ofb
.It Ar ctr
.El
.It When using Ar blowfish
.Bl -tag -offset ||| -width |
.It Ar cbc
.It Ar cfb
.It Ar ofb
.El
.El
.Pp
More information is in the
.Em CIPHERS
section.
.It Fl b
Batch mode.
Enable reading commands and the password from standard input.
In this case, the password must be on the first line
.Po like it would be in interactive mode
.Pc .
.It Fl B
Batch mode.
Enable reading commands from standard input, but prompt for the password.
.It Fl v
Display version.
.It Fl h
Display help.
.El
.Ss COMMANDS
These commands are available in the CLI:
.Bl -tag -offset ||| -width |
.It Ic new Op name
Create a new key in the current keychain.
Both key and value will be prompted for, except when
.Ar name
is specified; then it will be used as the key's name.
.Pp
Character sequences can be used in values:
.Pp
.Qq \en
- create a new line, and make the result a multiline value.
.Pp
.Qq \er ,
.Qq \eR
- these will be replaced with 2 and 4
.Po respectively
.Pc
random printable characters.
.Pp
.Qq \ea ,
.Qq \eA
- these will be replaced with 2 and 4
.Po respectively
.Pc
random alpha-numeric characters.
.Pp
Character sequences are to be used in values, regardless of their order or
count, and can be escaped using double backslashes
.Po eg.:
.Qq \e\ea
.Pc .
.It Ic list Op pager Op offset
List
.Ar pager
number of keys per page from the current keychain, skipping
.Ar offset
indices if specified.
Every key gets prefixed by its index number.
If
.Ar pager
is not specified, the default value of 20 is used.
The special value 0 means to not use the pager.
If
.Ar offset
is not specified, it is not used.
.It Ic ls Op pager Op offset
Alias of
.Ic list .
.It Ic edit Ar index
Edit a key.
.Ar index
is the key's index number in the current keychain.
.Pp
Character sequence rules in values apply to this command also.
See command
.Ic new
for more information about this.
.It Ic swap Ar index Ar index
Swap two keys, exchanging their index numbers.
The two
.Ar index
parameters are the keys' index numbers in the current keychain.
.It Ic insert Ar index Ar index
Move the key at the first
.Ar index
parameter to the index at the second
.Ar index
parameter in the current keychain.
Surrounding indices will be shifted backwards or forwards.
.It Ic search Ar string
Search for
.Ar string
in key names in the current keychain.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix
.Pq eg.: Ic search\&! :
show non-matching keys.
.Pp
.Ql *
suffix
.Pq eg.: Ic search* :
search in every keychain.
.Pp
.Ql i
suffix
.Pq eg.: Ic searchi :
case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Ic / Ar pattern
Search for
.Ar pattern
regular expression in key names in the current keychain.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix
.Pq eg.: Ic /\&! :
show non-matching keys.
.Pp
.Ql *
suffix
.Pq eg.: Ic /* :
search in every keychain.
.Pp
.Ql i
suffix
.Pq eg.: Ic /i :
case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Ic near Ar index Op context
Display the keyname of key at
.Ar index
position, and also print the surrounding keys' name in at most
.Ar context
vicinity.
Only the keys' names and index numbers get displayed.
.It Ic csearch Ar string
Search for
.Ar string
in keychain names.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix
.Pq eg.: Ic csearch\&! :
show non-matching keychains.
.Pp
.Ql i
suffix
.Pq eg.: Ic csearchi :
case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Ic c/ Ar pattern
Search for
.Ar pattern
regular expression in keychain names.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix
.Pq eg.: Ic c/\&! :
show non-matching keychains.
.Pp
.Ql i
suffix
.Pq eg.: Ic c/i :
case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Ic c Ar keychain
Change the current keychain.
.Ar keychain
can be the keychain's index number or name.
Index number takes priority when addressing a keychain.
.Pp
.Pq see command Ic cc
.It Ic cc Ar keychain_name
Works like
.Ic c ,
but the keychain's name takes priority over its index number.
.Pp
.Pq see command Ic c
.It Ic cdel Ar keychain
Delete a keychain.
.Ar keychain
can be the keychain's index number or name.
Index number takes priority when addressing a keychain.
.Pp
.Pq see command Ic ccdel
.It Ic ccdel Ar keychain_name
Works like
.Ic cdel ,
but the keychain's name takes priority over its index number.
.Pp
.Pq see command Ic cdel
.It Ic clear Op count
Emulate a screen clearing.
Scrolls a 100 lines by default, which can be multiplied by
.Ar count
times if specified.
.It Ic clist
List all keychain names and their descriptions.
Every keychain gets prefixed by its index number.
.It Ic cls
Alias of
.Ic clist .
.It Ic cnew Op name
Create a new keychain.
If
.Ar name
is not given then prompt for one.
.It Ic cedit
Edit the current keychain's name and description.
.It Ic copy Ar index Ar keychain
Copy a key from the current keychain to another keychain.
.Ar index
is the key's index number to copy and
.Ar keychain
is the destination keychain's index number or name.
Index number takes priority when addressing a keychain.
.It Ic cp Ar index Ar keychain
Alias of
.Ic copy .
.It Ic move Ar index Ar keychain
Move a key from the current keychain to another keychain.
.Ar index
is the key's index number to move and
.Ar keychain
is the destination keychain's index number or name.
Index number takes priority when addressing a keychain.
.It Ic mv Ar index Ar keychain
Alias of
.Ic move .
.It Ic del Ar index
Delete a key.
.Ar index
is the key's index number in the current keychain.
.It Ic rm Ar index
Alias of
.Ic del .
.It Ic passwd Op Fl A Ar key-type,key-comment Op ,password Op Fl Y Ar Key-slot,Device-index|Serial-number Op ,password Op Fl P Ar kdf Op Fl K Ar key length Op Fl R Ar kdf iterations Op Fl e Ar cipher Op Fl m Ar cipher mode
Change the database password or SSH public key identity being used to encrypt.
Optionally, SSH key, security key information, KDF, key length, KDF iterations,
cipher and cipher mode can also be changed.
All changes will be written immediately.
.Pp
More information about the
.Ar kdf ,
.Ar cipher ,
.Ar cipher mode
optional arguments are in their respective command line parameter description
and the KDF and CIPHERS sections of this manual.
.It Ic help Op command
Print application help or describe a
.Ar command .
.It Ic status
Display information about the database.
.It Ic export Fl k Ar filename Op Fl A Ar key-type,key-comment Op ,password Op Fl Y Ar Key-slot,Device-index|Serial-number Op ,password Op Fl P Ar kdf Op Fl K Ar key length Op Fl R Ar kdf iterations Op Fl e Ar cipher Op Fl m Ar cipher mode Op Fl c Ar keychain
Export the database to a
.Nm
compatible encrypted database file named
.Ar filename
(if no extension specified, ".kcd" will be appended).
.Pp
Optional arguments
.Ar kdf ,
.Ar cipher
and
.Ar cipher mode
can be used to specify a different KDF, encryption cipher and cipher mode to be
used while exporting the database.
This doesn't change the current database's parameters, but when importing this
exported database, the parameters in use must be the same
.Po or specified explicitly when using the
.Ic import
command
.Pc .
.Pp
When specifying
.Ar keychain ,
export only that keychain.
.Ar keychain
can be the keychain's index number or name.
Index number takes priority when addressing a keychain.
.Pp
.Po see commands
.Ic dump ,
.Ic import ,
.Ic append
.Pc
.It Ic dump Fl k Ar filename Op Fl c Ar keychain
Dump the database to a
.Nm
compatible XML file named
.Ar filename
(if no extension specified, ".xml" will be appended).
.Pp
When specifying a keychain, dump only that keychain to the XML file.
.Ar keychain
can be the keychain's index number or name.
Index number takes priority when addressing a keychain.
.Pp
.Em NOTE :
the created XML file will be plain text.
.Pp
.Pq see command Ic export
.It Ic import Fl k Ar filename Op Fl A Ar key-type,key-comment Op ,password Op Fl Y Ar Key-slot,Device-index|Serial-number Op ,password Op Fl P Ar kdf Op Fl K Ar key length Op Fl R Ar kdf iterations Op Fl e Ar cipher Op Fl m Ar cipher mode Op Fl o
Import and overwrite the current database with the one from a
.Nm
compatible encrypted database file named
.Ar filename .
.Ar filename
must be a proper
.Nm
database.
.Pp
The
.Ar SSH key ,
.Ar Security key information ,
.Ar kdf ,
.Ar key length ,
.Ar kdf iterations ,
.Ar encryption cipher
and
.Ar cipher mode
optional arguments can be used to specify these parameters if they differ from
the current database's.
.Pp
With the
.Fl o
option you can import legacy (<v2.5) databases with missing attributes.
.Pp
.Po see commands
.Ic importxml ,
.Ic export ,
.Ic append
.Pc
.It Ic importxml Fl k Ar filename Op Fl o
Import and overwrite the current database with the one from a
.Nm
compatible XML file named
.Ar filename .
.Ar filename
must contain a properly formatted
.Nm
XML document.
.Pp
With the
.Fl o
option you can import legacy (<v2.5) XML files with missing attributes.
.Pp
.Po see commands
.Ic import ,
.Ic export ,
.Ic append
.Pc
.It Ic append Fl k Ar filename Op Fl A Ar key-type,key-comment Op ,password Op Fl Y Ar Key-slot,Device-index|Serial-number Op ,password Op Fl P Ar kdf Op Fl K Ar key length Op Fl R Ar kdf iterations Op Fl e Ar cipher Op Fl m Ar cipher mode Op Fl o
Append new and merge existing keychains to the database from a
.Nm
compatible encrypted database file named
.Ar filename .
.Ar filename
must be a proper
.Nm
database.
.Pp
See command
.Ic import
for description of parameters.
.Pp
See the
.Em LIMITS
section for information about how
.Nm
deals with limits reached while appending.
.Pp
.Po see commands
.Ic appendxml ,
.Ic export ,
.Ic import
.Pc
.It Ic appendxml Fl k Ar filename Op Fl o
Append new and merge existing keychains to the database from a
.Nm
compatible XML file named
.Ar filename .
.Ar filename
must contain a properly formatted
.Nm
XML document.
.Pp
With the
.Fl o
option you can import legacy (<v2.5) databases with missing attributes.
.Pp
See the
.Em LIMITS
section for information about how
.Nm
deals with limits reached while appending.
.Pp
.Po see commands
.Ic append ,
.Ic export ,
.Ic import
.Pc
.It Ic info Op index
Print information about a key in the current keychain or the keychain itself.
If
.Ar index
is specified, it is the key's index number in the current keychain.
If omitted, information is about the current keychain.
.It Ic quit
Quit the program.
If the database has been modified, then ask if it should be saved.
.It Ic exit
Alias of
.Ic quit .
.It Ic tmux Ar index Op line
Copy the value of
.Ar index
to tmux's paste buffer.
.Ar index
is the key's index number in the current keychain.
.Ar line
can be used to specify the line number to copy, if
.Ar index
is a multiline value (defaults to 1).
This will try to execute the
.Xr tmux 1
binary with the
.Em set-buffer
command passing the
.Em value
as its parameter.
.Pp
Check the
.Em CAVEATS
section about the clipboard commands.
.It Ic Xclip Ar index Op line
.It Ic xclip Ar index Op line
Copy the value of
.Ar index
to the CLIPBOARD
.Po aka.: CTRL+c - CTRL+v
.Pc or PRIMARY X11 selection
.Po ie.: middle mouse button
.Pc , depending on the first
.Sq x
character's case, respectively.
.Ar index
is the key's index number in the current keychain.
.Ar line
can be used to specify the line number to copy, if
.Ar index
is a multiline value
.Po defaults to 1
.Pc .
.Pp
These will try to execute the
.Xr xclip 1
binary, piping the
.Em value
to its standard input.
.Pp
Check the
.Em CAVEATS
section about the clipboard commands.
.It Ic version
Display the program version.
.It Ic write
Save the database.
.It Ic save
Alias of
.Ic write .
.It Ic any number
To display a key's value, you enter the key's index
.Po ie.: only a number
.Pc into the command line, then it will display the entry with the given index.
You quit from the display with 'q' or EOT
.Po usually CTRL+d
.Pc .
.Pp
Rarely one needs to actually look at the passwords being stored, there are
convenient commands
.Po Ic Xclip xclip tmux
.Pc
.Pp
By specifying another number after the index
.Po eg.: '12 2' \(em here 12 is the index, and 2 is the extra number
.Po spice
.Pc after it
.Pc , that many random characters will be displayed between the value's characters.
You can navigate up/down through a multiline value's lines with keys j/k, n/p,
f/b, +/-, [/], {/}, </>, <SPACE>, <ENTER>, <BACKSPACE>.
Typing a number between 1-9 will jump directly to that line.
.Pp
It is possible to copy the displayed value to a clipboard
.Po or such
.Pc with these hotkeys:
.Bl -tag -offset ||| -width |
.It t
Copy the value to the tmux paste buffer like the
.Ic tmux
.Nm
command.
.It x
Copy the value to the PRIMARY X selection like the
.Ic xclip
.Nm
command.
.It X
Copy the value to the CLIPBOARD X selection like the
.Ic Xclip
.Nm
command.
.El
.Pp
Check the
.Em CAVEATS
section about the clipboard commands.
.Pp
Perhaps the extra number
.Po spice
.Pc after a key's index and its usefulness can use some further explanation.
Let's say you want to display a password to use it on a website's form, but you
don't want the people walking by or around you to recognize words, numbers or
parts of it.
You can use this nifty "trick" to tell
.Nm
to display that many random characters between the value's original characters
when showing it to you.
Granted, it will look like a mess
.Po although, that is what we wanted
.Pc , but you
can copy-paste it to the password entry in the website form in question.
Then you can start to "blindly" delete the given number of characters from it
by moving your cursor to the beginning
.Po eg.: HOME key
.Pc , pressing 'spice'
numbers of DEL, then jump over one character to the right
.Po with the right arrow key
.Pc , then delete the random characters again, then repeating this until you
reach the end of your original password
.Po those who played Mortal Kombat will feel a bit nostalgic
.Pc .
You can catch on to this, because the random character padding is of fixed
length, so the pattern remains the same for the whole password.
You don't even have to pay attention to the original length of the password,
because after you've completed the pattern
.Po DELs-move-DELs-move...
.Pc and removed
the spice
.Po ie.: every padding random character
.Pc , you end up with your original
password, and you'll just be deleting nothing after the end of the string.
This of course only makes sense if the form is a password input field, so you
.Po and everybody else
.Pc just see stars or dots in place of the password.
.El
.Ss CIPHERS
Databases are encrypted with the AES-256 cipher in CBC mode, if another cipher
and mode was not specified explicitly
.Po see the
.Fl e
and
.Fl m
options
.Pc . Ciphers use a key generated with a KDF from the user-supplied password
.Po and optionally a signature from an SSH agent or a HMAC response from a YubiKey
.Pc , and an IV
.Po initialization vector
.Pc that is read when first creating a database from the host's specific random device
.Po Pa /dev/urandom on Linux and
.Pa /dev/random on everything else
.Pc .
.Pp
To change the encryption cipher and/or its mode, you can use the
.Ic passwd
or
.Ic export
command.
.Pp
See also the
.Em CAVEATS
section.
.Ss KDF
The KDF
.Po key derivation function
.Pc converts the constructed password
.Po either directly from the user input or after being treated with one of the
relevant functions like an SSH agent or a security key
.Pc with a generated salt to a strong key that can be used safely during
encryption.
.Pp
Every SHA-* based PBKDF2 function uses 100000 iterations and the bcrypt KDF
uses 36 rounds by default.
If you're using
.Nm
on an old enough
.Po quite old
.Pc hardware, you might reckon that these numbers are too high, or in other
words, opening a database takes too much time.
See option
.Fl R
if you really think you should change this.
And remember, after saving/exporting a database with a certain number of KDF
rounds or iterations, you must use the same number when trying to open it.
.Pp
On changing the KDF being used, see the
.Ic passwd
command and the
.Fl P
option.
.Ss PASSWORDS
Although
.Nm
uses a key generated with a KDF to encrypt
.Po and decrypt
.Pc
a database, one of the inputs of that is usually
.Po but not necessarily
.Pc
a user-supplied password.
There are currently a couple of options to consider when deciding how to create
and/or use a database.
.Bl -tag -width |
.It A single password
Most simple one
.Po doesn't need any specific parameter to be specified
.Pc , just type in a password when creating a database and use the same one
when opening it.
Old school.
.It A signature based on an SSH key loaded into an SSH agent
This method \(em when used with the
.Op -A
option \(em takes the database IV and salt
.Po both available when reading the database file
.Pc
and the SSH agent generates a
.Ql new password
from them.
This will be the kind of gibberish that's essentially harder to guess than your
average password, but takes data as input that's available directly from the
database file.
Thus, when someone has read access to the database file
.Em and
the SSH agent that has the required key loaded
.Po or the private key directly
.Pc ,
they can open the database.
This method is convenient because one doesn't have to input a password
.Po the database open is non-interactive
.Pc
so it works neatly when combined with other tools \(em I've used this e.g. with
.Xr mutt 1
to get my IMAP/SMTP password without having to type in anything when I started
it.
.Pp
Additionally one can use a user-supplied password on top all of this
.Po by supplying the
.Ar ,password
parameter
.Pc , that will be mixed in with the input when getting the signature from the
SSH agent.
Thus adding an interactive layer to the database opening, and making it harder
for someone to open the database if they steal it along with the required SSH
private key.
.Pp
What
.Nm
actually does is not only mixing in the password when getting the signature,
but also directly appending it to the signature when using it as input with the
KDF.
In this case, when opening the database
.Nm
will ask for a password and the SSH agent for a signature based on the correct
private key.
.Pp
See the
.Op -A
option on how this works.
.It A challenge-response from a security key
.Nm
supports the YubiKey's HMAC challenge-response mode
.Po using the
.Op -Y option
.Pc
and the response is used as the password input for the KDF.
This too can have an added conveniency of not having to type in anything when
opening the database, because
.Nm
can use only the database salt as the challenge, and so the response from the
security key will be based on this.
The salt is directly available from the database file, so if someone steals it
.Em and
the required security key, they can open the database.
.Pp
There is however the
.Ar ,password
parameter here as well, with which one can add an interactive layer on top all
of this, and use the user-supplied password
.Po combined with the salt if it's not long enough
.Pc as the challenge.
In this case, when opening the database
.Nm
will ask for a password and the correct security key.
.Pp
More than one security key can be used in order for
.Nm
to require all of them in the right order when opening a database.
.Pp
See the
.Op -Y
option on how this works.
.It Combining authentication features
Now, knowing that database passwords can be generated with the help of an SSH
agent and a YubiKey security key with a user-supplied password, another thing
one can do besides using either one of the above functions, is to combine any
of these.
If \(em and only if \(em SSH agent signing and security key challenge-response
are used with a password
.Po see
.Ar ,password
parameter for both of these
.Pc
then
.Nm
will treat the user-supplied password first with the SSH agent and then
subsequently with the security key, thus requiring the user's password, the SSH
private key and the security key to open the database later on.
This may sound convoluted, and I'm not even sure if it's worth the
.Qq trouble ,
nevertheless, it is a possibility and I think it shows how the separate
features are built up.
.El
.Pp
At the end of the day, all these functions do is provide a password to be used
with the KDF to generate a key from it.
Choose one that you deem secure enough, is convenient and works for you.
.Ss LIMITS
.Nm
has its limits when it comes to dealing with keychains and keys in keychains.
The maximum number of elements for both is the upper limit an unsigned long
integer can store on the running platform, minus one.
These limits are enforced every time a new keychain or key is being created
.Po or moved, copied, etc...
.Pc .
Appending is done in a non-atomic fashion.
This means that
.Nm
will not create a keychain if it would not fit in the limit, and it will not
append keys to an existing keychain if they would not fit in the limit.
However, for example, if a database that is being appended contains a keychain
whose keys could not fit in the existing keychain, and also contains a keychain
whose keys could fit in the existing keychain, then the one that could fit will
be appended, and the one that could not will not be appended.
This means that appending is atomic on the keychain level
.Po or keys level, if you like
.Pc , and not atomic on the database level.
.Ss SUPPORTED DEVICES
.Bl -tag -width |
.It SSH agent
OpenSSH agent support is based on RFC
.Ql draft-miller-ssh-agent-01 ,
available at:
.Lk https://tools.ietf.org/id/draft-miller-ssh-agent-01.html
.It Security key
YubiKey 5 NFC has been used during testing.
.El
.Sh EXAMPLES
.Bl -tag -width |
.It Sy Creating a new database:
.Bl -tag -width |
.It Em Using a password with the encryption key generated by bcrypt :
.Bd -literal
$ kc -P bcrypt -k ~/.kc/my_passwords.kcd
Creating '/home/user/.kc/my_passwords.kcd'
Using '/home/user/.kc/my_passwords.kcd' database.
New password (empty to cancel):
New password again (empty to cancel):
<default% >

<default% > status
Database file: /home/user/.kc/my_passwords.kcd (/home/user/.kc/my_passwords.kcd)
XML structure size: 148 bytes
Password: yes
SSH agent: no
YubiKey: no
Password function: bcrypt (36 rounds)
Encryption: aes256, cbc
Read-only: no
Modified: yes
<default% >
.Ed
.It Em Using an SSH agent without a password:
.Bd -literal
$ ssh-add -l
256 SHA256:3fxFML/VoUOvFr5WDPsiJH8E8dwM0/27IZtoVW7Cz/g my_private_key (ED25519)

$ kc -A ssh-ed25519,my_private_key -k ~/.kc/my_secrets.kcd
Using '(ssh-ed25519) my_private_key' identity for decryption
Creating '/home/user/.kc/my_secrets.kcd'
Using '/home/user/.kc/my_secrets.kcd' database.
<default% >

<default% > status
Database file: /home/user/.kc/my_secrets.kcd (/home/user/.kc/my_secrets.kcd)
XML structure size: 148 bytes
Password: no
SSH agent: (ssh-ed25519) my_private_key
YubiKey: no
Password function: sha512 (100000 iterations)
Encryption: aes256, cbc
Read-only: no
Modified: yes
<default% >
.Ed
.It Em Using a YubiKey security key and a password:
.Bd -literal
$ kc -Y 2,password -k .kc/passwords_and_secrets.kcd
Using YubiKey slot #2 on device #0 and a password
Creating '/home/user/.kc/passwords_and_secrets.kcd'
Using '/home/user/.kc/passwords_and_secrets.kcd' database.
New password (empty to cancel):
New password again (empty to cancel):
Remember to touch your YubiKey if necessary
<default% >

<default% > status
Database file: .kc/passwords_and_secrets.kcd (/home/user/.kc/passwords_and_secrets.kcd)
XML structure size: 148 bytes
Password: yes
SSH agent: no
YubiKey: Slot #2, Device #0
Password function: sha512 (100000 iterations)
Encryption: aes256, cbc
Read-only: no
Modified: yes
<default% >
.Ed
.El
.El
.Bl -tag -width |
.It Sy Adding new entries :
.Bl -tag -width |
.It Em Simple :
.Bd -literal
<default% > new testuser
<default% NEW value> testpass
.Ed
.It Em Prompt for both key and value :
.Bd -literal
<default% > new
<default% NEW key> testuser2
<default% NEW value> test_\er_pass_with_random_characters:\eA
.Ed
.It Em Using the 'key' only as an indication :
.Bd -literal
<default% > new www.mysecuresite.com
<default% NEW value> user_name\enpass-word
.Ed
.It Em Using the random and newline character sequences :
.Bd -literal
<default% > new testuser3
<default% NEW value> \er\eR\en\ea\eA\enthis is a multiline value!
.Ed
.El
.Bl -tag -width |
.It Em Creating new keychains :
.Bd -literal
<default% > cnew email_accounts
<default% > cnew
<default% NEW keychain name> WebSite Accounts
<default% NEW keychain description> description
.Pp
<default% > cnew 2
<default% NEW keychain description> Two
Created keychain: 3. 2
.Ed
.El
.El
.Bl -tag -width |
.It Sy Displaying, listing entries :
.Bl -tag -width |
.It Em Listing the keys in the current keychain :
.Bd -literal
<default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3
.Ed
.It Em Displaying values in the current keychain :
.Bd -literal
<default% > 0
[testuser] testpass
<default% > 1
[testuser2] test_,x_pass_with_random_characters:6nzm
<default% > 2
[www.mysecuresite.com] [1/2] user_name
[www.mysecuresite.com] [2/2] pass-word
<default% > 3
[testuser3] [1/3] v#)z!9
[testuser3] [2/3] HwRz7i
[testuser3] [3/3] this is a multiline value!
.Ed
.It Em Listing keychains :
.Bd -literal
<default% > clist
0. default
1. email_accounts
2. WebSite Accounts
3. 2
.Ed
.It Em Switch to another keychains :
.Bd -literal
<default% > c email_accounts
<email_accounts% > c 2
<WebSite Accounts% > c 3
<2% > c 2
<WebSite Accounts% > cc 2
<2% >
.Ed
.El
.El
.Bl -tag -width |
.It Sy Editing existing entries :
.Bl -tag -width |
.It Em Edit an entry in the current keychain :
.Bd -literal
<default% > edit 1
<default% EDIT key> testuser2
<default% EDIT value> test_pass_with_random_characters:6nzm
<default% > 1
[testuser2] test_pass_with_random_characters:6nzm
.Ed
.It Em Rename a keychain :
.Bd -literal
<default% > cedit
<default% EDIT keychain name> my_own keychain
<default% EDIT keychain description> description
my_own keychain% >
.Ed
.El
.El
.Bl -tag -width |
.It Sy pwsafe_to_kc.pl :
.Bd -literal
# Export the pwsafe database to a cleartext file:
$ pwsafe --exportdb > pwsafe_export
Enter passphrase for .pwsafe.dat:

# Convert the cleartext pwsafe database to a kc XML database file:
$ pwsafe_to_kc.pl pwsafe_export kc_db.xml
opening pwsafe_export for reading.
opening kc_db.xml for writing.
Converting...
Done.
.Ed
.Pp
After the above commands, you should end up with a
.Nm
compatible XML database.
You can import it to
.Nm
using the
.Ic importxml
command.
.El
.Sh AUTHORS
.Nm
was written by
.An LEVAI Daniel
<leva@ecentrum.hu>
.Pp
Source, information, bugs:
https://github.com/levaidaniel/kc
.Sh CAVEATS
Fair warnings before using the clipboard features:
.Bl -enum -offset ||| -width |
.It
If you don't trust the system where you're running
.Ic kc
then don't use these features, as you can not be sure that the binaries in your
PATH are not tampered with and would record the passwords.
.It
Removal of the
.Em values
from the clipboards are not being dealt with.
This should be the user's responsibility.
.El
.Pp
SSH agent support:
.Bl -enum -offset ||| -width |
.It
The password
.Po signature
.Pc coming from
.Xr ssh-agent 1
varies between different types of SSH keys \(em different keys/key bit lengths
produce different signature lengths.
.It
.Nm
cannot handle spaces in the key comment when using the
.Ic export
or
.Ic import
commands.
Opening a database however, works with spaces in the key comment.
.El
.Pp
YubiKey HMAC challenge-response:
.Bl -enum -offset ||| -width |
.It
Supports an at most 64 bytes long password.
.It
Only HMAC mode is supported by
.Nm
.It
Maybe it goes without saying, but this method of password protection is not
quite useful over network connections
.Po e.g.: SSH on a remote machine
.Pc , as the
actual device is not plugged in there.
There is, however, a USB-over-IP implementation for Linux that could overcome
this.
.El
.Pp
Miscellaneous:
.Bl -enum -offset ||| -width |
.It
It is considered a good practice, to periodically manually backup the database
file(s) you use with
.Nm .
This could just mean a simple:
.Bd -literal -offset |||
$ cp ~/.kc/default ~/.kc/default-bkp
.Ed
.It
.Nm
doesn't try excessively hard to recover from hard and/or non-recoverable errors
.Po OS, memory, disk etc...
.Pc , and in some cases this could mean that it will
simply exit
.Po without saving the database
.Pc with an appropriate error message.
No need to worry, but keep this in mind like you would with a common word
processor or text editor and save periodically, for example when you edit many
keys at once.
.It
There is no character set conversion taking place in the program.
In this case this means you must be ready to display anything you type in.
If somehow you still end up with texts you can not display properly, and for
whatever reason you can not edit them in
.Nm ,
you can
.Qq repair
such database by dumping its content to a
.Nm
XML file
.Po see the
.Ic dump
command
.Pc , converting the plain text XML file to a working character set, then
importing back that XML file
.Po see the
.Ic importxml
command
.Pc .
.It
If you use
.Ar cfb ,
.Ar ctr
or
.Ar ofb
as the cipher mode, there is no specific sign if you enter a wrong password
during opening a database; in this case the database will seem to be corrupt
after decrypting, and
.Nm
simply will not be able to open it.
.It
On
.Ox
.Nm
uses
.Xr pledge 2
to restrict its access to certain functions, but only when
.Em not
compiled with YubiKey support.
Currently the way yubikey libraries access USB devices cannot be allowed by any
promise for
.Xr pledge 2 .
.It
There is a Perl script in the source package
.Po available from the project website
.Pc that converts an exported pwsafe database to a
.Nm
compatible XML database, which can be imported using the
.Ic importxml
command.
.Em NOTA BENE :
This script is really old and not maintained.
.El