Addition to memcmp(3)

Addition to memcmp(3)

[Michael Haardt]

Hello,

memcmp(3) does not document the return value for length 0 and the
CPU time depending on the number of compared bytes.  While both
is obvious, it should still be documented.

Michael

--- memcmp.3.orig	2014-11-17 08:53:53.848805576 +0100
+++ memcmp.3	2014-11-17 08:58:39.699005856 +0100
@@ -27,6 +27,7 @@
 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
 .\"     386BSD man pages
 .\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith-+5Oa3zvhR2o3uPMLIKxrzw@public.gmane.org)
+.\" Modified Mon Nov 17 07:45:13 2014 by Michael Haardt (michael-8s1n8bisGiQ@public.gmane.org)
 .TH MEMCMP 3  2014-03-14 "" "Linux Programmer's Manual"
 .SH NAME
 memcmp \- compare memory areas
@@ -42,6 +43,11 @@
 function compares the first \fIn\fP bytes (each interpreted as
 .IR "unsigned char" )
 of the memory areas \fIs1\fP and \fIs2\fP.
+.PP
+Do not use
+.BR memcmp ()
+to compare security critical data, such as cryptographic secrets,
+because the required CPU time depends on the amount of equal bytes.
 .SH RETURN VALUE
 The
 .BR memcmp ()
@@ -57,6 +63,8 @@
 .I s1
 and
 .IR s2 .
+.PP
+If \fIn\fP is zero, the return value is zero.
 .SH ATTRIBUTES
 .SS Multithreading (see pthreads(7))
 The
--
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: Addition to memcmp(3)

[Michael Kerrisk (man-pages)]

Hello Michael,

On Mon, Nov 17, 2014 at 9:07 AM, Michael Haardt <michael-8s1n8bisGiQ@public.gmane.org> wrote:
> Hello,
>
> memcmp(3) does not document the return value for length 0 and the
> CPU time depending on the number of compared bytes.  While both
> is obvious, it should still be documented.

Thanks for this patch. I applied, but see notes below.

Note 1: this patch covers two unrelated points, so I manually split it.

> --- memcmp.3.orig       2014-11-17 08:53:53.848805576 +0100
> +++ memcmp.3    2014-11-17 08:58:39.699005856 +0100
> @@ -27,6 +27,7 @@
>  .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
>  .\"     386BSD man pages
>  .\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith-+5Oa3zvhR2o3uPMLIKxrzw@public.gmane.org)
> +.\" Modified Mon Nov 17 07:45:13 2014 by Michael Haardt (michael-8s1n8bisGiQ@public.gmane.org)
>  .TH MEMCMP 3  2014-03-14 "" "Linux Programmer's Manual"
>  .SH NAME
>  memcmp \- compare memory areas
> @@ -42,6 +43,11 @@
>  function compares the first \fIn\fP bytes (each interpreted as
>  .IR "unsigned char" )
>  of the memory areas \fIs1\fP and \fIs2\fP.
> +.PP
> +Do not use
> +.BR memcmp ()
> +to compare security critical data, such as cryptographic secrets,
> +because the required CPU time depends on the amount of equal bytes.

I placed this piece in a new NOTES section.

Some text here about what one should do instead of using memcmp()
might be helpful. Do you have any suggestions?

>  .SH RETURN VALUE
>  The
>  .BR memcmp ()
> @@ -57,6 +63,8 @@
>  .I s1
>  and
>  .IR s2 .
> +.PP
> +If \fIn\fP is zero, the return value is zero.

Good call to add this piece Thanks.

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: Addition to memcmp(3)

[Michael Haardt]

> I placed this piece in a new NOTES section.
>
> Some text here about what one should do instead of using memcmp()
> might be helpful. Do you have any suggestions?

Obviously a comparison with constant CPU usage is asked for, which is
rather easy to implement given that secrets are usually only compared
for being equal.  AFAIK neither POSIX nor C99 offers a function for that.
I don't know if glibc does.  NetBSD does (consttime_memequal), but that
does not help portable code, so I have no good suggestion really.

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

Re: Addition to memcmp(3)

[Michael Kerrisk (man-pages)]

On 12/31/2014 12:41 AM, Michael Haardt wrote:
>> I placed this piece in a new NOTES section.
>>
>> Some text here about what one should do instead of using memcmp()
>> might be helpful. Do you have any suggestions?
> 
> Obviously a comparison with constant CPU usage is asked for, which is
> rather easy to implement given that secrets are usually only compared
> for being equal.  AFAIK neither POSIX nor C99 offers a function for that.
> I don't know if glibc does.  NetBSD does (consttime_memequal), but that
> does not help portable code, so I have no good suggestion really.

Thanks. I'll add this text to the page:

+Instead, a function that performs comparisons in constant time is required.
+Some operating systems provide such a function (e.g., NetBSD's
+.BR const_memequal ()),
+but no such function is specified in POSIX.
+On Linux, it may be necessary to implement such a function oneself.

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