1 /*
2  * Library to access the Linux Unified Key Setup (LUKS) Disk Encryption format
3  *
4  * Copyright (C) 2013-2020, Joachim Metz <joachim.metz@gmail.com>
5  *
6  * Refer to AUTHORS for acknowledgements.
7  *
8  * This program is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation, either version 3 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
20  */
21 
22 #if !defined( _LIBLUKSDE_H )
23 #define _LIBLUKSDE_H
24 
25 #include <libluksde/codepage.h>
26 #include <libluksde/definitions.h>
27 #include <libluksde/error.h>
28 #include <libluksde/extern.h>
29 #include <libluksde/features.h>
30 #include <libluksde/types.h>
31 
32 #include <stdio.h>
33 
34 #if defined( LIBLUKSDE_HAVE_BFIO )
35 #include <libbfio.h>
36 #endif
37 
38 #if defined( __cplusplus )
39 extern "C" {
40 #endif
41 
42 /* -------------------------------------------------------------------------
43  * Support functions
44  * ------------------------------------------------------------------------- */
45 
46 /* Returns the library version
47  */
48 LIBLUKSDE_EXTERN \
49 const char *libluksde_get_version(
50              void );
51 
52 /* Returns the access flags for reading
53  */
54 LIBLUKSDE_EXTERN \
55 int libluksde_get_access_flags_read(
56      void );
57 
58 /* Retrieves the narrow system string codepage
59  * A value of 0 represents no codepage, UTF-8 encoding is used instead
60  * Returns 1 if successful or -1 on error
61  */
62 LIBLUKSDE_EXTERN \
63 int libluksde_get_codepage(
64      int *codepage,
65      libluksde_error_t **error );
66 
67 /* Sets the narrow system string codepage
68  * A value of 0 represents no codepage, UTF-8 encoding is used instead
69  * Returns 1 if successful or -1 on error
70  */
71 LIBLUKSDE_EXTERN \
72 int libluksde_set_codepage(
73      int codepage,
74      libluksde_error_t **error );
75 
76 /* Determines if a file contains a LUKS volume signature
77  * Returns 1 if true, 0 if not or -1 on error
78  */
79 LIBLUKSDE_EXTERN \
80 int libluksde_check_volume_signature(
81      const char *filename,
82      libluksde_error_t **error );
83 
84 /* Determines if a file contains a LUKS volume signature
85  * Returns 1 if true, 0 if not or -1 on error
86  */
87 LIBLUKSDE_EXTERN \
88 int libluksde_check_volume_signature_wide(
89      const wchar_t *filename,
90      libluksde_error_t **error );
91 
92 #if defined( LIBLUKSDE_HAVE_BFIO )
93 
94 /* Determines if a file contains a LUKS volume signature using a Basic File IO (bfio) handle
95  * Returns 1 if true, 0 if not or -1 on error
96  */
97 LIBLUKSDE_EXTERN \
98 int libluksde_check_volume_signature_file_io_handle(
99      libbfio_handle_t *file_io_handle,
100      libluksde_error_t **error );
101 
102 #endif /* defined( LIBLUKSDE_HAVE_BFIO ) */
103 
104 /* -------------------------------------------------------------------------
105  * Notify functions
106  * ------------------------------------------------------------------------- */
107 
108 /* Sets the verbose notification
109  */
110 LIBLUKSDE_EXTERN \
111 void libluksde_notify_set_verbose(
112       int verbose );
113 
114 /* Sets the notification stream
115  * Returns 1 if successful or -1 on error
116  */
117 LIBLUKSDE_EXTERN \
118 int libluksde_notify_set_stream(
119      FILE *stream,
120      libluksde_error_t **error );
121 
122 /* Opens the notification stream using a filename
123  * The stream is opened in append mode
124  * Returns 1 if successful or -1 on error
125  */
126 LIBLUKSDE_EXTERN \
127 int libluksde_notify_stream_open(
128      const char *filename,
129      libluksde_error_t **error );
130 
131 /* Closes the notification stream if opened using a filename
132  * Returns 0 if successful or -1 on error
133  */
134 LIBLUKSDE_EXTERN \
135 int libluksde_notify_stream_close(
136      libluksde_error_t **error );
137 
138 /* -------------------------------------------------------------------------
139  * Error functions
140  * ------------------------------------------------------------------------- */
141 
142 /* Frees an error
143  */
144 LIBLUKSDE_EXTERN \
145 void libluksde_error_free(
146       libluksde_error_t **error );
147 
148 /* Prints a descriptive string of the error to the stream
149  * Returns the number of printed characters if successful or -1 on error
150  */
151 LIBLUKSDE_EXTERN \
152 int libluksde_error_fprint(
153      libluksde_error_t *error,
154      FILE *stream );
155 
156 /* Prints a descriptive string of the error to the string
157  * The end-of-string character is not included in the return value
158  * Returns the number of printed characters if successful or -1 on error
159  */
160 LIBLUKSDE_EXTERN \
161 int libluksde_error_sprint(
162      libluksde_error_t *error,
163      char *string,
164      size_t size );
165 
166 /* Prints a backtrace of the error to the stream
167  * Returns the number of printed characters if successful or -1 on error
168  */
169 LIBLUKSDE_EXTERN \
170 int libluksde_error_backtrace_fprint(
171      libluksde_error_t *error,
172      FILE *stream );
173 
174 /* Prints a backtrace of the error to the string
175  * The end-of-string character is not included in the return value
176  * Returns the number of printed characters if successful or -1 on error
177  */
178 LIBLUKSDE_EXTERN \
179 int libluksde_error_backtrace_sprint(
180      libluksde_error_t *error,
181      char *string,
182      size_t size );
183 
184 /* -------------------------------------------------------------------------
185  * Volume functions
186  * ------------------------------------------------------------------------- */
187 
188 /* Creates a volume
189  * Make sure the value value is referencing, is set to NULL
190  * Returns 1 if successful or -1 on error
191  */
192 LIBLUKSDE_EXTERN \
193 int libluksde_volume_initialize(
194      libluksde_volume_t **volume,
195      libluksde_error_t **error );
196 
197 /* Frees a volume
198  * Returns 1 if successful or -1 on error
199  */
200 LIBLUKSDE_EXTERN \
201 int libluksde_volume_free(
202      libluksde_volume_t **volume,
203      libluksde_error_t **error );
204 
205 /* Signals the volume to abort its current activity
206  * Returns 1 if successful or -1 on error
207  */
208 LIBLUKSDE_EXTERN \
209 int libluksde_volume_signal_abort(
210      libluksde_volume_t *volume,
211      libluksde_error_t **error );
212 
213 /* Opens a volume
214  * Returns 1 if successful, 0 if the keys could not be read or -1 on error
215  */
216 LIBLUKSDE_EXTERN \
217 int libluksde_volume_open(
218      libluksde_volume_t *volume,
219      const char *filename,
220      int access_flags,
221      libluksde_error_t **error );
222 
223 #if defined( LIBLUKSDE_HAVE_WIDE_CHARACTER_TYPE )
224 
225 /* Opens a volume
226  * Returns 1 if successful, 0 if the keys could not be read or -1 on error
227  */
228 LIBLUKSDE_EXTERN \
229 int libluksde_volume_open_wide(
230      libluksde_volume_t *volume,
231      const wchar_t *filename,
232      int access_flags,
233      libluksde_error_t **error );
234 
235 #endif /* defined( LIBLUKSDE_HAVE_WIDE_CHARACTER_TYPE ) */
236 
237 #if defined( LIBLUKSDE_HAVE_BFIO )
238 
239 /* Opens a volume using a Basic File IO (bfio) handle
240  * Returns 1 if successful, 0 if the keys could not be read or -1 on error
241  */
242 LIBLUKSDE_EXTERN \
243 int libluksde_volume_open_file_io_handle(
244      libluksde_volume_t *volume,
245      libbfio_handle_t *file_io_handle,
246      int access_flags,
247      libluksde_error_t **error );
248 
249 #endif /* defined( LIBLUKSDE_HAVE_BFIO ) */
250 
251 /* Closes a volume
252  * Returns 0 if successful or -1 on error
253  */
254 LIBLUKSDE_EXTERN \
255 int libluksde_volume_close(
256      libluksde_volume_t *volume,
257      libluksde_error_t **error );
258 
259 /* Determines if the volume is locked
260  * Returns 1 if locked, 0 if not or -1 on error
261  */
262 LIBLUKSDE_EXTERN \
263 int libluksde_volume_is_locked(
264      libluksde_volume_t *volume,
265      libluksde_error_t **error );
266 
267 /* Reads data at the current offset into a buffer
268  * Returns the number of bytes read or -1 on error
269  */
270 LIBLUKSDE_EXTERN \
271 ssize_t libluksde_volume_read_buffer(
272          libluksde_volume_t *volume,
273          void *buffer,
274          size_t buffer_size,
275          libluksde_error_t **error );
276 
277 /* Reads (media) data at a specific offset
278  * Returns the number of bytes read or -1 on error
279  */
280 LIBLUKSDE_EXTERN \
281 ssize_t libluksde_volume_read_buffer_at_offset(
282          libluksde_volume_t *volume,
283          void *buffer,
284          size_t buffer_size,
285          off64_t offset,
286          libluksde_error_t **error );
287 
288 #ifdef TODO_WRITE_SUPPORT
289 
290 /* Writes (media) data at the current offset
291  * Returns the number of input bytes written, 0 when no longer bytes can be written or -1 on error
292  */
293 LIBLUKSDE_EXTERN \
294 ssize_t libluksde_volume_write_buffer(
295          libluksde_volume_t *volume,
296          void *buffer,
297          size_t buffer_size,
298          libluksde_error_t **error );
299 
300 /* Writes (media) data at a specific offset,
301  * Returns the number of input bytes written, 0 when no longer bytes can be written or -1 on error
302  */
303 LIBLUKSDE_EXTERN \
304 ssize_t libluksde_volume_write_buffer_at_offset(
305          libluksde_volume_t *volume,
306          const void *buffer,
307          size_t buffer_size,
308          off64_t offset,
309          libluksde_error_t **error );
310 
311 #endif /* TODO_WRITE_SUPPORT */
312 
313 /* Seeks a certain offset of the data
314  * Returns the offset if seek is successful or -1 on error
315  */
316 LIBLUKSDE_EXTERN \
317 off64_t libluksde_volume_seek_offset(
318          libluksde_volume_t *volume,
319          off64_t offset,
320          int whence,
321          libluksde_error_t **error );
322 
323 /* Retrieves the the current offset of the (volume) data
324  * Returns 1 if successful or -1 on error
325  */
326 LIBLUKSDE_EXTERN \
327 int libluksde_volume_get_offset(
328      libluksde_volume_t *volume,
329      off64_t *offset,
330      libluksde_error_t **error );
331 
332 /* Retrieves the size
333  * Returns 1 if successful or -1 on error
334  */
335 LIBLUKSDE_EXTERN \
336 int libluksde_volume_get_size(
337      libluksde_volume_t *volume,
338      size64_t *size,
339      libluksde_error_t **error );
340 
341 /* Retrieves the encryption method
342  * Returns 1 if successful or -1 on error
343  */
344 LIBLUKSDE_EXTERN \
345 int libluksde_volume_get_encryption_method(
346      libluksde_volume_t *volume,
347      int *encryption_method,
348      int *encryption_chaining_mode,
349      libluksde_error_t **error );
350 
351 /* Retrieves the volume identifier
352  * The identifier is an UUID and is 16 bytes of size
353  * Returns 1 if successful, 0 if not or or -1 on error
354  */
355 LIBLUKSDE_EXTERN \
356 int libluksde_volume_get_volume_identifier(
357      libluksde_volume_t *volume,
358      uint8_t *uuid_data,
359      size_t uuid_data_size,
360      libluksde_error_t **error );
361 
362 /* Sets the key
363  * This function needs to be used before one of the open functions
364  * Returns 1 if successful or -1 on error
365  */
366 LIBLUKSDE_EXTERN \
367 int libluksde_volume_set_key(
368      libluksde_volume_t *volume,
369      const uint8_t *master_key,
370      size_t master_key_size,
371      libluksde_error_t **error );
372 
373 /* Sets the keys
374  * This function needs to be used before one of the open functions
375  *
376  * This function deprecated use libluksde_volume_set_key instead
377  *
378  * Returns 1 if successful or -1 on error
379  */
380 LIBLUKSDE_DEPRECATED \
381 LIBLUKSDE_EXTERN \
382 int libluksde_volume_set_keys(
383      libluksde_volume_t *volume,
384      const uint8_t *master_key,
385      size_t master_key_size,
386      libluksde_error_t **error );
387 
388 /* Sets an UTF-8 formatted password
389  * This function needs to be used before one of the open functions
390  * Returns 1 if successful, 0 if password is invalid or -1 on error
391  */
392 LIBLUKSDE_EXTERN \
393 int libluksde_volume_set_utf8_password(
394      libluksde_volume_t *volume,
395      const uint8_t *utf8_string,
396      size_t utf8_string_length,
397      libluksde_error_t **error );
398 
399 /* Sets an UTF-16 formatted password
400  * This function needs to be used before one of the open functions
401  * Returns 1 if successful, 0 if password is invalid or -1 on error
402  */
403 LIBLUKSDE_EXTERN \
404 int libluksde_volume_set_utf16_password(
405      libluksde_volume_t *volume,
406      const uint16_t *utf16_string,
407      size_t utf16_string_length,
408      libluksde_error_t **error );
409 
410 #if defined( __cplusplus )
411 }
412 #endif
413 
414 #endif /* !defined( _LIBLUKSDE_H ) */
415