eessppeelllloo/cryptsetup
1
0
Fork 0
mirror of https://gitlab.com/cryptsetup/cryptsetup.git synced 2025-12-13 11:50:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update libcryptsetup.h comments.

Browse Source
This commit is contained in:
Milan Broz
2015-08-26 16:10:10 +02:00
parent 7843415243
commit def397d0c8
1 changed files with 60 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
lib/libcryptsetup.h
View File

@@ -136,7 +136,7 @@ void crypt_log(struct crypt_device *cd, int level, const char *msg);
/** @} */ /** @} */
/** /**
* Set confirmation callback (yes/no) * Set confirmation callback (yes/no).
* *
* If code need confirmation (like resetting uuid or restoring LUKS header from file) * If code need confirmation (like resetting uuid or restoring LUKS header from file)
* this function is called. If not defined, everything is confirmed. * this function is called. If not defined, everything is confirmed.
@@ -156,7 +156,7 @@ void crypt_set_confirm_callback(struct crypt_device *cd,
void *usrptr); void *usrptr);
/** /**
* Set password query callback. * Set password query callback. DEPRECATED
* *
* If code need @e _interactive_ query for password, this callback is called. * If code need @e _interactive_ query for password, this callback is called.
* If not defined, compiled-in default is called (uses terminal input). * If not defined, compiled-in default is called (uses terminal input).
@@ -176,8 +176,7 @@ void crypt_set_confirm_callback(struct crypt_device *cd,
* @note Only zero terminated passwords can be entered this way, for complex * @note Only zero terminated passwords can be entered this way, for complex
* use API functions directly. * use API functions directly.
* @note Maximal length of password is limited to @e length @e - @e 1 (minimal 511 chars) * @note Maximal length of password is limited to @e length @e - @e 1 (minimal 511 chars)
* @note Internal compiled-in terminal input is DEPRECATED and will be removed * @note This function is DEPRECATED and will be removed in future versions.
* in future versions.
* *
* @see Callback function is used in these call provided, that certain conditions are met: * @see Callback function is used in these call provided, that certain conditions are met:
* @li crypt_keyslot_add_by_passphrase * @li crypt_keyslot_add_by_passphrase
@@ -194,7 +193,7 @@ void crypt_set_password_callback(struct crypt_device *cd,
/** /**
* Set timeout for interactive password entry using default * Set timeout for interactive password entry using default
* password callback * password callback. DEPRECATED
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param timeout_sec timeout in seconds * @param timeout_sec timeout in seconds
@@ -202,16 +201,18 @@ void crypt_set_password_callback(struct crypt_device *cd,
void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec); void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
/** /**
* Set number of retries in case password input has been incorrect * Set number of retries in case password input has been incorrect. DEPRECATED.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param tries the number * @param tries the number
*
* @note This function is DEPRECATED and will be removed in future versions.
*/ */
void crypt_set_password_retry(struct crypt_device *cd, int tries); void crypt_set_password_retry(struct crypt_device *cd, int tries);
/** /**
* Set how long should cryptsetup iterate in PBKDF2 function. * Set how long should cryptsetup iterate in PBKDF2 function.
* Default value heads towards the iterations which takes around 1 second * Default value heads towards the iterations which takes around 1 second.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param iteration_time_ms the time in ms * @param iteration_time_ms the time in ms
@@ -222,10 +223,12 @@ void crypt_set_iterarion_time(struct crypt_device *cd, uint64_t iteration_time_m
/** /**
* Set whether passphrase will be verified on input * Set whether passphrase will be verified on input
* (user has to input same passphrase twice) * (user has to input same passphrase twice). DEPRECATED
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param password_verify @e 0 = false, @e !0 true * @param password_verify @e 0 = false, @e !0 true
*
* @note This function is DEPRECATED and will be removed in future versions.
*/ */
void crypt_set_password_verify(struct crypt_device *cd, int password_verify); void crypt_set_password_verify(struct crypt_device *cd, int password_verify);
@@ -263,7 +266,7 @@ int crypt_set_data_device(struct crypt_device *cd, const char *device);
void crypt_set_rng_type(struct crypt_device *cd, int rng_type); void crypt_set_rng_type(struct crypt_device *cd, int rng_type);
/** /**
* Get which RNG (random number generator) is used for generating long term key * Get which RNG (random number generator) is used for generating long term key.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @return RNG type on success or negative errno value otherwise. * @return RNG type on success or negative errno value otherwise.
@@ -274,7 +277,7 @@ int crypt_get_rng_type(struct crypt_device *cd);
/** @} */ /** @} */
/** /**
* Helper to lock/unlock memory to avoid swap sensitive data to disk * Helper to lock/unlock memory to avoid swap sensitive data to disk.
* *
* @param cd crypt device handle, can be @e NULL * @param cd crypt device handle, can be @e NULL
* @param lock 0 to unlock otherwise lock memory * @param lock 0 to unlock otherwise lock memory
@@ -319,7 +322,7 @@ const char *crypt_get_type(struct crypt_device *cd);
/** /**
* *
* Structure used as parameter for PLAIN device type * Structure used as parameter for PLAIN device type.
* *
* @see crypt_format * @see crypt_format
*/ */
@@ -331,7 +334,7 @@ struct crypt_params_plain {
}; };
/** /**
* Structure used as parameter for LUKS device type * Structure used as parameter for LUKS device type.
* *
* @see crypt_format, crypt_load * @see crypt_format, crypt_load
* *
@@ -347,7 +350,7 @@ struct crypt_params_luks1 {
/** /**
* *
* Structure used as parameter for loop-AES device type * Structure used as parameter for loop-AES device type.
* *
* @see crypt_format * @see crypt_format
* *
@@ -360,7 +363,7 @@ struct crypt_params_loopaes {
/** /**
* *
* Structure used as parameter for dm-verity device type * Structure used as parameter for dm-verity device type.
* *
* @see crypt_format, crypt_load * @see crypt_format, crypt_load
* *
@@ -388,7 +391,7 @@ struct crypt_params_verity {
/** /**
* *
* Structure used as parameter for TCRYPT device type * Structure used as parameter for TCRYPT device type.
* *
* @see crypt_load * @see crypt_load
* *
@@ -422,7 +425,7 @@ struct crypt_params_tcrypt {
/** @} */ /** @} */
/** /**
* Create (format) new crypt device (and possible header on-disk) but not activates it. * Create (format) new crypt device (and possible header on-disk) but do not activate it.
* *
* @pre @e cd contains initialized and not formatted device context (device type must @b not be set) * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
* *
@@ -452,7 +455,7 @@ int crypt_format(struct crypt_device *cd,
void *params); void *params);
/** /**
* Set new UUID for already existing device * Set new UUID for already existing device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param uuid requested UUID or @e NULL if it should be generated * @param uuid requested UUID or @e NULL if it should be generated
@@ -465,7 +468,7 @@ int crypt_set_uuid(struct crypt_device *cd,
const char *uuid); const char *uuid);
/** /**
* Load crypt device parameters from on-disk header * Load crypt device parameters from on-disk header.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param requested_type @link crypt_type @endlink or @e NULL for all known * @param requested_type @link crypt_type @endlink or @e NULL for all known
@@ -484,7 +487,7 @@ int crypt_load(struct crypt_device *cd,
void *params); void *params);
/** /**
* Try to repair crypt device on-disk header if invalid * Try to repair crypt device on-disk header if invalid.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param requested_type @link crypt_type @endlink or @e NULL for all known * @param requested_type @link crypt_type @endlink or @e NULL for all known
@@ -498,7 +501,7 @@ int crypt_repair(struct crypt_device *cd,
void *params); void *params);
/** /**
* Resize crypt device * Resize crypt device.
* *
* @param cd - crypt device handle * @param cd - crypt device handle
* @param name - name of device to resize * @param name - name of device to resize
@@ -511,7 +514,7 @@ int crypt_resize(struct crypt_device *cd,
uint64_t new_size); uint64_t new_size);
/** /**
* Suspends crypt device. * Suspend crypt device.
* *
* @param cd crypt device handle, can be @e NULL * @param cd crypt device handle, can be @e NULL
* @param name name of device to suspend * @param name name of device to suspend
@@ -525,7 +528,7 @@ int crypt_suspend(struct crypt_device *cd,
const char *name); const char *name);
/** /**
* Resumes crypt device using passphrase. * Resume crypt device using passphrase.
* *
* *
* @param cd crypt device handle * @param cd crypt device handle
@@ -547,7 +550,7 @@ int crypt_resume_by_passphrase(struct crypt_device *cd,
size_t passphrase_size); size_t passphrase_size);
/** /**
* Resumes crypt device using key file. * Resume crypt device using key file.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param name name of device to resume * @param name name of device to resume
@@ -577,7 +580,7 @@ int crypt_resume_by_keyfile(struct crypt_device *cd,
size_t keyfile_size); size_t keyfile_size);
/** /**
* Releases crypt device context and used memory. * Release crypt device context and used memory.
* *
* @param cd crypt device handle * @param cd crypt device handle
*/ */
@@ -594,7 +597,7 @@ void crypt_free(struct crypt_device *cd);
#define CRYPT_ANY_SLOT -1 #define CRYPT_ANY_SLOT -1
/** /**
* Add key slot using provided passphrase * Add key slot using provided passphrase.
* *
* @pre @e cd contains initialized and formatted LUKS device context * @pre @e cd contains initialized and formatted LUKS device context
* *
@@ -618,7 +621,7 @@ int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
size_t new_passphrase_size); size_t new_passphrase_size);
/** /**
* Change defined key slot using provided passphrase * Change defined key slot using provided passphrase.
* *
* @pre @e cd contains initialized and formatted LUKS device context * @pre @e cd contains initialized and formatted LUKS device context
* *
@@ -648,7 +651,7 @@ int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
size_t new_passphrase_size); size_t new_passphrase_size);
/** /**
* Add key slot using provided key file path * Add key slot using provided key file path.
* *
* @pre @e cd contains initialized and formatted LUKS device context * @pre @e cd contains initialized and formatted LUKS device context
* *
@@ -663,7 +666,8 @@ int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
* *
* @return allocated key slot number or negative errno otherwise. * @return allocated key slot number or negative errno otherwise.
* *
* @note Note that @e keyfile can be "-" for STDIN * @note Note that @e keyfile can be "-" for STDIN. This special handling is DEPRECATED
* and will be removed in next version.
*/ */
int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd, int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
int keyslot, int keyslot,
@@ -684,7 +688,7 @@ int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
size_t new_keyfile_size); size_t new_keyfile_size);
/** /**
* Add key slot using provided volume key * Add key slot using provided volume key.
* *
* @pre @e cd contains initialized and formatted LUKS device context * @pre @e cd contains initialized and formatted LUKS device context
* *
@@ -708,7 +712,7 @@ int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
size_t passphrase_size); size_t passphrase_size);
/** /**
* Destroy (and disable) key slot * Destroy (and disable) key slot.
* *
* @pre @e cd contains initialized and formatted LUKS device context * @pre @e cd contains initialized and formatted LUKS device context
* *
@@ -761,7 +765,7 @@ struct crypt_active_device {
}; };
/** /**
* Receives runtime attributes of active crypt device * Receive runtime attributes of active crypt device.
* *
* @param cd crypt device handle (can be @e NULL) * @param cd crypt device handle (can be @e NULL)
* @param name name of active device * @param name name of active device
@@ -777,7 +781,7 @@ int crypt_get_active_device(struct crypt_device *cd,
/** @} */ /** @} */
/** /**
* Activate device or check passphrase * Activate device or check passphrase.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param name name of device to create, if @e NULL only check passphrase * @param name name of device to create, if @e NULL only check passphrase
@@ -799,7 +803,7 @@ int crypt_activate_by_passphrase(struct crypt_device *cd,
uint32_t flags); uint32_t flags);
/** /**
* Activate device or check using key file * Activate device or check using key file.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param name name of device to create, if @e NULL only check keyfile * @param name name of device to create, if @e NULL only check keyfile
@@ -829,7 +833,7 @@ int crypt_activate_by_keyfile(struct crypt_device *cd,
uint32_t flags); uint32_t flags);
/** /**
* Activate device using provided volume key * Activate device using provided volume key.
* *
* *
* @param cd crypt device handle * @param cd crypt device handle
@@ -869,7 +873,7 @@ int crypt_activate_by_volume_key(struct crypt_device *cd,
int crypt_deactivate(struct crypt_device *cd, const char *name); int crypt_deactivate(struct crypt_device *cd, const char *name);
/** /**
* Get volume key from of crypt device * Get volume key from crypt device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param keyslot use this keyslot or @e CRYPT_ANY_SLOT * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
@@ -892,7 +896,7 @@ int crypt_volume_key_get(struct crypt_device *cd,
size_t passphrase_size); size_t passphrase_size);
/** /**
* Verify that provided volume key is valid for crypt device * Verify that provided volume key is valid for crypt device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param volume_key provided volume key * @param volume_key provided volume key
@@ -921,7 +925,7 @@ typedef enum {
} crypt_status_info; } crypt_status_info;
/** /**
* Get status info about device name * Get status info about device name.
* *
* @param cd crypt device handle, can be @e NULL * @param cd crypt device handle, can be @e NULL
* @param name crypt device name * @param name crypt device name
@@ -932,7 +936,7 @@ typedef enum {
crypt_status_info crypt_status(struct crypt_device *cd, const char *name); crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
/** /**
* Dump text-formatted information about crypt or verity device to log output * Dump text-formatted information about crypt or verity device to log output.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -941,7 +945,7 @@ crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
int crypt_dump(struct crypt_device *cd); int crypt_dump(struct crypt_device *cd);
/** /**
* Get cipher used in device * Get cipher used in device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -951,7 +955,7 @@ int crypt_dump(struct crypt_device *cd);
const char *crypt_get_cipher(struct crypt_device *cd); const char *crypt_get_cipher(struct crypt_device *cd);
/** /**
* Get cipher mode used in device * Get cipher mode used in device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -961,7 +965,7 @@ const char *crypt_get_cipher(struct crypt_device *cd);
const char *crypt_get_cipher_mode(struct crypt_device *cd); const char *crypt_get_cipher_mode(struct crypt_device *cd);
/** /**
* Get device UUID * Get device UUID.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -971,7 +975,7 @@ const char *crypt_get_cipher_mode(struct crypt_device *cd);
const char *crypt_get_uuid(struct crypt_device *cd); const char *crypt_get_uuid(struct crypt_device *cd);
/** /**
* Get path to underlaying device * Get path to underlaying device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -981,7 +985,7 @@ const char *crypt_get_uuid(struct crypt_device *cd);
const char *crypt_get_device_name(struct crypt_device *cd); const char *crypt_get_device_name(struct crypt_device *cd);
/** /**
* Get device offset in sectors where real data starts on underlying device) * Get device offset in sectors where real data starts (on underlying device).
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -991,7 +995,7 @@ const char *crypt_get_device_name(struct crypt_device *cd);
uint64_t crypt_get_data_offset(struct crypt_device *cd); uint64_t crypt_get_data_offset(struct crypt_device *cd);
/** /**
* Get IV offset in sectors (skip) * Get IV offset in sectors (skip).
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -1001,7 +1005,7 @@ uint64_t crypt_get_data_offset(struct crypt_device *cd);
uint64_t crypt_get_iv_offset(struct crypt_device *cd); uint64_t crypt_get_iv_offset(struct crypt_device *cd);
/** /**
* Get size (in bytes) of volume key for crypt device * Get size (in bytes) of volume key for crypt device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* *
@@ -1011,7 +1015,7 @@ uint64_t crypt_get_iv_offset(struct crypt_device *cd);
int crypt_get_volume_key_size(struct crypt_device *cd); int crypt_get_volume_key_size(struct crypt_device *cd);
/** /**
* Get device parameters for VERITY device * Get device parameters for VERITY device.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param vp verity device info * @param vp verity device info
@@ -1034,7 +1038,7 @@ int crypt_get_verity_info(struct crypt_device *cd,
*/ */
/** /**
* Informational benchmark for ciphers * Informational benchmark for ciphers.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param cipher (e.g. "aes") * @param cipher (e.g. "aes")
@@ -1060,7 +1064,7 @@ int crypt_benchmark(struct crypt_device *cd,
double *decryption_mbs); double *decryption_mbs);
/** /**
* Informational benchmark for KDF * Informational benchmark for KDF.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param kdf Key derivation function (e.g. "pbkdf2") * @param kdf Key derivation function (e.g. "pbkdf2")
@@ -1101,7 +1105,7 @@ typedef enum {
} crypt_keyslot_info; } crypt_keyslot_info;
/** /**
* Get information about particular key slot * Get information about particular key slot.
* *
* *
* @param cd crypt device handle * @param cd crypt device handle
@@ -1124,7 +1128,7 @@ crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
int crypt_keyslot_max(const char *type); int crypt_keyslot_max(const char *type);
/** /**
* Get keyslot area pointers (relative to metadata device) * Get keyslot area pointers (relative to metadata device).
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param keyslot keyslot number * @param keyslot keyslot number
@@ -1140,7 +1144,7 @@ int crypt_keyslot_area(struct crypt_device *cd,
uint64_t *length); uint64_t *length);
/** /**
* Backup header and keyslots to file * Backup header and keyslots to file.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param requested_type @link crypt_type @endlink or @e NULL for all known * @param requested_type @link crypt_type @endlink or @e NULL for all known
@@ -1154,7 +1158,7 @@ int crypt_header_backup(struct crypt_device *cd,
const char *backup_file); const char *backup_file);
/** /**
* Restore header and keyslots from backup file * Restore header and keyslots from backup file.
* *
* *
* @param cd crypt device handle * @param cd crypt device handle
@@ -1169,14 +1173,13 @@ int crypt_header_restore(struct crypt_device *cd,
const char *backup_file); const char *backup_file);
/** /**
* Receives last reported error * Receive last reported error.
* *
* @param cd crypt device handle * @param cd crypt device handle
* @param buf buffef for message * @param buf buffef for message
* @param size size of buffer * @param size size of buffer
* *
* @note Note that this is old API function using global context. * @note All error messages are reported also through log callback.
* All error messages are reported also through log callback.
*/ */
void crypt_last_error(struct crypt_device *cd, char *buf, size_t size); void crypt_last_error(struct crypt_device *cd, char *buf, size_t size);
@@ -1186,8 +1189,7 @@ void crypt_last_error(struct crypt_device *cd, char *buf, size_t size);
* @param buf buffef for message * @param buf buffef for message
* @param size size of buffer * @param size size of buffer
* *
* @note Note that this is old API function using global context. * @note This function is DEPRECATED and will be removed in future versions.
* All error messages are reported also through log callback.
*/ */
void crypt_get_error(char *buf, size_t size); void crypt_get_error(char *buf, size_t size);