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

Clarify comments in API examples.

Browse Source
This commit is contained in:
Milan Broz
2019-08-30 16:24:56 +02:00
parent af0c5c3ccb
commit 4a7180a4f2
2 changed files with 28 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/examples/crypt_log_usage.c
View File

@@ -1,5 +1,5 @@
/*
* An example of using logging through libcryptsetup API
* libcryptsetup API log example
*
* Copyright (C) 2011-2019 Red Hat, Inc. All rights reserved.
*
@@ -25,10 +25,8 @@
#include <libcryptsetup.h>
/*
* This is an example of function that can be registered using crypt_set_log_callback API.
* This is an example of crypt_set_log_callback API callback.
*
* Its prototype is void (*log)(int level, const char *msg, void *usrptr) as defined
* in crypt_set_log_callback
*/
static void simple_syslog_wrapper(int level, const char *msg, void *usrptr)
{
@@ -71,7 +69,7 @@ int main(void)
return 2;
}
/* crypt_set_log_callback() - register a log function for crypt context */
/* crypt_set_log_callback() - register a log callback for crypt context */
crypt_set_log_callback(cd, &simple_syslog_wrapper, (void *)usrprefix);
/* send messages ithrough the crypt_log() interface */
@@ -83,7 +81,7 @@ int main(void)
/* release crypt context */
crypt_free(cd);
/* Initialize default (global) log function */
/* Initialize default (global) log callback */
crypt_set_log_callback(NULL, &simple_syslog_wrapper, NULL);
crypt_log(NULL, CRYPT_LOG_NORMAL, "This is normal log message");

67
docs/examples/crypt_luks_usage.c
View File

@@ -1,5 +1,5 @@
/*
* An example of using LUKS device through libcryptsetup API
* libcryptsetup API - using LUKS device example
*
* Copyright (C) 2011-2019 Red Hat, Inc. All rights reserved.
*
@@ -32,19 +32,15 @@ static int format_and_add_keyslots(const char *path)
int r;
/*
* crypt_init() call precedes most of operations of cryptsetup API. The call is used
* to initialize crypt device context stored in structure referenced by _cd_ in
* the example. Second parameter is used to pass underlaying device path.
* The crypt_init() call is used to initialize crypt_device context,
* The path parameter specifies a device path.
*
* Note:
* If path refers to a regular file it'll be attached to a first free loop device.
* crypt_init() operation fails in case there's no more loop device available.
* Also, loop device will have the AUTOCLEAR flag set, so the file loopback will
* be detached automatically.
* For path, you can use either link to a file or block device.
* The loopback device will be detached automatically.
*/
r = crypt_init(&cd, path);
if (r < 0 ) {
if (r < 0) {
printf("crypt_init() failed for %s.\n", path);
return r;
}
@@ -52,49 +48,37 @@ static int format_and_add_keyslots(const char *path)
printf("Context is attached to block device %s.\n", crypt_get_device_name(cd));
/*
* So far no data were written on your device. This will change with call of
* crypt_format() only if you specify CRYPT_LUKS2 as device type.
* So far, no data were written to the device.
*/
printf("Device %s will be formatted to LUKS device after 5 seconds.\n"
printf("Device %s will be formatted as a LUKS device after 5 seconds.\n"
"Press CTRL+C now if you want to cancel this operation.\n", path);
sleep(5);
/*
* NULLs for uuid and volume_key means that these attributes will be
* generated during crypt_format(). Volume key is generated with respect
* to key size parameter passed to function.
*
* crypt_format() checks device size (LUKS header must fit there).
* generated during crypt_format().
*/
r = crypt_format(cd, /* crypt context */
CRYPT_LUKS2, /* LUKS2 is new LUKS header; use CRYPT_LUKS1 for LUKS1 */
CRYPT_LUKS2, /* LUKS2 is a new LUKS format; use CRYPT_LUKS1 for LUKS1 */
"aes", /* used cipher */
"xts-plain64", /* used block mode and IV generator*/
"xts-plain64", /* used block mode and IV */
NULL, /* generate UUID */
NULL, /* generate volume key from RNG */
512 / 8, /* 512bit key - here AES-256 in XTS mode, size is in bytes */
NULL); /* default parameters */
if(r < 0) {
if (r < 0) {
printf("crypt_format() failed on device %s\n", crypt_get_device_name(cd));
crypt_free(cd);
return r;
}
/*
* The device now contains LUKS header, but there is
* no active keyslot with encrypted volume key yet.
*/
/*
* cryptt_kesylot_add_* call stores volume_key in encrypted form into keyslot.
* Without keyslot you can't manipulate with LUKS device after the context will be freed.
* The device now contains a LUKS header, but there is no active keyslot.
*
* To create a new keyslot you need to supply the existing one (to get the volume key from) or
* you need to supply the volume key.
* crypt_keyslot_add_* call stores the volume_key in the encrypted form into the keyslot.
*
* After format, we have volume key stored internally in context so add new keyslot
* using this internal volume key.
* After format, the volume key is stored internally.
*/
r = crypt_keyslot_add_by_volume_key(cd, /* crypt context */
CRYPT_ANY_SLOT, /* just use first free slot */
@@ -112,8 +96,8 @@ static int format_and_add_keyslots(const char *path)
printf("The first keyslot is initialized.\n");
/*
* Add another keyslot, now using the first keyslot.
* It will decrypt volume key from the first keyslot and creates new one with another passphrase.
* Add another keyslot, now authenticating with the first keyslot.
* It decrypts the volume key from the first keyslot and creates a new one with the specified passphrase.
*/
r = crypt_keyslot_add_by_passphrase(cd, /* crypt context */
CRYPT_ANY_SLOT, /* just use first free slot */
@@ -139,18 +123,15 @@ static int activate_and_check_status(const char *path, const char *device_name)
/*
* LUKS device activation example.
* It's sequence of sub-steps: device initialization, LUKS header load
* and the device activation itself.
*/
r = crypt_init(&cd, path);
if (r < 0 ) {
if (r < 0) {
printf("crypt_init() failed for %s.\n", path);
return r;
}
/*
* crypt_load() is used to load the LUKS header from block device
* into crypt_device context.
* crypt_load() is used to load existing LUKS header from a block device
*/
r = crypt_load(cd, /* crypt context */
CRYPT_LUKS, /* requested type - here LUKS of any type */
@@ -163,11 +144,11 @@ static int activate_and_check_status(const char *path, const char *device_name)
}
/*
* Device activation creates device-mapper devie mapping with name device_name.
* Device activation creates a device-mapper device with the specified name.
*/
r = crypt_activate_by_passphrase(cd, /* crypt context */
device_name, /* device name to activate */
CRYPT_ANY_SLOT,/* which slot use (ANY - try all) */
CRYPT_ANY_SLOT,/* the keyslot use (try all here) */
"foo", 3, /* passphrase */
CRYPT_ACTIVATE_READONLY); /* flags */
if (r < 0) {
@@ -182,7 +163,7 @@ static int activate_and_check_status(const char *path, const char *device_name)
printf("\tdevice UUID: %s\n", crypt_get_uuid(cd));
/*
* Get info about active device (query DM backend)
* Get info about the active device.
*/
r = crypt_get_active_device(cd, device_name, &cad);
if (r < 0) {
@@ -210,7 +191,7 @@ static int handle_active_device(const char *device_name)
int r;
/*
* crypt_init_by_name() initializes device context and loads LUKS header from backing device
* crypt_init_by_name() initializes context by an active device-mapper name
*/
r = crypt_init_by_name(&cd, device_name);
if (r < 0) {
@@ -227,7 +208,7 @@ static int handle_active_device(const char *device_name)
}
/*
* crypt_deactivate() is used to deactivate device
* crypt_deactivate() is used to deactivate a device
*/
r = crypt_deactivate(cd, device_name);
if (r < 0) {