Debian Codegraph @

README

raw
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).