Merge branch 'vendor/GCC44'
[dragonfly.git] / contrib / cryptsetup / lib / libcryptsetup.h
1 #ifndef _LIBCRYPTSETUP_H
2 #define _LIBCRYPTSETUP_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif
6
7 #include <stdint.h>
8
9 struct crypt_device; /* crypt device handle */
10
11 /**
12  * Initialise crypt device handle and check if provided device exists.
13  *
14  * Returns 0 on success or negative errno value otherwise.
15  *
16  * @cd - returns pointer to crypt device handle
17  * @device - path to device
18  *
19  * Note that logging is not initialized here, possible messages uses
20  * default log function.
21  */
22 int crypt_init(struct crypt_device **cd, const char *device);
23
24 /**
25  * Initialise crypt device handle from provided active device name
26  * and check if provided device exists.
27  *
28  * Returns 0 on success or negative errno value otherwise.
29  *
30  * @cd - crypt device handle
31  * @name - name of active crypt device
32  */
33 int crypt_init_by_name(struct crypt_device **cd, const char *name);
34
35 /**
36  * Set log function.
37  *
38  * @cd - crypt device handle (can be NULL to set default log function)
39  * @usrptr - provided identification in callback
40  * @level  - log level below (debug messages can uses other levels)
41  * @msg    - log message
42  */
43 #define CRYPT_LOG_NORMAL 0
44 #define CRYPT_LOG_ERROR  1
45 #define CRYPT_LOG_VERBOSE  2
46 #define CRYPT_LOG_DEBUG -1 /* always on stdout */
47 void crypt_set_log_callback(struct crypt_device *cd,
48         void (*log)(int level, const char *msg, void *usrptr),
49         void *usrptr);
50
51 /**
52  * Log message through log function.
53  *
54  * @cd - crypt device handle
55  * @level  - log level
56  * @msg    - log message
57  */
58 void crypt_log(struct crypt_device *cd, int level, const char *msg);
59
60 /**
61  * Set confirmation callback (yes/no)
62  *
63  * If code need confirmation (like deleting last key slot) this function
64  * is called. If not defined, everything is confirmed.
65  *
66  * Calback should return 0 if operation is declined, other values mean accepted.
67  *
68  * @cd - crypt device handle
69  * @usrptr - provided identification in callback
70  * @msg - Message for user to confirm
71  */
72 void crypt_set_confirm_callback(struct crypt_device *cd,
73         int (*confirm)(const char *msg, void *usrptr),
74         void *usrptr);
75
76 /**
77  * Set password query callback.
78  *
79  * If code need _interactive_ query for password, this callback is called.
80  * If not defined, compiled-in default is called (uses terminal input).
81  *
82  * @cd - crypt device handle
83  * @usrptr - provided identification in callback
84  * @msg - Message for user
85  * @buf - buffer for password
86  * @length - size of buffer
87  *
88  * - Note that if this function is defined, verify option is ignored
89  *   (caller whch provided callback is responsible fo password verification)
90  * - Only zero terminated passwords can be enteted this way, for complex
91  *   API functions directly.
92  * - Maximal length of password is limited to @length-1 (minimal 511 chars)
93  */
94 void crypt_set_password_callback(struct crypt_device *cd,
95         int (*password)(const char *msg, char *buf, size_t length, void *usrptr),
96         void *usrptr);
97
98 /**
99  * Various crypt device parameters
100  *
101  * @cd - crypt device handle
102  * @timeout - timeout in secons for password entry if compiled-in function used
103  * @password_retry - number of tries for password if not verified
104  * @iteration_time - iteration time for LUKS header in miliseconds
105  * @password_verify - for compiled-in password query always verify passwords twice
106  */
107 void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
108 void crypt_set_password_retry(struct crypt_device *cd, int tries);
109 void crypt_set_iterarion_time(struct crypt_device *cd, uint64_t iteration_time_ms);
110 void crypt_set_password_verify(struct crypt_device *cd, int password_verify);
111
112 /**
113  * Helper to lock/unlock memory to avoid swap sensitive data to disk
114  *
115  * @cd - crypt device handle, can be NULL
116  * @lock - 0 to unloct otherwise lock memory
117  *
118  * Return value indicates that memory is locked (function can be called multiple times).
119  * Only root can do this. Note it locks/unlocks all process memory, not only crypt context.
120  */
121 int crypt_memory_lock(struct crypt_device *cd, int lock);
122
123 #define CRYPT_PLAIN "PLAIN" /* regular crypt device, no on-disk header */
124 #define CRYPT_LUKS1 "LUKS1" /* LUKS version 1 header on-disk */
125
126 struct crypt_params_plain {
127         const char *hash; /* password hash function */
128         uint64_t offset;  /* offset in sectors */
129         uint64_t skip;    /* IV initilisation sector */
130 };
131
132 struct crypt_params_luks1 {
133         const char *hash;      /* hash used in LUKS header */
134         size_t data_alignment; /* in sectors, data offset is multiple of this */
135 };
136
137 /**
138  * Create (format) new crypt device (and possible header on-disk) but not activates it.
139  *
140  * Returns 0 on success or negative errno value otherwise.
141  *
142  * @cd - crypt device handle
143  * @type - type of device (optional params struct must be of this type)
144  * @cipher - (e.g. "aes")
145  * @cipher_mode - including IV specification (e.g. "xts-plain")
146  * @uuid - requested UUID or NULL if it should be generated
147  * @volume_key - pre-generated volume key or NULL if it should be generated (only for LUKS)
148  * @volume_key_size - size og volume key in bytes.
149  * @params - crypt type specific parameters
150  *
151  * Note that crypt_format do not enable any keyslot, but it stores volume key internally
152  * and subsequent crypt_keyslot_add_* calls can be used.
153  * (It is the only situation when crypt_keyslot_add_* do not require active key slots.)
154  */
155 int crypt_format(struct crypt_device *cd,
156         const char *type,
157         const char *cipher,
158         const char *cipher_mode,
159         const char *uuid,
160         const char *volume_key,
161         size_t volume_key_size,
162         void *params);
163
164 /**
165  * Load crypt device parameters from on-disk header
166  *
167  * Returns 0 on success or negative errno value otherwise.
168  *
169  * @cd - crypt device handle
170  * @requested_type - use NULL for all known
171  * @params - crypt type specific parameters
172  */
173 int crypt_load(struct crypt_device *cd,
174                const char *requested_type,
175                void *params);
176
177 /**
178  * Suspends crypt device.
179  *
180  * Returns 0 on success or negative errno value otherwise.
181  *
182  * @cd - crypt device handle, can be NULL
183  * @name - name of device to suspend
184  */
185 int crypt_suspend(struct crypt_device *cd,
186                   const char *name);
187
188 /**
189  * Resumes crypt device using passphrase.
190  *
191  * Returns unlocked key slot number or negative errno otherwise.
192  *
193  * @cd - crypt device handle
194  * @name - name of device to resume
195  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
196  * @passphrase - passphrase used to unlock volume key, NULL for query
197  * @passphrase_size - size of @passphrase (binary data)
198  */
199 int crypt_resume_by_passphrase(struct crypt_device *cd,
200                                const char *name,
201                                int keyslot,
202                                const char *passphrase,
203                                size_t passphrase_size);
204
205 /**
206  * Resumes crypt device using key file.
207  *
208  * Returns unlocked key slot number or negative errno otherwise.
209  *
210  * @cd - crypt device handle
211  * @name - name of device to resume
212  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
213  * @keyfile - key file used to unlock volume key, NULL for passphrase query
214  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
215  */
216 int crypt_resume_by_keyfile(struct crypt_device *cd,
217                             const char *name,
218                             int keyslot,
219                             const char *keyfile,
220                             size_t keyfile_size);
221
222 /**
223  * Releases crypt device context and used memory.
224  *
225  * @cd - crypt device handle
226  */
227 void crypt_free(struct crypt_device *cd);
228
229 /**
230  * Add key slot using provided passphrase
231  *
232  * Returns allocated key slot number or negative errno otherwise.
233  *
234  * @cd - crypt device handle
235  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
236  * @passphrase - passphrase used to unlock volume key, NULL for query
237  * @passphrase_size - size of @passphrase (binary data)
238  * @new_passphrase - passphrase for new keyslot, NULL for query
239  * @new_passphrase_size - size of @new_passphrase (binary data)
240  */
241 #define CRYPT_ANY_SLOT -1
242 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
243         int keyslot,
244         const char *passphrase,
245         size_t passphrase_size,
246         const char *new_passphrase,
247         size_t new_passphrase_size);
248
249 /**
250 * Add key slot using provided key file path
251  *
252  * Returns allocated key slot number or negative errno otherwise.
253  *
254  * @cd - crypt device handle
255  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
256  * @keyfile - key file used to unlock volume key, NULL for passphrase query
257  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
258  * @new_keyfile - keyfile for new keyslot, NULL for passphrase query
259  * @new_keyfile_size - number of bytes to read from @new_keyfile, 0 is unlimited
260  *
261  * Note that @keyfile can be "-" for STDIN
262  */
263 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
264         int keyslot,
265         const char *keyfile,
266         size_t keyfile_size,
267         const char *new_keyfile,
268         size_t new_keyfile_size);
269
270 /**
271  * Add key slot using provided volume key
272  *
273  * Returns allocated key slot number or negative errno otherwise.
274  *
275  * @cd - crypt device handle
276  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
277  * @volume_key - provided volume key or NULL if used after crypt_format
278  * @volume_key_size - size of @volume_key
279  * @passphrase - passphrase for new keyslot, NULL for query
280  * @passphrase_size - size of @passphrase
281  */
282 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
283         int keyslot,
284         const char *volume_key,
285         size_t volume_key_size,
286         const char *passphrase,
287         size_t passphrase_size);
288
289 /**
290  * Destroy (and disable) key slot
291  *
292  * Returns 0 on success or negative errno value otherwise.
293  *
294  * @cd - crypt device handle
295  * @keyslot - requested key slot to destroy
296  *
297  * Note that there is no passphrase verification used.
298  */
299 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
300
301 /**
302  * Activation flags
303  */
304 #define CRYPT_ACTIVATE_READONLY (1 << 0)
305 #define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
306
307 /**
308  * Activate device or check passphrase
309  *
310  * Returns unlocked key slot number or negative errno otherwise.
311  *
312  * @cd - crypt device handle
313  * @name - name of device to create, if NULL only check passphrase
314  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
315  * @passphrase - passphrase used to unlock volume key, NULL for query
316  * @passphrase_size - size of @passphrase
317  * @flags - activation flags
318  */
319 int crypt_activate_by_passphrase(struct crypt_device *cd,
320         const char *name,
321         int keyslot,
322         const char *passphrase,
323         size_t passphrase_size,
324         uint32_t flags);
325
326 /**
327  * Activate device or check using key file
328  *
329  * Returns unlocked key slot number or negative errno otherwise.
330  *
331  * @cd - crypt device handle
332  * @name - name of device to create, if NULL only check keyfile
333  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
334  * @keyfile - key file used to unlock volume key
335  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
336  * @flags - activation flags
337  */
338 int crypt_activate_by_keyfile(struct crypt_device *cd,
339         const char *name,
340         int keyslot,
341         const char *keyfile,
342         size_t keyfile_size,
343         uint32_t flags);
344
345 /**
346  * Activate device using provided volume key
347  *
348  * Returns 0 on success or negative errno value otherwise.
349  *
350  * @cd - crypt device handle
351  * @name - name of device to create, if NULL only check volume key
352  * @volume_key - provided volume key
353  * @volume_key_size - size of @volume_key
354  * @flags - activation flags
355  */
356 int crypt_activate_by_volume_key(struct crypt_device *cd,
357         const char *name,
358         const char *volume_key,
359         size_t volume_key_size,
360         uint32_t flags);
361
362 /**
363  * Deactivate crypt device
364  *
365  * @cd - crypt device handle, can be NULL
366  * @name - name of device to deactivate
367   */
368 int crypt_deactivate(struct crypt_device *cd, const char *name);
369
370 /**
371  * Get volume key from of crypt device
372  *
373  * Returns unlocked key slot number or negative errno otherwise.
374  *
375  * @cd - crypt device handle
376  * @keyslot - use this keyslot or CRYPT_ANY_SLOT
377  * @volume_key - buffer for volume key
378  * @volume_key_size - on input, size of buffer @volume_key,
379  *                    on output size of @volume_key
380  * @passphrase - passphrase used to unlock volume key, NULL for query
381  * @passphrase_size - size of @passphrase
382  */
383 int crypt_volume_key_get(struct crypt_device *cd,
384         int keyslot,
385         char *volume_key,
386         size_t *volume_key_size,
387         const char *passphrase,
388         size_t passphrase_size);
389
390 /**
391  * Verify that provided volume key is valid for crypt device
392  *
393  * Returns 0 on success or negative errno value otherwise.
394  *
395  * @cd - crypt device handle
396  * @volume_key - provided volume key
397  * @volume_key_size - size of @volume_key
398  */
399 int crypt_volume_key_verify(struct crypt_device *cd,
400         const char *volume_key,
401         size_t volume_key_size);
402
403 /**
404  * Get status info about device name
405  *
406  * Returns value defined by crypt_status_info.
407  *
408  * @cd - crypt device handle, can be NULL
409  * @name -crypt device name
410  *
411  * CRYPT_INACTIVE - no such mapped device
412  * CRYPT_ACTIVE - device is active
413  * CRYPT_BUSY - device is active and has open count > 0
414  */
415 typedef enum {
416         CRYPT_INVALID,
417         CRYPT_INACTIVE,
418         CRYPT_ACTIVE,
419         CRYPT_BUSY
420 } crypt_status_info;
421 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
422
423 /**
424  * Dump text-formatted information about crypt device to log output
425  *
426  * Returns 0 on success or negative errno value otherwise.
427  *
428  * @cd - crypt device handle, can be NULL
429  */
430 int crypt_dump(struct crypt_device *cd);
431
432 /**
433  * Various crypt device info functions
434  *
435  * @cd - crypt device handle
436  *
437  * cipher - used cipher, e.g. "aes" or NULL otherwise
438  * cipher_mode - used cipher mode including IV, e.g. "xts-plain" or NULL otherwise
439  * uuid - device UUID or NULL if not set
440  * data_offset - device offset in sectors where real data starts on underlying device)
441  * volume_key_size - size (in bytes) of volume key for crypt device
442  */
443 const char *crypt_get_cipher(struct crypt_device *cd);
444 const char *crypt_get_cipher_mode(struct crypt_device *cd);
445 const char *crypt_get_uuid(struct crypt_device *cd);
446 uint64_t crypt_get_data_offset(struct crypt_device *cd);
447 int crypt_get_volume_key_size(struct crypt_device *cd);
448
449 /**
450  * Get information about particular key slot
451  *
452  * Returns value defined by crypt_keyslot_info.
453  *
454  * @cd - crypt device handle
455  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
456  */
457 typedef enum {
458         CRYPT_SLOT_INVALID,
459         CRYPT_SLOT_INACTIVE,
460         CRYPT_SLOT_ACTIVE,
461         CRYPT_SLOT_ACTIVE_LAST
462 } crypt_keyslot_info;
463 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
464
465 /**
466  * Backup header and keyslots to file
467  *
468  * Returns 0 on success or negative errno value otherwise.
469  *
470  * @cd - crypt device handle
471  * @requested_type - type of header to backup
472  * @backup_file - file to backup header to
473  */
474 int crypt_header_backup(struct crypt_device *cd,
475         const char *requested_type,
476         const char *backup_file);
477
478 /**
479  * Restore header and keyslots from backup file
480  *
481  * Returns 0 on success or negative errno value otherwise.
482  *
483  * @cd - crypt device handle
484  * @requested_type - type of header to restore
485  * @backup_file - file to restore header from
486  */
487 int crypt_header_restore(struct crypt_device *cd,
488         const char *requested_type,
489         const char *backup_file);
490
491 /**
492  * Receives last reported error
493  *
494  * @buf - buffef for message
495  * @size - size of buffer
496  *
497  * Note that this is old API function using global context.
498  * All error messages are reported also through log callback.
499  */
500 void crypt_get_error(char *buf, size_t size);
501
502 /**
503  * Get directory where mapped crypt devices are created
504  */
505 const char *crypt_get_dir(void);
506
507 /**
508  * Set library debug level
509  */
510 #define CRYPT_DEBUG_ALL  -1
511 #define CRYPT_DEBUG_NONE  0
512 void crypt_set_debug_level(int level);
513
514 /**
515  * OLD DEPRECATED API **********************************
516  *
517  * Provided only for backward compatibility.
518  */
519
520 struct interface_callbacks {
521     int (*yesDialog)(char *msg);
522     void (*log)(int level, char *msg);
523 };
524
525 #define CRYPT_FLAG_VERIFY               (1 << 0)
526 #define CRYPT_FLAG_READONLY             (1 << 1)
527 #define CRYPT_FLAG_VERIFY_IF_POSSIBLE   (1 << 2)
528 #define CRYPT_FLAG_VERIFY_ON_DELKEY     (1 << 3)
529 #define CRYPT_FLAG_NON_EXCLUSIVE_ACCESS (1 << 4)
530
531 struct crypt_options {
532         const char      *name;
533         const char      *device;
534
535         const char      *cipher;
536         const char      *hash;
537
538         const char      *passphrase;
539         int             passphrase_fd;
540         const char      *key_file;
541         const char      *new_key_file;
542         int             key_size;
543
544         unsigned int    flags;
545         int             key_slot;
546
547         uint64_t        size;
548         uint64_t        offset;
549         uint64_t        skip;
550         uint64_t        iteration_time;
551         uint64_t        timeout;
552
553         uint64_t        align_payload;
554         int             tries;
555
556         struct interface_callbacks *icb;
557 };
558
559 int crypt_create_device(struct crypt_options *options);
560 int crypt_update_device(struct crypt_options *options);
561 int crypt_resize_device(struct crypt_options *options);
562 int crypt_query_device(struct crypt_options *options);
563 int crypt_remove_device(struct crypt_options *options);
564 int crypt_luksFormat(struct crypt_options *options);
565 int crypt_luksOpen(struct crypt_options *options);
566 int crypt_luksKillSlot(struct crypt_options *options);
567 int crypt_luksRemoveKey(struct crypt_options *options);
568 int crypt_luksAddKey(struct crypt_options *options);
569 int crypt_luksUUID(struct crypt_options *options);
570 int crypt_isLuks(struct crypt_options *options);
571 int crypt_luksDump(struct crypt_options *options);
572
573 void crypt_put_options(struct crypt_options *options);
574
575 #ifdef __cplusplus
576 }
577 #endif
578 #endif /* _LIBCRYPTSETUP_H */