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