| 1 |
libsecrecy |
| 2 |
========== |
| 3 |
|
| 4 |
libsecrecy is a header only C++17 library implementing an encrypted file |
| 5 |
format based on GCM (Galois Counter Mode) and AES128 or AES256. |
| 6 |
|
| 7 |
It uses [nettle](http://www.lysator.liu.se/~nisse/nettle/) routines for file |
| 8 |
encryption and decryption via GCM using AES128 or AES256 as cipher function |
| 9 |
and [gpgme](https://gnupg.org/software/gpgme/index.html) for key storage. |
| 10 |
|
| 11 |
While encryption is currently only supported in a streaming fashion, |
| 12 |
decryption allows random access in the encrypted file due to independently |
| 13 |
encoded subunits. |
| 14 |
|
| 15 |
# Compilation |
| 16 |
|
| 17 |
libsecrecy uses the GNU autoconf/automake tool set. It can be compiled on Linux |
| 18 |
using: |
| 19 |
|
| 20 |
libtoolize |
| 21 |
aclocal |
| 22 |
autoreconf -i -f |
| 23 |
./configure |
| 24 |
make |
| 25 |
|
| 26 |
Running autoreconf requires a complete set of tools including autoconf, automake, |
| 27 |
autoheader, aclocal and libtool. Use |
| 28 |
|
| 29 |
./configure --prefix=$HOME/libsecrecy |
| 30 |
make install |
| 31 |
|
| 32 |
to obtain a local installation. |
| 33 |
|
| 34 |
Compiling libsecrecy requires nettle, gpgme and pkg-config to be installed. |
| 35 |
On Debian and Ubuntu this can be done by installing the packages nettle-dev, |
| 36 |
libgpgme-dev and pkg-config. |
| 37 |
|
| 38 |
# Command line tool |
| 39 |
|
| 40 |
The distribution comes with a command line tool called secrecy. This tool |
| 41 |
currently has three subcommands createKey, encrypt, decrypt, exportKey, |
| 42 |
importKey, listKeys and setDefaultKey. |
| 43 |
|
| 44 |
--- |
| 45 |
|
| 46 |
Keys for libsecrecy can be created using the command |
| 47 |
|
| 48 |
secrecy createKey cipher gpgid keyname |
| 49 |
|
| 50 |
where cipher can currently take the values AES128, AES192 or AES256, gpgid needs |
| 51 |
to be a valid id (e.g. email adress) present as a secret key in gpg's |
| 52 |
keyring which can be used for securely storing the AES key for use by |
| 53 |
libsecrecy and keyname can be chosen as a human readable name for the key |
| 54 |
create (e.g. mykey). |
| 55 |
|
| 56 |
See https://gnupg.org/documentation/manuals/gnupg/OpenPGP-Key-Management.html#OpenPGP-Key-Management |
| 57 |
for creating and handling gpg keys. |
| 58 |
|
| 59 |
The program outputs a key hash in the form of a hexadecimal encoded string. |
| 60 |
Either this key hash or the key name given can to be provided to the encrypt command of secrecy for |
| 61 |
encrypting files using the newly created key. |
| 62 |
|
| 63 |
--- |
| 64 |
|
| 65 |
Files can be encrypted using the encrypt command of secrecy. The syntax for |
| 66 |
this is |
| 67 |
|
| 68 |
secrecy encrypt keyhash/name < input.plain > output.encryped |
| 69 |
|
| 70 |
Keyhash/name is either the hex string which was printed by createKey when creating the |
| 71 |
key or the name given to createKey when creating the key. If the string |
| 72 |
provided is empty, then the default key name is used (see setDefaultKey), if |
| 73 |
any has been set. |
| 74 |
|
| 75 |
Note that this command needs to decrypt the key from it's gpg encoded form, |
| 76 |
so you will need to provide the respective passphrase in some form. |
| 77 |
|
| 78 |
--- |
| 79 |
|
| 80 |
Encrypted files can be decryped using the decrypt command of secrecy. The |
| 81 |
respective syntax is |
| 82 |
|
| 83 |
secrecy decrypt < input.encrypted > output.plain |
| 84 |
|
| 85 |
This command also needs to decrypt the key from it's gpg encoded form, |
| 86 |
so you will need to provide the respective passphrase in some form. |
| 87 |
|
| 88 |
Note that you do not need to provide the keyhash for decryption as this |
| 89 |
information is provided inside the encrypted file. |
| 90 |
|
| 91 |
--- |
| 92 |
|
| 93 |
Keys can be exported to an encrypted transfer format for passing data on to |
| 94 |
third parties via the exportKey command of secrecy. The syntax for this is |
| 95 |
|
| 96 |
secrecy exportKey keyname gpgid > exported_key.txt |
| 97 |
|
| 98 |
where keyname is a valid key name or hash and gpgid is a string identifying |
| 99 |
the recipient of the key. The public key of gpgid needs to be available in |
| 100 |
gpg's key database. |
| 101 |
|
| 102 |
--- |
| 103 |
|
| 104 |
Keys can be imported from the format produced by the exportKey command using |
| 105 |
the importKey command. The syntax is |
| 106 |
|
| 107 |
secrecry importKey gpgid < exported_key.txt |
| 108 |
|
| 109 |
where gpgid designates the gpg key which will be used to locally encrypt the |
| 110 |
key for storing it in libsecrecy's database. |
| 111 |
|
| 112 |
--- |
| 113 |
|
| 114 |
The list of installed keys can be shown using |
| 115 |
|
| 116 |
secrecy listKeys |
| 117 |
|
| 118 |
which prints a tab separated table such that the first column contains |
| 119 |
the key names and the second the respective key hash values. |
| 120 |
|
| 121 |
--- |
| 122 |
|
| 123 |
The default key can be set using |
| 124 |
|
| 125 |
secrecy setDefaultKey keyname |
| 126 |
|
| 127 |
The default key is used when an empty keyname string is used for running |
| 128 |
any command accepting a key name (with the obvious exceptions of |
| 129 |
createKey and setDefaultKey). |
| 130 |
|
| 131 |
# Key storage |
| 132 |
|
| 133 |
AES keys are stored encrypted using gpg via gpgme. Each key is assigned |
| 134 |
a hash H value at creation time. H is computed as the SHA256 checksum of |
| 135 |
a randomly generated sequence. Keys are stored and searched for in the |
| 136 |
directory set in the environment variable `LIBSECRECY_KEYDIR`. If this |
| 137 |
variable is not set, then the subdirectory .libsecrecy inside the current |
| 138 |
users home directory (designated by the environment variable HOME) is used. |
| 139 |
Inside this directory the key for hash H is stored in the file |
| 140 |
hash/H (e.g. `hash/3E35C013C66C66B09E3E0B923451530C62D4346D9F5165906FC94B9B4D35E28E`) |
| 141 |
where the respective files are encrypted using gpgme. The secret key used |
| 142 |
for this encryption can be set at key creation time. |
| 143 |
|
| 144 |
# Compiling your own program using the installed library |
| 145 |
|
| 146 |
After installing libsecrecy in e.g. `$HOME/libsecrecy`, the flags required for |
| 147 |
using the library can be acquired using the pkg-config tool via |
| 148 |
|
| 149 |
PKG_CONFIG_PATH=$HOME/libsecrecy/lib/pkgconfig pkg-config libsecrecy --cflags --libs |
| 150 |
|
| 151 |
A simple example decryption program is |
| 152 |
|
| 153 |
``` |
| 154 |
#include <libsecrecy/GCMInputStream.hpp> |
| 155 |
#include <iostream> |
| 156 |
|
| 157 |
int main() |
| 158 |
{ |
| 159 |
libsecrecy::GCMInputStream GIS(std::cin); |
| 160 |
static std::size_t const buffersize = 16*1024; |
| 161 |
char B[buffersize]; |
| 162 |
|
| 163 |
while ( GIS ) |
| 164 |
{ |
| 165 |
GIS.read(&B[0],buffersize); |
| 166 |
std::cout.write(&B[0],GIS.gcount()); |
| 167 |
} |
| 168 |
} |
| 169 |
``` |
| 170 |
|
| 171 |
A simple encrypytion example program is |
| 172 |
|
| 173 |
``` |
| 174 |
#include <libsecrecy/GCMOutputStream.hpp> |
| 175 |
#include <iostream> |
| 176 |
|
| 177 |
int main() |
| 178 |
{ |
| 179 |
std::string const scipher = "AES256"; |
| 180 |
std::string const shexhash = "3E35C013C66C66B09E3E0B923451530C62D4346D9F5165906FC94B9B4D35E28E"; |
| 181 |
libsecrecy::GCMOutputStream GOS(std::cout,scipher,shexhash); |
| 182 |
static std::size_t const buffersize = 16*1024; |
| 183 |
char B[buffersize]; |
| 184 |
|
| 185 |
while ( std::cin ) |
| 186 |
{ |
| 187 |
std::cin.read(&B[0],buffersize); |
| 188 |
GOS.write(&B[0],std::cin.gcount()); |
| 189 |
} |
| 190 |
} |
| 191 |
``` |
| 192 |
|
| 193 |
Obviously you need to provide a value obtained using secrecry's createKey |
| 194 |
command as `shexhash`. |
| 195 |
|
| 196 |
# License |
| 197 |
|
| 198 |
libsecrecy is provided under a simplified (2 clause) BSD license (see COPYING). |