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 <[email protected]>
Cc: Mimi Zohar <[email protected]>
Cc: David Howells <[email protected]>
Cc: David Woodhouse <[email protected]>
Cc: [email protected]
---
certs/system_keyring.c | 30 ++++++++++++++++++++----------
1 file changed, 20 insertions(+), 10 deletions(-)
--- 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,
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...
--
~Randy