[RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Eugene Syromyatnikov]

---
 man2/keyctl.2 | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 144 insertions(+), 3 deletions(-)

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index e4b4bc9..570edf5 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -25,6 +25,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
+.mso www.tmac
 .TH KEYCTL 2 2017-03-13 Linux "Linux Key Management Calls"
 .SH NAME
 keyctl \- manipulate the kernel's key management facility
@@ -1413,7 +1414,8 @@ via the function
 .TP
 .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
 .\" commit ddbb41148724367394d0880c516bfaeed127b52e
-Compute a Diffie-Hellman shared secret or public key.
+Compute a Diffie-Hellman shared secret or public key,
+optionally applying key derivation function (KDF) to the result.
 .IP
 The
 .I arg2
@@ -1476,10 +1478,67 @@ system call was considered a good fit due to the DH algorithm's use
 for deriving shared keys;
 it also allows the type of the key to determine
 which DH implementation (software or hardware) is appropriate.
+.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8
 .IP
-The
+If the
 .I arg5
-argument is reserved and must be 0.
+argument is
+.BR NULL ,
+then the DH result itself is returned.
+Otherwise (since Linux 4.12), it is a pointer to a structure which specifies
+parameters of the KDF operation to be applied:
+.IP
+.in +4n
+.EX
++struct keyctl_kdf_params {
+    char *hashname;
+    char *otherinfo;
+    __u32 otherinfolen;
+    __u32 __spare[8];
+};
+.EE
+.in
+.IP
+The
+.B hashname
+field is a null-terminated string no longer than
+.B CRYPTO_MAX_ALG_NAME
+(128 bytes as of this writing) which specifies hash name
+(available into the kernel's crypto API; the list of the hashes available
+is rather tricky to observe; please refer to the
+.URL https://www.kernel.org/doc/html/latest/crypto/architecture.html "Kernel Crypto API Architecture"
+for the information regarding how hash names are constructed and
+to your kernel's source and configuration regarding what ciphers
+and templates with
+.B CRYPTO_ALG_TYPE_SHASH
+are available)
+to be applied to DH result in KDF operation.
+.IP
+The
+.B otherinfo
+field is an
+.I OtherInfo
+data as described in SP800-56A section 5.8.1.2 and is algorithm-specific.
+This data is concatenated with the result of DH operation and is provided as
+an input to the KDF operation.
+Its size is provided in the
+.B otherinfolen
+field and is limited by
+.B KEYCTL_KDF_MAX_OI_LEN
+constant that defined in
+.B security/keys/internal.h
+to a value of 64.
+.IP
+The
+.B __spare
+field is currently unused.
+.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
+It was ignored until Linux 4.13 (but still should be
+user-addressable since it is copied to the kernel),
+and should contain zeroes since Linux 4.13.
+.IP
+The KDF implementation complies with SP800-56A as well
+as with SP800-108 (the counter KDF).
 .SH RETURN VALUE
 For a successful call, the return value depends on the operation:
 .TP
@@ -1545,6 +1604,43 @@ and the requested link would result in a cycle.
 The key quota for the caller's user would be exceeded by creating a key or
 linking it to the keyring.
 .TP
+.B EFAULT
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and one of the following has failed:
+.RS
+.IP \(bu 3
+copying of
+.BR "struct keyctl_dh_params" ,
+pointed by
+.IR arg2 ,
+from the user space;
+.IP \(bu
+copying of
+.BR "struct keyctl_kdf_params" ,
+pointed by non-NULL
+.IR arg5 ,
+from the user space
+(in case kernel supports performing KDF operation on DH operation result);
+.IP \(bu
+copying of data pointed by
+.B hashname
+field of
+.B "struct keyctl_kdf_params"
+from the user space;
+.IP \(bu
+copying of data pointed by
+.B otherinfo
+field of
+.B struct keyctl_kdf_params
+from the user space if
+.B otherinfolen
+field was non-zero;
+.IP \(bu
+copying of the result to the user space.
+.RE
+.TP
 .B EINVAL
 .I operation
 was
@@ -1570,10 +1666,38 @@ exceeded the limit (32 bytes and 4096 bytes respectively).
 .B EINVAL
 .I operation
 was
+.BR KEYCTL_DH_COMPUTE ,
+.I arg5
+was non-NULL and kernel does not support applying KDF operation to the DH
+operation result.
+.TP
+.B EINVAL
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+And the digest size of the hashing algorithm supplied is zero.
+.TP
+.B EINVAL
+.I operation
+was
 .B KEYCTL_DH_COMPUTE
 and the buffer size provided is not enough to hold the result.
 Provide 0 as a buffer size in order to obtain the minimum buffer size.
 .TP
+.B EINVAL
+.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the
+.B __spare
+field of the
+.B struct keyctl_kdf_params
+provided in
+.I arg5
+field
+contains non-zero values.
+.TP
 .B EKEYEXPIRED
 An expired key was found or specified.
 .TP
@@ -1590,6 +1714,23 @@ was
 and the requested link would cause the maximum nesting depth
 for keyrings to be exceeded.
 .TP
+.B EMSGSIZE
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the buffer length exceeds
+.B KEYCTL_KDF_MAX_OUTPUT_LEN
+(which is 1024 currently)
+or the
+.B otherinfolen
+field of
+.B struct keyctl_kdf_parms
+passed in
+.I arg5
+exceeds
+.B KEYCTL_KDF_MAX_OI_LEN
+(which is 64 currently).
+.TP
 .BR ENFILE " (Linux kernels before 3.13)"
 .IR operation
 was
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Stephan Mueller]

Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene Syromyatnikov:

Hi Eugene,

> +field is a null-terminated string no longer than
> +.B CRYPTO_MAX_ALG_NAME
> +(128 bytes as of this writing) which specifies hash name

Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes. Also, 
it must be a valid cipher name as mentioned. Thus, I do not think the size is 
relevant here considering the requirement to use a proper name.

Otherwise, the KDF documentation looks good.

Ciao
Stephan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Eugene Syromyatnikov]

On Thu, Aug 31, 2017 at 6:07 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org> wrote:
> Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene Syromyatnikov:
>
> Hi Eugene,
>
>> +field is a null-terminated string no longer than
>> +.B CRYPTO_MAX_ALG_NAME
>> +(128 bytes as of this writing) which specifies hash name
>
> Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes. Also,
> it must be a valid cipher name as mentioned. Thus, I do not think the size is
> relevant here considering the requirement to use a proper name.

Right, it's probably more important for syscall decoding, but not for
the documentation. However, my understanding is that cipher template
can be specified (like "rfc4106(gcm(aes))"), and I'm not sure how deep
this nesting can be and whether it is possible to reach algorithm name
limit this way (by employing the usage of driver name instead of
common name, for example—as I understood, it is also possible). It
probably makes more sense to just mention this limit in the ERRORS
section instead.

> Otherwise, the KDF documentation looks good.
>
> Ciao
> Stephan



-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Stephan Mueller]

Am Donnerstag, 31. August 2017, 18:17:09 CEST schrieb Eugene Syromyatnikov:

Hi Eugene,

> On Thu, Aug 31, 2017 at 6:07 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org> 
wrote:
> > Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene
> > Syromyatnikov:
> > 
> > Hi Eugene,
> > 
> >> +field is a null-terminated string no longer than
> >> +.B CRYPTO_MAX_ALG_NAME
> >> +(128 bytes as of this writing) which specifies hash name
> > 
> > Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes.
> > Also, it must be a valid cipher name as mentioned. Thus, I do not think
> > the size is relevant here considering the requirement to use a proper
> > name.
> 
> Right, it's probably more important for syscall decoding, but not for
> the documentation. However, my understanding is that cipher template
> can be specified (like "rfc4106(gcm(aes))"), and I'm not sure how deep
> this nesting can be and whether it is possible to reach algorithm name
> limit this way (by employing the usage of driver name instead of
> common name, for example—as I understood, it is also possible). It
> probably makes more sense to just mention this limit in the ERRORS
> section instead.

CRYPTO_MAX_ALG_NAME is given a size that all allowed cipher names can be 
represented.

Somehow in the 4.12 release cycle, somebody found a very obscure yet valid 
name for a symmetric cipher that exceeded the 64 byte limit causing the bump 
to 128 bytes.

Though, that obscure name is no SHASH. All SHASH keyed digest cipher names are 
below 64 bytes.
> 
> > Otherwise, the KDF documentation looks good.
> > 
> > Ciao
> > Stephan



Ciao
Stephan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Eugene Syromyatnikov]

On Thu, Aug 31, 2017 at 4:21 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org> wrote:
> Am Donnerstag, 31. August 2017, 18:17:09 CEST schrieb Eugene Syromyatnikov:
>
> Hi Eugene,
>
>> On Thu, Aug 31, 2017 at 6:07 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org>
> wrote:
>> > Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene
>> > Syromyatnikov:
>> >
>> > Hi Eugene,
>> >
>> >> +field is a null-terminated string no longer than
>> >> +.B CRYPTO_MAX_ALG_NAME
>> >> +(128 bytes as of this writing) which specifies hash name
>> >
>> > Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes.
>> > Also, it must be a valid cipher name as mentioned. Thus, I do not think
>> > the size is relevant here considering the requirement to use a proper
>> > name.
>>
>> Right, it's probably more important for syscall decoding, but not for
>> the documentation. However, my understanding is that cipher template
>> can be specified (like "rfc4106(gcm(aes))"), and I'm not sure how deep
>> this nesting can be and whether it is possible to reach algorithm name
>> limit this way (by employing the usage of driver name instead of
>> common name, for example—as I understood, it is also possible). It
>> probably makes more sense to just mention this limit in the ERRORS
>> section instead.
>
> CRYPTO_MAX_ALG_NAME is given a size that all allowed cipher names can be
> represented.
>
> Somehow in the 4.12 release cycle, somebody found a very obscure yet valid
> name for a symmetric cipher that exceeded the 64 byte limit causing the bump
> to 128 bytes.
>
> Though, that obscure name is no SHASH. All SHASH keyed digest cipher names are
> below 64 bytes.

I see. Thanks for the clarification!


-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Michael Kerrisk (man-pages)]

On 08/31/2017 06:32 PM, Eugene Syromyatnikov wrote:
> On Thu, Aug 31, 2017 at 4:21 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org> wrote:
>> Am Donnerstag, 31. August 2017, 18:17:09 CEST schrieb Eugene Syromyatnikov:
>>
>> Hi Eugene,
>>
>>> On Thu, Aug 31, 2017 at 6:07 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org>
>> wrote:
>>>> Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene
>>>> Syromyatnikov:
>>>>
>>>> Hi Eugene,
>>>>
>>>>> +field is a null-terminated string no longer than
>>>>> +.B CRYPTO_MAX_ALG_NAME
>>>>> +(128 bytes as of this writing) which specifies hash name
>>>>
>>>> Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes.
>>>> Also, it must be a valid cipher name as mentioned. Thus, I do not think
>>>> the size is relevant here considering the requirement to use a proper
>>>> name.
>>>
>>> Right, it's probably more important for syscall decoding, but not for
>>> the documentation. However, my understanding is that cipher template
>>> can be specified (like "rfc4106(gcm(aes))"), and I'm not sure how deep
>>> this nesting can be and whether it is possible to reach algorithm name
>>> limit this way (by employing the usage of driver name instead of
>>> common name, for example—as I understood, it is also possible). It
>>> probably makes more sense to just mention this limit in the ERRORS
>>> section instead.
>>
>> CRYPTO_MAX_ALG_NAME is given a size that all allowed cipher names can be
>> represented.
>>
>> Somehow in the 4.12 release cycle, somebody found a very obscure yet valid
>> name for a symmetric cipher that exceeded the 64 byte limit causing the bump
>> to 128 bytes.
>>
>> Though, that obscure name is no SHASH. All SHASH keyed digest cipher names are
>> below 64 bytes.
> 
> I see. Thanks for the clarification!

Hi Eugene,

So, should I expect a new version of this patch?

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Eugene Syromyatnikov]

On Sun, Sep 3, 2017 at 2:43 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 08/31/2017 06:32 PM, Eugene Syromyatnikov wrote:
>> On Thu, Aug 31, 2017 at 4:21 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org> wrote:
>>> Am Donnerstag, 31. August 2017, 18:17:09 CEST schrieb Eugene Syromyatnikov:
>>>
>>> Hi Eugene,
>>>
>>>> On Thu, Aug 31, 2017 at 6:07 PM, Stephan Mueller <smueller-T9tCv8IpfcWELgA04lAiVw@public.gmane.org>
>>> wrote:
>>>>> Am Donnerstag, 31. August 2017, 17:58:36 CEST schrieb Eugene
>>>>> Syromyatnikov:
>>>>>
>>>>> Hi Eugene,
>>>>>
>>>>>> +field is a null-terminated string no longer than
>>>>>> +.B CRYPTO_MAX_ALG_NAME
>>>>>> +(128 bytes as of this writing) which specifies hash name
>>>>>
>>>>> Is it necessary to specify that size? Note, up to 4.11 it was 64 bytes.
>>>>> Also, it must be a valid cipher name as mentioned. Thus, I do not think
>>>>> the size is relevant here considering the requirement to use a proper
>>>>> name.
>>>>
>>>> Right, it's probably more important for syscall decoding, but not for
>>>> the documentation. However, my understanding is that cipher template
>>>> can be specified (like "rfc4106(gcm(aes))"), and I'm not sure how deep
>>>> this nesting can be and whether it is possible to reach algorithm name
>>>> limit this way (by employing the usage of driver name instead of
>>>> common name, for example—as I understood, it is also possible). It
>>>> probably makes more sense to just mention this limit in the ERRORS
>>>> section instead.
>>>
>>> CRYPTO_MAX_ALG_NAME is given a size that all allowed cipher names can be
>>> represented.
>>>
>>> Somehow in the 4.12 release cycle, somebody found a very obscure yet valid
>>> name for a symmetric cipher that exceeded the 64 byte limit causing the bump
>>> to 128 bytes.
>>>
>>> Though, that obscure name is no SHASH. All SHASH keyed digest cipher names are
>>> below 64 bytes.
>>
>> I see. Thanks for the clarification!
>
> Hi Eugene,
>
> So, should I expect a new version of this patch?
Well, this change is incorporated in v2—I decided just to mention that
in case syscall failed due to exceed in hashname size, syscall fails
with EINVAL (and no with ENOENT, for example, when no algorithm with
the provided name found):

+.B EINVAL
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the hash name provided in the
+.B hashname
+field of the
+.B struct keyctl_kdf_params
+pointed by
+.I arg5
+argument is too big (the limit is implementation-specific and varies between
+kernel versions, but it is deemed big enough for all valid algorithm names).

-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 4/5] keyctl.2: document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE

[Michael Kerrisk (man-pages)]

Hi Eugene,

On 3 September 2017 at 03:41, Eugene Syromyatnikov <evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On Sun, Sep 3, 2017 at 2:43 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

[...]

>> So, should I expect a new version of this patch?
> Well, this change is incorporated in v2—I decided just to mention that
> in case syscall failed due to exceed in hashname size, syscall fails
> with EINVAL (and no with ENOENT, for example, when no algorithm with
> the provided name found):

Ahhh -- yes, sorry. I confused the patch series.

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html