NAME

kc —

console based username and password management application

SYNOPSIS

`kc`	[`-k` `database file`] [`-c` `keychain name/idx`] [`-C` `keychain name`] [`-r`] [`-p` `password file`] [`-P` `kdf`] [`-e` `cipher`] [`-m` `mode`] [`-b`] [`-B`] [`-v`] [`-h`]

DESCRIPTION

The kc utility is a console based username and password management application using an encrypted XML document as its database. The database file is protected by a password that the user supplies during the creation of a new database. This password can be at most 256 characters long, and is converted to a key with a KDF (key derivation function). If the supplied password (either by user input or in a password file) is longer than the allowed maximum, kc silently discards the rest of it.

A database file can contain multiple keychains, and keychains in turn can contain multiple keys (usernames if you like) and values (passwords if you like).

After starting kc the 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 new command, then entering only a number in the command line will display the entry with the given index. You quit from the display with 'q' or EOT (usually CTRL+d).

The CLI supports tab-completion for commands and keychains.

There is a utility in the source package (it is also available from the project website) that converts an exported pwsafe database to a kc compatible XML database, which can be imported using the importxml command.

When saving the database (write command) kc will create a temporary file (under the same directory as the opened database file), and will first try to save the whole database to that temporary database file. When this succeeds, only then will kc replace the old database with the new one, so you will always have a usable and intact (but potentially older) version of your database file.

NOTE: It is considered a good practice, to periodically manually backup the database file(s) you use with kc. This could just mean a simple:

$ cp ~/.kc/default ~/.kc/default-bkp

kc doesn't try excessively hard to recover from hard and/or non-recoverable errors (OS, memory, disk etc...), and in some cases this could mean that it will simply exit 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 (write) periodically, for example when you edit many keys at once. See also the CAVEATS section regarding this.

NOTE: Currently 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 kc, you can "repair" such database by dumping its content to a kc XML file (see the dump command below), converting the plain text XML file to a working character set, then importing back that XML file (see the importxml command below).

PARAMETERS

-k file

Use file as database. The default is ~/.kc/default.kcd.

-c keychain

Change to the specified keychain after opening the database.

-C keychain

Same as -c, but force keychain to be the keychain's name, instead of its index number. More on this is in the c and cc commands' description.

-r

Open the database in read-only mode. kc will not try to lock the database file, and commands which could modify the database will not be available.

-p file

Read password from file. The last new line gets stripped.

-P kdf

KDF to use with the password. Valid parameters are:

sha1: OpenSSL's PKCS5 PBKDF2 with SHA-1. kc uses 5000 rounds.
sha512: OpenSSL's PKCS5 PBKDF2 with SHA-512. This is the default. kc uses 5000 rounds.
bcrypt: Bcrypt PBKDF based on Blowfish. kc uses 16 rounds, and this is slightly slower than the SHA-* variants. On Linux, a bundled bcrypt implementation from OpenBSD is used, and its version is the one that was available at the time of this kc release.
scrypt: If compiled with libscrypt, kc can use the scrypt KDF. Note that this can be slow on older machines, but therein lies the algorithm's strength.

More information is in the KDF section.

-e cipher

Encryption cipher for database encryption. Valid parameters are:

aes256: This is the default
blowfish

-m mode

Cipher mode for database encryption. Different encryption ciphers can have different modes. The valid parameters are:

aes256

cbc: This is the default
cfb128
ofb

blowfish

cbc
ecb
cfb64
ofb

More information is in the CIPHERS section.

-b

Batch mode. Enable reading commands and the password from standard input. In this case, the password must be on the first line (like it would be in interactive mode).

-B

Batch mode. Enable reading commands from standard input, but prompt for the password.

-v

Display version.

-h

Display help.

COMMANDS

These commands are available in the CLI:

new [name]

Create a new key in the current keychain. Both key and value will be prompted for, except when name is specified; then it will be used as the key's name.

Character sequences can be used in values:

"\n" - create a new line, and make the result a multiline value.

"\r", "\R" - these will be replaced with 2 and 4 (respectively) random printable characters.

"\a", "\A" - these will be replaced with 2 and 4 (respectively) random alpha-numeric characters.

Character sequences are to be used in values, regardless of their order or count, and can be escaped using double backslashes (eg.: "\\a").

list [pager [offset]]

List pager number of keys per page from the current keychain, skipping offset indices if specified. Every key gets prefixed by its index number. If pager is not specified, the default value of 20 is used. The special value 0 means to not use the pager. If offset is not specified, it is not used.

ls [pager [offset]]

Alias of list.

edit index

Edit a key. index is the key's index number in the current keychain.

Character sequence rules in values apply to this command also. See command new for more information about this.

swap index index

Swap two keys, exchanging their index numbers. The two index parameters are the keys' index numbers in the current keychain.

insert index index

Move the key at the first index parameter to the index at the second index parameter in the current keychain. Surrounding indices will be shifted backwards or forwards.

search string

Search for string in key names in the current keychain.

Optional modifiers:

‘!’ suffix (eg.: search!): show non-matching keys.

‘*’ suffix (eg.: search*): search in every keychain.

‘i’ suffix (eg.: searchi): case of characters doesn't matter.

You can combine the modifiers.

/ pattern

Search for pattern regular expression in key names in the current keychain.

Optional modifiers:

‘!’ suffix (eg.: /!): show non-matching keys.

‘*’ suffix (eg.: /*): search in every keychain.

‘i’ suffix (eg.: /i): case of characters doesn't matter.

You can combine the modifiers.

near index [context]

Display the keyname of key at index position, and also print the surrounding keys' name in at most context vicinity. Only the keys' names and index numbers get displayed.

csearch string

Search for string in keychain names.

Optional modifiers:

‘!’ suffix (eg.: csearch!): show non-matching keychains.

‘i’ suffix (eg.: csearchi): case of characters doesn't matter.

You can combine the modifiers.

c/ pattern

Search for pattern regular expression in keychain names.

Optional modifiers:

‘!’ suffix (eg.: c/!): show non-matching keychains.

‘i’ suffix (eg.: c/i): case of characters doesn't matter.

You can combine the modifiers.

c keychain

Change the current keychain. keychain can be the keychain's index number or name. Index number takes priority when addressing a keychain. (see command cc)

cc keychain_name

Works like c, but the keychain's name takes priority over its index number. (see command c)

cdel keychain

Delete a keychain. keychain can be the keychain's index number or name. Index number takes priority when addressing a keychain. (see command ccdel)

ccdel keychain_name

Works like cdel, but the keychain's name takes priority over its index number. (see command cdel)

clear [count]

Emulate a screen clearing. Scrolls a 100 lines by default, which can be multiplied by count times if specified.

clist

List all keychain names and their descriptions. Every keychain gets prefixed by its index number.

cls

Alias of clist.

cnew [name]

Create a new keychain. If name is not given then prompt for one.

cedit

Edit the current keychain's name and description.

copy index keychain

Copy a key from the current keychain to another keychain. index is the key's index number to copy and keychain is the destination keychain's index number or name. Index number takes priority when addressing a keychain.

cp index keychain

Alias of copy.

move index keychain

Move a key from the current keychain to another keychain. index is the key's index number to move and keychain is the destination keychain's index number or name. Index number takes priority when addressing a keychain.

mv index keychain

Alias of move.

del index

Delete a key. index is the key's index number in the current keychain.

rm index

Alias of del.

passwd [-P kdf]

Change the database password and optionally the KDF. All changes will be written immediately.

More information about the kdf optional argument is in the -P parameter description and the KDF section of this manual.

help [command]

Print application help or describe a command.

status

Display information about the database.

export -k filename [-P kdf [-e cipher [-m cipher_mode [-c keychain]]]]

Export the database to a kc compatible encrypted database file named filename (if no extension specified, ".kcd" will be appended).

Optional arguments kdf, cipher and 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 (or specified explicitly when using the import command).

When specifying keychain, export only that keychain. keychain can be the keychain's index number or name. Index number takes priority when addressing a keychain. (see commands dump, import, append)

dump -k filename [-c keychain]

Dump the database to a kc compatible XML file named filename (if no extension specified, ".xml" will be appended).

When specifying a keychain, dump only that keychain to the XML file. keychain can be the keychain's index number or name. Index number takes priority when addressing a keychain. (see command export) NOTE: the created XML file will be plain text.

import -k filename [-P kdf [-e cipher [-m cipher_mode]]]

Import and overwrite the current database with the one from a kc compatible encrypted database file named filename. filename must be a proper kc database.

The kdf cipher and cipher_mode optional arguments can be used to specify these parameters if they differ from the current database's. (see commands importxml, export, append)

importxml -k filename

Import and overwrite the current database with the one from a kc compatible XML file named filename. filename must contain a properly formatted kc XML document. (see commands import, export, append)

append -k filename [-P kdf [-m cipher_mode]]

Append new and merge existing keychains to the database from a kc compatible encrypted database file named filename. filename must be a proper kc database.

The kdf and cipher_mode optional arguments can be used to specify these parameters if they differ from the current database's. See the LIMITS section for information about how kc deals with limits reached while appending. (see commands appendxml, export, import)

appendxml -k filename

Append new and merge existing keychains to the database from a kc compatible XML file named filename. filename must contain a properly formatted kc XML document. See the LIMITS section for information about how kc deals with limits reached while appending. (see commands append, export, import)

info [index]

Print information about a key in the current keychain or the keychain itself. If index is specified, it is the key's index number in the current keychain. If omitted, information is about the current keychain.

quit

Quit the program. If the database has been modified, then ask if it should be saved.

exit

Alias of quit.

tmux index [line]

Copy the value of index to tmux's paste buffer. index is the key's index number in the current keychain. line can be used to specify the line number to copy, if index is a multiline value (defaults to 1). This will try to execute the tmux(1) binary with the set-buffer command passing the value as its parameter.

Check the CAVEATS section about the clipboard commands.

Xclip index [line]

xclip index [line]

Copy the value of index to the CLIPBOARD (aka.: CTRL+c - CTRL+v) or PRIMARY X11 selection (ie.: middle mouse button), depending on the first ‘x’ character's case, respectively. index is the key's index number in the current keychain. line can be used to specify the line number to copy, if index is a multiline value (defaults to 1).

These will try to execute the xclip(1) binary, piping the value to its standard input.

Check the CAVEATS section about the clipboard commands.

version

Display the program version.

write

Save the database.

save

Alias of write.

any number

To display a key's value, you enter the key's index (ie.: only a number) into the command line, then it will display the entry with the given index. You quit from the display with 'q' or EOT (usually CTRL+d). By specifying another number after the index (eg.: '12 2' -- here 12 is the index, and 2 is the extra number (spice) after it), 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.

It is possible to copy the displayed value to a clipboard (or such) with these hotkeys:

t: Copy the value to the tmux paste buffer like the tmux command.
x: Copy the value to the PRIMARY X selection. like the xclip command.
X: Copy the value to the CLIPBOARD X selection, like the Xclip command.

Check the CAVEATS section about the clipboard commands.

Perhaps the extra number (spice) 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 kc to display that many random characters between the value's original characters when showing it to you. Granted, it will look like a mess (although, that is what we wanted), 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 you cursor to the beginning (eg. HOME key), pressing 'spice' numbers of DEL, then jump over one character to the right (with the right arrow key), then delete the random characters again, then repeating this until you reach the end of you original password (those who played Mortal Kombat will feel a bit nostalgic). 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 (DELs-move-DELs-move...) and removed the spice (ie.: every padding random character), you end up with you 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 (and everybody else) just see stars or dots in place of the password.

CIPHERS

Databases are encrypted with the AES-256 cipher in CBC mode, if another cipher and mode was not specified explicitly. (see the -e and -m options). Ciphers use a 128 byte key generated with a KDF (key derivation function) from the supplied password (see the KDF section), and an IV (initialization vector) that is read from the host's specific random device (/dev/urandom on Linux and /dev/random on everything else) as characters. See also the CAVEATS section. To change the encryption cipher and/or its mode, you can use the export command.

KDF

The KDF converts the user supplied password with a generated salt to a strong key that can be used safely during encryption. Every SHA-* based PBKDF2 KDF uses 5000 rounds in kc. On changing the KDF in use, see the -P option and the passwd command. Of course, changing the KDF with which the database was created/opened means that the new KDF must be used from then on. This is because changing the KDF changes the key the database was encrypted with.

LIMITS

kc has limits when it deals 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 (or moved, copied, etc...). Appending is done in a non-atomic fashion. This means that kc 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 (or keys level, if you like), and not atomic on the database level.

EXAMPLES

pwsafe_to_kc.pl:

# 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.

After the above commands, you should end up with a kc compatible XML database. You can import it to kc using the importxml command.

Adding new entries:

Simple
:
<default% > new testuser
<default% NEW value> testpass

Prompt for both key and value
:
<default% > new
<default% NEW key> testuser2
<default% NEW value> test_\r_pass_with_random_characters:\A

Using the 'key' only as an indication
:
<default% > new www.mysecuresite.com
<default% NEW value> user_name\npass-word

Using the random and newline character sequences
:
<default% > new testuser3
<default% NEW value> \r\R\n\a\A\nthis is a multiline value!

Creating new keychains
:
<default% > cnew email_accounts
<default% > cnew
<default% NEW keychain name> WebSite Accounts
<default% NEW keychain description> description

<default% > cnew 2
<default% NEW keychain description> Two
Created keychain: 3. 2

Results
:

Listing the keys in the current keychain
:
<default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

Displaying values in the current keychain
:
<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!

Listing keychains
:
<default% > clist
0. default
1. email_accounts
2. WebSite Accounts
3. 2

Switch to another keychains
:
<default% > c email_accounts
<email_accounts% > c 2
<WebSite Accounts% > c 3
<2% > c 2
<WebSite Accounts% > cc 2
<2% >

Editing existing entries:

<default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

Edit an entry in the current keychain
:
<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

Rename a keychain
:
<default% > cedit
<default% EDIT keychain name> my_own keychain
<default% EDIT keychain description> description
my_own keychain% >

CAVEATS

If you use cfb128 or ofb as the cipher mode, there is no specific sign if you enter a wrong password during the opening of a database; in this case the database would seem to be corrupt after decrypting, and kc will not be able to open it.

There is no character conversion taking place for the input fields.

kc will exit without saving the database (with a corresponding error message) when an out-of-memory condition arises.

Fair warnings before using the clipboard features:

If you don't trust the system where you're running 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.
Removal of the values from the clipboards are not being dealt with. This should be the user's responsibility.

AUTHOR

kc was written by LEVAI Daniel <leva@ecentrum.hu>

Source, information, bugs: https://github.com/levaidaniel/kc