linux-kernel - Re: [PATCH 4/7] eCryptfs: Comments for some structs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Date:	Thu, 26 Jul 2007 04:29:31 +0530
From:	"Satyam Sharma" <satyam.sharma@...il.com>
To:	"Michael Halcrow" <mhalcrow@...ibm.com>
Cc:	akpm@...ux-foundation.org, linux-kernel@...r.kernel.org,
	toml@...ibm.com
Subject: Re: [PATCH 4/7] eCryptfs: Comments for some structs

Trivial nits ...

On 7/26/07, Michael Halcrow <mhalcrow@...ibm.com> wrote:
> [...]
> +/**
> + * ecryptfs_global_auth_tok structs refer to authentication token keys
> + * in the user keyring that apply to newly created files. A list of
> + * these objects hangs off of the mount_crypt_stat struct for any
> + * given eCryptfs mount. This struct maintains a reference to both the
> + * key contents and the key itself so that the key can be put on
> + * unmount.
> + */

/** is used to annotate kernel-doc style comments, which this
one isn't -- IIRC, kernel-doc doesn't like this (?)

>  struct ecryptfs_global_auth_tok {
>  #define ECRYPTFS_AUTH_TOK_INVALID 0x00000001
>         u32 flags;
> -       struct list_head mount_crypt_stat_list;
> -       struct key *global_auth_tok_key;
> -       struct ecryptfs_auth_tok *global_auth_tok;
> -       unsigned char sig[ECRYPTFS_SIG_SIZE_HEX + 1];

> +       struct list_head mount_crypt_stat_list; /* Default auth_tok list for
> +                                                * the mount_crypt_stat */
> +       struct key *global_auth_tok_key; /* The key from the user's keyring for
> +                                         * the sig */

Tsk. You could consider using kernel-doc style itself to comment the
structure -- this stuff goes up there and doesn't look icky.

> +       struct ecryptfs_auth_tok *global_auth_tok; /* The key contents */
> +       unsigned char sig[ECRYPTFS_SIG_SIZE_HEX + 1]; /* The key identifier */
>  };
>
> +/**
> + * Typically, eCryptfs will use the same ciphers repeatedly throughout
> + * the course of its operations. In order to avoid unnecessarily
> + * destroying and initializing the same cipher repeatedly, eCryptfs
> + * keeps a list of crypto API contexts around to use when needed.
> + */

Again, you could consider using kernel-doc style comments here.

>  struct ecryptfs_key_tfm {
>         struct crypto_blkcipher *key_tfm;
>         size_t key_size;
>         struct mutex key_tfm_mutex;
> -       struct list_head key_tfm_list;
> +       struct list_head key_tfm_list; /* The module's tfm list */
>         unsigned char cipher_name[ECRYPTFS_MAX_CIPHER_NAME_SIZE + 1];
>  };


Satyam
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/