1.\" $OpenBSD: timingsafe_bcmp.3,v 1.2 2014/06/21 20:22:15 tedu Exp $ 2.\" 3.\" Copyright (c) 2014 Google Inc. 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.Dd August 15, 2016 17.Dt TIMINGSAFE_BCMP 3 18.Os 19.Sh NAME 20.Nm timingsafe_bcmp , 21.Nm timingsafe_memcmp 22.Nd timing-safe byte sequence comparisons 23.Sh SYNOPSIS 24.In string.h 25.Ft int 26.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" 27.Ft int 28.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" 29.Sh DESCRIPTION 30The 31.Fn timingsafe_bcmp 32and 33.Fn timingsafe_memcmp 34functions lexicographically compare the first 35.Fa len 36bytes (each interpreted as an 37.Vt unsigned char ) 38pointed to by 39.Fa b1 40and 41.Fa b2 . 42.Pp 43Additionally, their running times are independent of the byte sequences compared, 44making them safe to use for comparing secret values such as cryptographic MACs. 45In contrast, 46.Xr bcmp 3 47and 48.Xr memcmp 3 49may short-circuit after finding the first differing byte. 50.Sh RETURN VALUES 51The 52.Fn timingsafe_bcmp 53function returns 0 or not zero if the byte sequence pointed to by 54.Fa b1 55compares equal to or not equal to (respectively) 56the byte sequence pointed to by 57.Fa b2 . 58.Pp 59The 60.Fn timingsafe_memcmp 61function returns a negative value, 0, or positive value if the byte sequence 62pointed to by 63.Fa b1 64compares less than, equal to, or greater than (respectively) 65the byte sequence pointed to by 66.Fa b2 . 67.Sh SEE ALSO 68.Xr bcmp 3 , 69.Xr memcmp 3 70.Sh STANDARDS 71The 72.Fn timingsafe_bcmp 73and 74.Fn timingsafe_memcmp 75functions are 76.Fx 77extensions. 78.Sh HISTORY 79The 80.Fn timingsafe_bcmp 81function first appeared in 82.Ox 4.9 . 83.Pp 84The 85.Fn timingsafe_memcmp 86function first appeared in 87.Ox 5.6 . 88.Pp 89Both functions first appeared in 90.Fx 11.1 . 91