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.\" 17.Dd April 11, 2019 18.Dt TIMINGSAFE_BCMP 3 19.Os 20.Sh NAME 21.Nm timingsafe_bcmp , 22.Nm timingsafe_memcmp 23.Nd timing-safe byte sequence comparisons 24.Sh LIBRARY 25.Lb libc 26.Sh SYNOPSIS 27.In string.h 28.Ft int 29.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" 30.Ft int 31.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" 32.Sh DESCRIPTION 33The 34.Fn timingsafe_bcmp 35and 36.Fn timingsafe_memcmp 37functions lexicographically compare the first 38.Fa len 39bytes (each interpreted as an 40.Vt unsigned char ) 41pointed to by 42.Fa b1 43and 44.Fa b2 . 45.Pp 46Additionally, their running times are independent of the byte sequences compared, 47making them safe to use for comparing secret values such as cryptographic MACs. 48In contrast, 49.Xr bcmp 3 50and 51.Xr memcmp 3 52may short-circuit after finding the first differing byte. 53.Sh RETURN VALUES 54The 55.Fn timingsafe_bcmp 56function returns 0 or not zero if the byte sequence pointed to by 57.Fa b1 58compares equal to or not equal to (respectively) 59the byte sequence pointed to by 60.Fa b2 . 61.Pp 62The 63.Fn timingsafe_memcmp 64function returns a negative value, 0, or positive value if the byte sequence 65pointed to by 66.Fa b1 67compares less than, equal to, or greater than (respectively) 68the byte sequence pointed to by 69.Fa b2 . 70.Sh SEE ALSO 71.Xr bcmp 3 , 72.Xr memcmp 3 73.Sh STANDARDS 74The 75.Fn timingsafe_bcmp 76and 77.Fn timingsafe_memcmp 78functions are 79.Ox 80extensions. 81.Sh HISTORY 82The 83.Fn timingsafe_bcmp 84function first appeared in 85.Ox 4.9 86and 87.Dx 5.6 . 88.Pp 89The 90.Fn timingsafe_memcmp 91function first appeared in 92.Ox 5.5 93and 94.Dx 5.6 . 95