| Message ID | 20211025003813.5164-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | certs: system_keyring.c: clean up kernel-doc | expand |
Hi Randy, On Sun, 2021-10-24 at 17:38 -0700, Randy Dunlap wrote: > Fix some kernel-doc warnings in system_keyring.c: > > system_keyring.c:43: warning: expecting prototype for restrict_link_to_builtin_trusted(). Prototype was for restrict_link_by_builtin_trusted() instead > system_keyring.c:77: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst > * Allocate a struct key_restriction for the "builtin and secondary trust" > system_keyring.c:77: warning: missing initial short description on line: > * Allocate a struct key_restriction for the "builtin and secondary trust" > > Fix the warnings above and then see & fix these: > > system_keyring.c:43: warning: No description found for return value of 'restrict_link_by_builtin_trusted' > system_keyring.c:62: warning: No description found for return value of 'restrict_link_by_builtin_and_secondary_trusted' > system_keyring.c:190: warning: No description found for return value of 'verify_pkcs7_message_sig' > system_keyring.c:275: warning: No description found for return value of 'verify_pkcs7_signature' > > This still leaves non-exported two functions that do not have their > functions parameters documented: restrict_link_by_builtin_trusted() and > restrict_link_by_builtin_and_secondary_trusted(). > > Use '%' preceding constants in kernel-doc notation. > > Use "builtin" consistently instead of "built in" or "built-in". > > Don't use "/**" to begin a comment that is not in kernel-doc format. > > Document the use of VERIFY_USE_SECONDARY_KEYRING and > VERIFY_USE_PLATFORM_KEYRING. > Thanks, Randy. Even after these changes there are additional kernel doc warnings. Missing are the parameter definitions for restrict_link_by_builtin_trusted() and restrict_link_by_builtin_and_secondary_trusted(). The first three are exactly the same as for restrict_link_by_signature(). The fourth parm needs to be tweaked. Mimi
On 10/27/21 5:12 PM, Mimi Zohar wrote: > Hi Randy, > > On Sun, 2021-10-24 at 17:38 -0700, Randy Dunlap wrote: >> Fix some kernel-doc warnings in system_keyring.c: >> >> system_keyring.c:43: warning: expecting prototype for restrict_link_to_builtin_trusted(). Prototype was for restrict_link_by_builtin_trusted() instead >> system_keyring.c:77: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst >> * Allocate a struct key_restriction for the "builtin and secondary trust" >> system_keyring.c:77: warning: missing initial short description on line: >> * Allocate a struct key_restriction for the "builtin and secondary trust" >> >> Fix the warnings above and then see & fix these: >> >> system_keyring.c:43: warning: No description found for return value of 'restrict_link_by_builtin_trusted' >> system_keyring.c:62: warning: No description found for return value of 'restrict_link_by_builtin_and_secondary_trusted' >> system_keyring.c:190: warning: No description found for return value of 'verify_pkcs7_message_sig' >> system_keyring.c:275: warning: No description found for return value of 'verify_pkcs7_signature' >> >> This still leaves non-exported two functions that do not have their >> functions parameters documented: restrict_link_by_builtin_trusted() and >> restrict_link_by_builtin_and_secondary_trusted(). >> >> Use '%' preceding constants in kernel-doc notation. >> >> Use "builtin" consistently instead of "built in" or "built-in". >> >> Don't use "/**" to begin a comment that is not in kernel-doc format. >> >> Document the use of VERIFY_USE_SECONDARY_KEYRING and >> VERIFY_USE_PLATFORM_KEYRING. >> > > Thanks, Randy. Even after these changes there are additional kernel > doc warnings. Missing are the parameter definitions for > restrict_link_by_builtin_trusted() and > restrict_link_by_builtin_and_secondary_trusted(). The first three are > exactly the same as for restrict_link_by_signature(). The fourth parm > needs to be tweaked. Ah, thanks for the info. I'll update the patch...
--- linux-next-20211022.orig/certs/system_keyring.c +++ linux-next-20211022/certs/system_keyring.c @@ -31,10 +31,12 @@ extern __initconst const unsigned long s extern __initconst const unsigned long module_cert_size; /** - * restrict_link_to_builtin_trusted - Restrict keyring addition by built in CA + * restrict_link_by_builtin_trusted - Restrict keyring addition by builtin CA * * Restrict the addition of keys into a keyring based on the key-to-be-added - * being vouched for by a key in the built in system keyring. + * being vouched for by a key in the builtin system keyring. + * + * Return: %0 on success or a negative value on error */ int restrict_link_by_builtin_trusted(struct key *dest_keyring, const struct key_type *type, @@ -51,8 +53,10 @@ int restrict_link_by_builtin_trusted(str * addition by both builtin and secondary keyrings * * Restrict the addition of keys into a keyring based on the key-to-be-added - * being vouched for by a key in either the built-in or the secondary system + * being vouched for by a key in either the builtin or the secondary system * keyrings. + * + * Return: %0 on success or a negative value on error */ int restrict_link_by_builtin_and_secondary_trusted( struct key *dest_keyring, @@ -73,7 +77,7 @@ int restrict_link_by_builtin_and_seconda secondary_trusted_keys); } -/** +/* * Allocate a struct key_restriction for the "builtin and secondary trust" * keyring. Only for use in system_trusted_keyring_init(). */ @@ -170,14 +174,17 @@ late_initcall(load_system_certificate_li /** * verify_pkcs7_message_sig - Verify a PKCS#7-based signature on system data. - * @data: The data to be verified (NULL if expecting internal data). + * @data: The data to be verified (%NULL if expecting internal data). * @len: Size of @data. * @pkcs7: The PKCS#7 message that is the signature. - * @trusted_keys: Trusted keys to use (NULL for builtin trusted keys only, - * (void *)1UL for all trusted keys). + * @trusted_keys: Trusted keys to use (%NULL for builtin trusted keys only, + * %VERIFY_USE_SECONDARY_KEYRING for secondary trusted keys, + * %VERIFY_USE_PLATFORM_KEYRING for platform trusted keys). * @usage: The use to which the key is being put. * @view_content: Callback to gain access to content. * @ctx: Context for callback. + * + * Return: %0 on success or a negative value on error */ int verify_pkcs7_message_sig(const void *data, size_t len, struct pkcs7_message *pkcs7, @@ -254,15 +261,18 @@ error: /** * verify_pkcs7_signature - Verify a PKCS#7-based signature on system data. - * @data: The data to be verified (NULL if expecting internal data). + * @data: The data to be verified (%NULL if expecting internal data). * @len: Size of @data. * @raw_pkcs7: The PKCS#7 message that is the signature. * @pkcs7_len: The size of @raw_pkcs7. - * @trusted_keys: Trusted keys to use (NULL for builtin trusted keys only, - * (void *)1UL for all trusted keys). + * @trusted_keys: Trusted keys to use (%NULL for builtin trusted keys only, + * %VERIFY_USE_SECONDARY_KEYRING for secondary trusted keys, + * %VERIFY_USE_PLATFORM_KEYRING for platform trusted keys). * @usage: The use to which the key is being put. * @view_content: Callback to gain access to content. * @ctx: Context for callback. + * + * Return: %0 on success or a negative value on error */ int verify_pkcs7_signature(const void *data, size_t len, const void *raw_pkcs7, size_t pkcs7_len,
Fix some kernel-doc warnings in system_keyring.c: system_keyring.c:43: warning: expecting prototype for restrict_link_to_builtin_trusted(). Prototype was for restrict_link_by_builtin_trusted() instead system_keyring.c:77: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst * Allocate a struct key_restriction for the "builtin and secondary trust" system_keyring.c:77: warning: missing initial short description on line: * Allocate a struct key_restriction for the "builtin and secondary trust" Fix the warnings above and then see & fix these: system_keyring.c:43: warning: No description found for return value of 'restrict_link_by_builtin_trusted' system_keyring.c:62: warning: No description found for return value of 'restrict_link_by_builtin_and_secondary_trusted' system_keyring.c:190: warning: No description found for return value of 'verify_pkcs7_message_sig' system_keyring.c:275: warning: No description found for return value of 'verify_pkcs7_signature' This still leaves non-exported two functions that do not have their functions parameters documented: restrict_link_by_builtin_trusted() and restrict_link_by_builtin_and_secondary_trusted(). Use '%' preceding constants in kernel-doc notation. Use "builtin" consistently instead of "built in" or "built-in". Don't use "/**" to begin a comment that is not in kernel-doc format. Document the use of VERIFY_USE_SECONDARY_KEYRING and VERIFY_USE_PLATFORM_KEYRING. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Mimi Zohar <zohar@linux.ibm.com> Cc: David Howells <dhowells@redhat.com> Cc: David Woodhouse <dwmw2@infradead.org> Cc: keyrings@vger.kernel.org --- certs/system_keyring.c | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-)