1*84d9c625SLionel Sambuc.\" $NetBSD: explicit_memset.3,v 1.2 2013/08/28 15:46:23 riastradh Exp $ 2*84d9c625SLionel Sambuc.\" 3*84d9c625SLionel Sambuc.\" Copyright (c) 2013 The NetBSD Foundation, Inc. 4*84d9c625SLionel Sambuc.\" All rights reserved. 5*84d9c625SLionel Sambuc.\" 6*84d9c625SLionel Sambuc.\" This documentation is derived from text contributed to The NetBSD 7*84d9c625SLionel Sambuc.\" Foundation by Taylor R. Campbell. 8*84d9c625SLionel Sambuc.\" 9*84d9c625SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without 10*84d9c625SLionel Sambuc.\" modification, are permitted provided that the following conditions 11*84d9c625SLionel Sambuc.\" are met: 12*84d9c625SLionel Sambuc.\" 1. Redistributions of source code must retain the above copyright 13*84d9c625SLionel Sambuc.\" notice, this list of conditions and the following disclaimer. 14*84d9c625SLionel Sambuc.\" 2. Redistributions in binary form must reproduce the above copyright 15*84d9c625SLionel Sambuc.\" notice, this list of conditions and the following disclaimer in the 16*84d9c625SLionel Sambuc.\" documentation and/or other materials provided with the distribution. 17*84d9c625SLionel Sambuc.\" 18*84d9c625SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19*84d9c625SLionel Sambuc.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20*84d9c625SLionel Sambuc.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21*84d9c625SLionel Sambuc.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22*84d9c625SLionel Sambuc.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23*84d9c625SLionel Sambuc.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24*84d9c625SLionel Sambuc.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25*84d9c625SLionel Sambuc.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26*84d9c625SLionel Sambuc.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27*84d9c625SLionel Sambuc.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28*84d9c625SLionel Sambuc.\" POSSIBILITY OF SUCH DAMAGE. 29*84d9c625SLionel Sambuc.\" 30*84d9c625SLionel Sambuc.Dd August 28, 2013 31*84d9c625SLionel Sambuc.Dt EXPLICIT_MEMSET 3 32*84d9c625SLionel Sambuc.Os 33*84d9c625SLionel Sambuc.Sh NAME 34*84d9c625SLionel Sambuc.Nm explicit_memset 35*84d9c625SLionel Sambuc.Nd guarantee writing a byte to a byte string 36*84d9c625SLionel Sambuc.Sh LIBRARY 37*84d9c625SLionel Sambuc.Lb libc 38*84d9c625SLionel Sambuc.Sh SYNOPSIS 39*84d9c625SLionel Sambuc.In string.h 40*84d9c625SLionel Sambuc.Ft void * 41*84d9c625SLionel Sambuc.Fn explicit_memset "void *b" "int c" "size_t len" 42*84d9c625SLionel Sambuc.Sh DESCRIPTION 43*84d9c625SLionel SambucThe 44*84d9c625SLionel Sambuc.Fn explicit_memset 45*84d9c625SLionel Sambucfunction writes 46*84d9c625SLionel Sambuc.Fa len 47*84d9c625SLionel Sambucbytes of value 48*84d9c625SLionel Sambuc.Fa c 49*84d9c625SLionel Sambuc(converted to an unsigned char) to the string 50*84d9c625SLionel Sambuc.Fa b . 51*84d9c625SLionel SambucIt is guaranteed not to be optimized away by the compiler even if 52*84d9c625SLionel Sambuc.Fa b 53*84d9c625SLionel Sambucis no longer used and is about to be freed or go out of scope. 54*84d9c625SLionel Sambuc.Sh RETURN VALUES 55*84d9c625SLionel SambucThe 56*84d9c625SLionel Sambuc.Fn explicit_memset 57*84d9c625SLionel Sambucfunction returns the original value of 58*84d9c625SLionel Sambuc.Fa b . 59*84d9c625SLionel Sambuc.Sh EXAMPLES 60*84d9c625SLionel SambucCreate a buffer on the stack for a secret key, use it, and then zero it 61*84d9c625SLionel Sambucin memory before throwing it away. 62*84d9c625SLionel Sambuc.Bd -literal -offset indent 63*84d9c625SLionel Sambucvoid 64*84d9c625SLionel Sambucf(void) 65*84d9c625SLionel Sambuc{ 66*84d9c625SLionel Sambuc uint8_t key[32]; 67*84d9c625SLionel Sambuc 68*84d9c625SLionel Sambuc crypto_random(key, sizeof(key)); 69*84d9c625SLionel Sambuc do_crypto_stuff(key, sizeof(key)); 70*84d9c625SLionel Sambuc \&... 71*84d9c625SLionel Sambuc 72*84d9c625SLionel Sambuc explicit_memset(key, 0, sizeof(key)); 73*84d9c625SLionel Sambuc} 74*84d9c625SLionel Sambuc.Ed 75*84d9c625SLionel Sambuc.Sh SEE ALSO 76*84d9c625SLionel Sambuc.Xr consttime_memequal 3 , 77*84d9c625SLionel Sambuc.Xr memset 3 78*84d9c625SLionel Sambuc.Sh HISTORY 79*84d9c625SLionel SambucThe 80*84d9c625SLionel Sambuc.Fn explicit_memset 81*84d9c625SLionel Sambucfunction appeared in 82*84d9c625SLionel Sambuc.Nx 7.0 . 83