From 22e78fafbdf84883f70eb4944cf658fc23c4a1f4 Mon Sep 17 00:00:00 2001 From: Michael Halcrow Date: Tue, 16 Oct 2007 01:28:02 -0700 Subject: [PATCH] eCryptfs: kerneldoc fixes for crypto.c and keystore.c Andrew Morton wrote: From: mhalcrow@us.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: Michael Halcrow Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- fs/ecryptfs/crypto.c | 69 +++++++++++++++++++++++++++++++++++++------------- fs/ecryptfs/keystore.c | 48 ++++++++++++++++++++--------------- 2 files changed, 79 insertions(+), 38 deletions(-) diff --git a/fs/ecryptfs/crypto.c b/fs/ecryptfs/crypto.c index 6051dbf..7aa2f48 100644 --- a/fs/ecryptfs/crypto.c +++ b/fs/ecryptfs/crypto.c @@ -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,9 +1437,10 @@ out: return rc; } -static int ecryptfs_write_metadata_to_xattr(struct dentry *ecryptfs_dentry, - struct ecryptfs_crypt_stat *crypt_stat, - char *page_virt, size_t size) +static int +ecryptfs_write_metadata_to_xattr(struct dentry *ecryptfs_dentry, + struct ecryptfs_crypt_stat *crypt_stat, + char *page_virt, size_t size) { int rc; @@ -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, diff --git a/fs/ecryptfs/keystore.c b/fs/ecryptfs/keystore.c index 778bdf9..e9cda7a 100644 --- a/fs/ecryptfs/keystore.c +++ b/fs/ecryptfs/keystore.c @@ -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 -- 1.8.2.3