1641ead6dSzrj.\" $OpenBSD: timingsafe_bcmp.3,v 1.2 2014/06/21 20:22:15 tedu Exp $ 2641ead6dSzrj.\" 3641ead6dSzrj.\" Copyright (c) 2014 Google Inc. 4641ead6dSzrj.\" 5641ead6dSzrj.\" Permission to use, copy, modify, and distribute this software for any 6641ead6dSzrj.\" purpose with or without fee is hereby granted, provided that the above 7641ead6dSzrj.\" copyright notice and this permission notice appear in all copies. 8641ead6dSzrj.\" 9641ead6dSzrj.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10641ead6dSzrj.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11641ead6dSzrj.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12641ead6dSzrj.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13641ead6dSzrj.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14641ead6dSzrj.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15641ead6dSzrj.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16641ead6dSzrj.\" 17641ead6dSzrj.Dd April 11, 2019 18641ead6dSzrj.Dt TIMINGSAFE_BCMP 3 19641ead6dSzrj.Os 20641ead6dSzrj.Sh NAME 21641ead6dSzrj.Nm timingsafe_bcmp , 22641ead6dSzrj.Nm timingsafe_memcmp 23641ead6dSzrj.Nd timing-safe byte sequence comparisons 24afe603d8SSascha Wildner.Sh LIBRARY 25afe603d8SSascha Wildner.Lb libc 26641ead6dSzrj.Sh SYNOPSIS 27641ead6dSzrj.In string.h 28641ead6dSzrj.Ft int 29641ead6dSzrj.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" 30641ead6dSzrj.Ft int 31641ead6dSzrj.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" 32641ead6dSzrj.Sh DESCRIPTION 33641ead6dSzrjThe 34641ead6dSzrj.Fn timingsafe_bcmp 35641ead6dSzrjand 36641ead6dSzrj.Fn timingsafe_memcmp 37641ead6dSzrjfunctions lexicographically compare the first 38641ead6dSzrj.Fa len 39641ead6dSzrjbytes (each interpreted as an 40641ead6dSzrj.Vt unsigned char ) 41641ead6dSzrjpointed to by 42641ead6dSzrj.Fa b1 43641ead6dSzrjand 44641ead6dSzrj.Fa b2 . 45641ead6dSzrj.Pp 46641ead6dSzrjAdditionally, their running times are independent of the byte sequences compared, 47641ead6dSzrjmaking them safe to use for comparing secret values such as cryptographic MACs. 48641ead6dSzrjIn contrast, 49641ead6dSzrj.Xr bcmp 3 50641ead6dSzrjand 51641ead6dSzrj.Xr memcmp 3 52641ead6dSzrjmay short-circuit after finding the first differing byte. 53641ead6dSzrj.Sh RETURN VALUES 54641ead6dSzrjThe 55641ead6dSzrj.Fn timingsafe_bcmp 56641ead6dSzrjfunction returns 0 or not zero if the byte sequence pointed to by 57641ead6dSzrj.Fa b1 58641ead6dSzrjcompares equal to or not equal to (respectively) 59641ead6dSzrjthe byte sequence pointed to by 60641ead6dSzrj.Fa b2 . 61641ead6dSzrj.Pp 62641ead6dSzrjThe 63641ead6dSzrj.Fn timingsafe_memcmp 64641ead6dSzrjfunction returns a negative value, 0, or positive value if the byte sequence 65641ead6dSzrjpointed to by 66641ead6dSzrj.Fa b1 67641ead6dSzrjcompares less than, equal to, or greater than (respectively) 68641ead6dSzrjthe byte sequence pointed to by 69641ead6dSzrj.Fa b2 . 70641ead6dSzrj.Sh SEE ALSO 71641ead6dSzrj.Xr bcmp 3 , 72641ead6dSzrj.Xr memcmp 3 73641ead6dSzrj.Sh STANDARDS 74641ead6dSzrjThe 75641ead6dSzrj.Fn timingsafe_bcmp 76641ead6dSzrjand 77641ead6dSzrj.Fn timingsafe_memcmp 78641ead6dSzrjfunctions are 79641ead6dSzrj.Ox 80641ead6dSzrjextensions. 81641ead6dSzrj.Sh HISTORY 82641ead6dSzrjThe 83641ead6dSzrj.Fn timingsafe_bcmp 84641ead6dSzrjfunction first appeared in 85641ead6dSzrj.Ox 4.9 86641ead6dSzrjand 87641ead6dSzrj.Dx 5.6 . 88641ead6dSzrj.Pp 89641ead6dSzrjThe 90641ead6dSzrj.Fn timingsafe_memcmp 91641ead6dSzrjfunction first appeared in 92*d79aa16aSSascha Wildner.Ox 5.5 93*d79aa16aSSascha Wildnerand 94641ead6dSzrj.Dx 5.6 . 95