Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/string/timingsafe_bcmp.3
- This file was added.
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" $OpenBSD: timingsafe_bcmp.3,v 1.2 2014/06/21 20:22:15 tedu Exp $ | |||||
.\" | |||||
.\" Copyright (c) 2014 Google Inc. | |||||
.\" | |||||
.\" Permission to use, copy, modify, and distribute this software for any | |||||
.\" purpose with or without fee is hereby granted, provided that the above | |||||
.\" copyright notice and this permission notice appear in all copies. | |||||
.\" | |||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |||||
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |||||
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |||||
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |||||
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |||||
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.Dd $Mdocdate: June 13 2014 $ | |||||
.Dt TIMINGSAFE_BCMP 3 | |||||
bjk: Is this a target merge date? ;) | |||||
Not Done Inline ActionsYes. delphij: Yes. | |||||
.Os | |||||
.Sh NAME | |||||
.Nm timingsafe_bcmp , | |||||
.Nm timingsafe_memcmp | |||||
.Nd timing-safe byte sequence comparisons | |||||
.Sh SYNOPSIS | |||||
.In string.h | |||||
.Ft int | |||||
.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" | |||||
.Ft int | |||||
.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Fn timingsafe_bcmp | |||||
and | |||||
.Fn timingsafe_memcmp | |||||
functions lexicographically compare the first | |||||
.Fa len | |||||
bytes (each interpreted as an | |||||
.Vt unsigned char ) | |||||
pointed to by | |||||
.Fa b1 | |||||
and | |||||
.Fa b2 . | |||||
.Pp | |||||
Additionally, their running times are independent of the byte sequences compared, | |||||
making them safe to use for comparing secret values such as cryptographic MACs. | |||||
In contrast, | |||||
.Xr bcmp 3 | |||||
and | |||||
.Xr memcmp 3 | |||||
may short-circuit after finding the first differing byte. | |||||
.Sh RETURN VALUES | |||||
The | |||||
.Fn timingsafe_bcmp | |||||
function returns 0 or not zero if the byte sequence pointed to by | |||||
.Fa b1 | |||||
compares equal to or not equal to (respectively) | |||||
the byte sequence pointed to by | |||||
.Fa b2 . | |||||
.Pp | |||||
The | |||||
.Fn timingsafe_memcmp | |||||
function returns a negative value, 0, or positive value if the byte sequence | |||||
pointed to by | |||||
.Fa b1 | |||||
compares less than, equal to, or greater than (respectively) | |||||
the byte sequence pointed to by | |||||
Not Done Inline ActionsI slightly worry that future advances in compiler optimizers will make these semantics hard to support, but have no real objection. bjk: I slightly worry that future advances in compiler optimizers will make these semantics hard to… | |||||
Not Done Inline ActionsThat's possible, but I think we can always hint compiler not to optimize a select subset of library functions when this become a problem? delphij: That's possible, but I think we can always hint compiler not to optimize a select subset of… | |||||
.Fa b2 . | |||||
.Sh SEE ALSO | |||||
.Xr bcmp 3 , | |||||
.Xr memcmp 3 | |||||
.Sh STANDARDS | |||||
The | |||||
.Fn timingsafe_bcmp | |||||
and | |||||
.Fn timingsafe_memcmp | |||||
functions are | |||||
.Fx | |||||
extensions. | |||||
.Sh HISTORY | |||||
The | |||||
.Fn timingsafe_bcmp | |||||
function first appeared in | |||||
.Ox 4.9 . | |||||
.Pp | |||||
The | |||||
.Fn timingsafe_memcmp | |||||
function first appeared in | |||||
.Ox 5.6 . | |||||
Both functions first appeared in | |||||
.Fx 12.0 . |
Is this a target merge date? ;)