Commit 22e78faf authored by Michael Halcrow's avatar Michael Halcrow Committed by Linus Torvalds
Browse files

eCryptfs: kerneldoc fixes for crypto.c and keystore.c 



Andrew Morton wrote:
From: mhalcrow@us.ibm.com <mhalcrow@halcrow.austin.ibm.com>
> > +/**
> > + * decrypt_passphrase_encrypted_session_key - Decrypt the session key
> > + * with the given auth_tok.
> >   *
> >   * Returns Zero on success; non-zero error otherwise.
> >   */
>
> That comment purports to be a kerneldoc-style comment.  But
>
> - kerneldoc doesn't support multiple lines on the introductory line
>   which identifies the name of the function (alas).  So you'll need to
>   overflow 80 cols here.
>
> - the function args weren't documented
>
> But the return value is!  People regularly forget to do that.  And
> they frequently forget to document the locking prerequisites and the
> permissible calling contexts (process/might_sleep/hardirq, etc)
>
> (please check all ecryptfs kerneldoc for this stuff sometime)

This patch cleans up some of the existing comments and makes a couple
of line break tweaks. There is more work to do to bring eCryptfs into
full kerneldoc-compliance.

Signed-off-by: default avatarMichael Halcrow <mhalcrow@us.ibm.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 6c6f57f3

fs/ecryptfs/crypto.c

+52 −17
Original line number Diff line number Diff line
@@ -722,6 +722,11 @@ out: 


/**

 * decrypt_scatterlist

 * @crypt_stat: Cryptographic context

 * @dest_sg: The destination scatterlist to decrypt into

 * @src_sg: The source scatterlist to decrypt from

 * @size: The number of bytes to decrypt

 * @iv: The initialization vector to use for the decryption

 *

 * Returns the number of bytes decrypted; negative value on error

 */
@@ -763,6 +768,13 @@ out: 


/**

 * ecryptfs_encrypt_page_offset

 * @crypt_stat: The cryptographic context

 * @dst_page: The page to encrypt into

 * @dst_offset: The offset in the page to encrypt into

 * @src_page: The page to encrypt from

 * @src_offset: The offset in the page to encrypt from

 * @size: The number of bytes to encrypt

 * @iv: The initialization vector to use for the encryption

 *

 * Returns the number of bytes encrypted

 */
@@ -785,6 +797,13 @@ ecryptfs_encrypt_page_offset(struct ecryptfs_crypt_stat *crypt_stat, 


/**

 * ecryptfs_decrypt_page_offset

 * @crypt_stat: The cryptographic context

 * @dst_page: The page to decrypt into

 * @dst_offset: The offset in the page to decrypt into

 * @src_page: The page to decrypt from

 * @src_offset: The offset in the page to decrypt from

 * @size: The number of bytes to decrypt

 * @iv: The initialization vector to use for the decryption

 *

 * Returns the number of bytes decrypted

 */
@@ -940,6 +959,8 @@ static void ecryptfs_generate_new_key(struct ecryptfs_crypt_stat *crypt_stat) 


/**

 * ecryptfs_copy_mount_wide_flags_to_inode_flags

 * @crypt_stat: The inode's cryptographic context

 * @mount_crypt_stat: The mount point's cryptographic context

 *

 * This function propagates the mount-wide flags to individual inode

 * flags.
@@ -980,7 +1001,8 @@ out: 


/**

 * ecryptfs_set_default_crypt_stat_vals

 * @crypt_stat

 * @crypt_stat: The inode's cryptographic context

 * @mount_crypt_stat: The mount point's cryptographic context

 *

 * Default values in the event that policy does not override them.

 */
@@ -1000,7 +1022,7 @@ static void ecryptfs_set_default_crypt_stat_vals( 


/**

 * ecryptfs_new_file_context

 * @ecryptfs_dentry

 * @ecryptfs_dentry: The eCryptfs dentry

 *

 * If the crypto context for the file has not yet been established,

 * this is where we do that.  Establishing a new crypto context
@@ -1017,7 +1039,6 @@ static void ecryptfs_set_default_crypt_stat_vals( 
 *

 * Returns zero on success; non-zero otherwise

 */

/* Associate an authentication token(s) with the file */

int ecryptfs_new_file_context(struct dentry *ecryptfs_dentry)

{

	struct ecryptfs_crypt_stat *crypt_stat =
@@ -1095,7 +1116,7 @@ static struct ecryptfs_flag_map_elem ecryptfs_flag_map[] = { 


/**

 * ecryptfs_process_flags

 * @crypt_stat

 * @crypt_stat: The cryptographic context

 * @page_virt: Source data to be parsed

 * @bytes_read: Updated with the number of bytes read

 *
@@ -1183,7 +1204,7 @@ ecryptfs_cipher_code_str_map[] = { 


/**

 * ecryptfs_code_for_cipher_string

 * @str: The string representing the cipher name

 * @crypt_stat: The cryptographic context

 *

 * Returns zero on no match, or the cipher code on match

 */
@@ -1241,9 +1262,9 @@ int ecryptfs_cipher_code_to_string(char *str, u16 cipher_code) 


/**

 * ecryptfs_read_header_region

 * @data

 * @dentry

 * @nd

 * @data: The virtual address to write header region data into

 * @dentry: The lower dentry

 * @mnt: The lower VFS mount

 *

 * Returns zero on success; non-zero otherwise

 */
@@ -1315,9 +1336,10 @@ struct kmem_cache *ecryptfs_header_cache_2; 


/**

 * ecryptfs_write_headers_virt

 * @page_virt

 * @crypt_stat

 * @ecryptfs_dentry

 * @page_virt: The virtual address to write the headers to

 * @size: Set to the number of bytes written by this function

 * @crypt_stat: The cryptographic context

 * @ecryptfs_dentry: The eCryptfs dentry

 *

 * Format version: 1

 *
@@ -1371,9 +1393,9 @@ static int ecryptfs_write_headers_virt(char *page_virt, size_t *size, 
	return rc;

}



static int ecryptfs_write_metadata_to_contents(struct ecryptfs_crypt_stat *crypt_stat,

					       struct file *lower_file,

					       char *page_virt)

static int

ecryptfs_write_metadata_to_contents(struct ecryptfs_crypt_stat *crypt_stat,

				    struct file *lower_file, char *page_virt)

{

	mm_segment_t oldfs;

	int current_header_page;
@@ -1415,7 +1437,8 @@ out: 
	return rc;

}



static int ecryptfs_write_metadata_to_xattr(struct dentry *ecryptfs_dentry,

static int

ecryptfs_write_metadata_to_xattr(struct dentry *ecryptfs_dentry,

				 struct ecryptfs_crypt_stat *crypt_stat,

				 char *page_virt, size_t size)

{
@@ -1428,6 +1451,7 @@ static int ecryptfs_write_metadata_to_xattr(struct dentry *ecryptfs_dentry, 


/**

 * ecryptfs_write_metadata

 * @ecryptfs_dentry: The eCryptfs dentry

 * @lower_file: The lower file struct, which was returned from dentry_open

 *

 * Write the file headers out.  This will likely involve a userspace
@@ -1525,6 +1549,7 @@ static int parse_header_metadata(struct ecryptfs_crypt_stat *crypt_stat, 


/**

 * set_default_header_data

 * @crypt_stat: The cryptographic context

 *

 * For version 0 file format; this function is only for backwards

 * compatibility for files created with the prior versions of
@@ -1538,6 +1563,10 @@ static void set_default_header_data(struct ecryptfs_crypt_stat *crypt_stat) 


/**

 * ecryptfs_read_headers_virt

 * @page_virt: The virtual address into which to read the headers

 * @crypt_stat: The cryptographic context

 * @ecryptfs_dentry: The eCryptfs dentry

 * @validate_header_size: Whether to validate the header size while reading

 *

 * Read/parse the header data. The header format is detailed in the

 * comment block for the ecryptfs_write_headers_virt() function.
@@ -1597,9 +1626,13 @@ out: 


/**

 * ecryptfs_read_xattr_region

 * @page_virt: The vitual address into which to read the xattr data

 * @ecryptfs_dentry: The eCryptfs dentry

 *

 * Attempts to read the crypto metadata from the extended attribute

 * region of the lower file.

 *

 * Returns zero on success; non-zero on error

 */

int ecryptfs_read_xattr_region(char *page_virt, struct dentry *ecryptfs_dentry)

{
@@ -1638,6 +1671,8 @@ out: 


/**

 * ecryptfs_read_metadata

 * @ecryptfs_dentry: The eCryptfs dentry

 * @lower_file: The lower file from which to read the metadata

 *

 * Common entry point for reading file metadata. From here, we could

 * retrieve the header information from the header region of the file,

fs/ecryptfs/keystore.c

+27 −21
Original line number Diff line number Diff line
@@ -71,7 +71,7 @@ int process_request_key_err(long err_code) 
 *        address; zero on error

 * @length_size: The number of bytes occupied by the encoded length

 *

 * Returns Zero on success

 * Returns zero on success; non-zero on error

 */

static int parse_packet_length(unsigned char *data, size_t *size,

			       size_t *length_size)
@@ -106,11 +106,11 @@ out: 


/**

 * write_packet_length

 * @dest: The byte array target into which to write the

 *       length. Must have at least 5 bytes allocated.

 * @dest: The byte array target into which to write the length. Must

 *        have at least 5 bytes allocated.

 * @size: The length to write.

 * @packet_size_length: The number of bytes used to encode the

 *                      packet length is written to this address.

 * @packet_size_length: The number of bytes used to encode the packet

 *                      length is written to this address.

 *

 * Returns zero on success; non-zero on error.

 */
@@ -397,10 +397,11 @@ out: 
}



/**

 * decrypt_pki_encrypted_session_key - Decrypt the session key with

 * the given auth_tok.

 * decrypt_pki_encrypted_session_key - Decrypt the session key with the given auth_tok.

 * @auth_tok: The key authentication token used to decrypt the session key

 * @crypt_stat: The cryptographic context

 *

 * Returns Zero on success; non-zero error otherwise.

 * Returns zero on success; non-zero error otherwise.

 */

static int

decrypt_pki_encrypted_session_key(struct ecryptfs_auth_tok *auth_tok,
@@ -484,18 +485,18 @@ struct kmem_cache *ecryptfs_auth_tok_list_item_cache; 


/**

 * parse_tag_1_packet

 * @crypt_stat: The cryptographic context to modify based on packet

 *              contents.

 * @crypt_stat: The cryptographic context to modify based on packet contents

 * @data: The raw bytes of the packet.

 * @auth_tok_list: eCryptfs parses packets into authentication tokens;

 *                 a new authentication token will be placed at the end

 *                 of this list for this packet.

 *                 a new authentication token will be placed at the

 *                 end of this list for this packet.

 * @new_auth_tok: Pointer to a pointer to memory that this function

 *                allocates; sets the memory address of the pointer to

 *                NULL on error. This object is added to the

 *                auth_tok_list.

 * @packet_size: This function writes the size of the parsed packet

 *               into this memory location; zero on error.

 * @max_packet_size: The maximum allowable packet size

 *

 * Returns zero on success; non-zero on error.

 */
@@ -996,10 +997,11 @@ ecryptfs_find_auth_tok_for_sig( 
}



/**

 * decrypt_passphrase_encrypted_session_key - Decrypt the session key

 * with the given auth_tok.

 * decrypt_passphrase_encrypted_session_key - Decrypt the session key with the given auth_tok.

 * @auth_tok: The passphrase authentication token to use to encrypt the FEK

 * @crypt_stat: The cryptographic context

 *

 * Returns Zero on success; non-zero error otherwise.

 * Returns zero on success; non-zero error otherwise

 */

static int

decrypt_passphrase_encrypted_session_key(struct ecryptfs_auth_tok *auth_tok,
@@ -1102,8 +1104,9 @@ int ecryptfs_get_auth_tok_sig(char **sig, struct ecryptfs_auth_tok *auth_tok) 


/**

 * ecryptfs_parse_packet_set

 * @dest: The header page in memory

 * @version: Version of file format, to guide parsing behavior

 * @crypt_stat: The cryptographic context

 * @src: Virtual address of region of memory containing the packets

 * @ecryptfs_dentry: The eCryptfs dentry associated with the packet set

 *

 * Get crypt_stat to have the file's session key if the requisite key

 * is available to decrypt the session key.
@@ -1354,7 +1357,10 @@ out: 
/**

 * write_tag_1_packet - Write an RFC2440-compatible tag 1 (public key) packet

 * @dest: Buffer into which to write the packet

 * @max: Maximum number of bytes that can be writtn

 * @remaining_bytes: Maximum number of bytes that can be writtn

 * @auth_tok: The authentication token used for generating the tag 1 packet

 * @crypt_stat: The cryptographic context

 * @key_rec: The key record struct for the tag 1 packet

 * @packet_size: This function will write the number of bytes that end

 *               up constituting the packet; set to zero on error

 *
@@ -1441,7 +1447,7 @@ out: 
/**

 * write_tag_11_packet

 * @dest: Target into which Tag 11 packet is to be written

 * @max: Maximum packet length

 * @remaining_bytes: Maximum packet length

 * @contents: Byte array of contents to copy in

 * @contents_length: Number of bytes in contents

 * @packet_length: Length of the Tag 11 packet written; zero on error
@@ -1501,7 +1507,7 @@ write_tag_11_packet(char *dest, size_t *remaining_bytes, char *contents, 
/**

 * write_tag_3_packet

 * @dest: Buffer into which to write the packet

 * @max: Maximum number of bytes that can be written

 * @remaining_bytes: Maximum number of bytes that can be written

 * @auth_tok: Authentication token

 * @crypt_stat: The cryptographic context

 * @key_rec: encrypted key
@@ -1707,7 +1713,7 @@ struct kmem_cache *ecryptfs_key_record_cache; 


/**

 * ecryptfs_generate_key_packet_set

 * @dest: Virtual address from which to write the key record set

 * @dest_base: Virtual address from which to write the key record set

 * @crypt_stat: The cryptographic context from which the

 *              authentication tokens will be retrieved

 * @ecryptfs_dentry: The dentry, used to retrieve the mount crypt stat

CRA Git | Maintained and supported by SUSTech CRA and CCSE