1854023f0SXin LI.\" $OpenBSD: timingsafe_bcmp.3,v 1.2 2014/06/21 20:22:15 tedu Exp $ 2854023f0SXin LI.\" 3854023f0SXin LI.\" Copyright (c) 2014 Google Inc. 4854023f0SXin LI.\" 5854023f0SXin LI.\" Permission to use, copy, modify, and distribute this software for any 6854023f0SXin LI.\" purpose with or without fee is hereby granted, provided that the above 7854023f0SXin LI.\" copyright notice and this permission notice appear in all copies. 8854023f0SXin LI.\" 9854023f0SXin LI.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10854023f0SXin LI.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11854023f0SXin LI.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12854023f0SXin LI.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13854023f0SXin LI.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14854023f0SXin LI.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15854023f0SXin LI.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16854023f0SXin LI.Dd August 15, 2016 17854023f0SXin LI.Dt TIMINGSAFE_BCMP 3 18854023f0SXin LI.Os 19854023f0SXin LI.Sh NAME 20854023f0SXin LI.Nm timingsafe_bcmp , 21854023f0SXin LI.Nm timingsafe_memcmp 22854023f0SXin LI.Nd timing-safe byte sequence comparisons 23854023f0SXin LI.Sh SYNOPSIS 24854023f0SXin LI.In string.h 25854023f0SXin LI.Ft int 26854023f0SXin LI.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" 27854023f0SXin LI.Ft int 28854023f0SXin LI.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" 29854023f0SXin LI.Sh DESCRIPTION 30854023f0SXin LIThe 31854023f0SXin LI.Fn timingsafe_bcmp 32854023f0SXin LIand 33854023f0SXin LI.Fn timingsafe_memcmp 34854023f0SXin LIfunctions lexicographically compare the first 35854023f0SXin LI.Fa len 36854023f0SXin LIbytes (each interpreted as an 37854023f0SXin LI.Vt unsigned char ) 38854023f0SXin LIpointed to by 39854023f0SXin LI.Fa b1 40854023f0SXin LIand 41854023f0SXin LI.Fa b2 . 42854023f0SXin LI.Pp 43854023f0SXin LIAdditionally, their running times are independent of the byte sequences compared, 44854023f0SXin LImaking them safe to use for comparing secret values such as cryptographic MACs. 45854023f0SXin LIIn contrast, 46854023f0SXin LI.Xr bcmp 3 47854023f0SXin LIand 48854023f0SXin LI.Xr memcmp 3 49854023f0SXin LImay short-circuit after finding the first differing byte. 50854023f0SXin LI.Sh RETURN VALUES 51854023f0SXin LIThe 52854023f0SXin LI.Fn timingsafe_bcmp 53854023f0SXin LIfunction returns 0 or not zero if the byte sequence pointed to by 54854023f0SXin LI.Fa b1 55854023f0SXin LIcompares equal to or not equal to (respectively) 56854023f0SXin LIthe byte sequence pointed to by 57854023f0SXin LI.Fa b2 . 58854023f0SXin LI.Pp 59854023f0SXin LIThe 60854023f0SXin LI.Fn timingsafe_memcmp 61854023f0SXin LIfunction returns a negative value, 0, or positive value if the byte sequence 62854023f0SXin LIpointed to by 63854023f0SXin LI.Fa b1 64854023f0SXin LIcompares less than, equal to, or greater than (respectively) 65854023f0SXin LIthe byte sequence pointed to by 66854023f0SXin LI.Fa b2 . 67854023f0SXin LI.Sh SEE ALSO 68854023f0SXin LI.Xr bcmp 3 , 69854023f0SXin LI.Xr memcmp 3 70854023f0SXin LI.Sh STANDARDS 71854023f0SXin LIThe 72854023f0SXin LI.Fn timingsafe_bcmp 73854023f0SXin LIand 74854023f0SXin LI.Fn timingsafe_memcmp 75854023f0SXin LIfunctions are 76854023f0SXin LI.Fx 77854023f0SXin LIextensions. 78854023f0SXin LI.Sh HISTORY 79854023f0SXin LIThe 80854023f0SXin LI.Fn timingsafe_bcmp 81854023f0SXin LIfunction first appeared in 82854023f0SXin LI.Ox 4.9 . 83854023f0SXin LI.Pp 84854023f0SXin LIThe 85854023f0SXin LI.Fn timingsafe_memcmp 86854023f0SXin LIfunction first appeared in 87854023f0SXin LI.Ox 5.6 . 88854023f0SXin LI.Pp 89854023f0SXin LIBoth functions first appeared in 90*6f55a4e2SDavid E. O'Brien.Fx 11.1 . 91