1.\" $OpenBSD: ASN1_BIT_STRING_set.3,v 1.2 2021/11/19 16:00:54 schwarze Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 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 $Mdocdate: November 19 2021 $ 18.Dt ASN1_BIT_STRING_SET 3 19.Os 20.Sh NAME 21.Nm ASN1_BIT_STRING_set , 22.Nm ASN1_BIT_STRING_set_bit , 23.Nm ASN1_BIT_STRING_get_bit , 24.Nm ASN1_BIT_STRING_check 25.Nd ASN.1 BIT STRING accessors 26.Sh SYNOPSIS 27.In openssl/asn1.h 28.Ft int 29.Fo ASN1_BIT_STRING_set 30.Fa "ASN1_BIT_STRING *bitstr" 31.Fa "unsigned char *data" 32.Fa "int len" 33.Fc 34.Ft int 35.Fo ASN1_BIT_STRING_set_bit 36.Fa "ASN1_BIT_STRING *bitstr" 37.Fa "int bitnumber" 38.Fa "int set" 39.Fc 40.Ft int 41.Fo ASN1_BIT_STRING_get_bit 42.Fa "ASN1_BIT_STRING *bitstr" 43.Fa "int bitnumber" 44.Fc 45.Ft int 46.Fo ASN1_BIT_STRING_check 47.Fa "ASN1_BIT_STRING *bitstr" 48.Fa "const unsigned char *goodbits" 49.Fa "int goodbits_len" 50.Fc 51.Sh DESCRIPTION 52.Fn ASN1_BIT_STRING_set 53sets the length attribute of 54.Fa bitstr 55to 56.Fa len 57and copies that number of bytes from 58.Fa data 59into 60.Fa bitstr , 61overwriting any previous data, by merely calling 62.Xr ASN1_STRING_set 3 . 63This function does no validation whatsoever. 64In particular, it neither checks that 65.Fa bitstr 66is actually of the type 67.Dv V_ASN1_BIT_STRING 68nor, even if it is, that the 69.Fa data 70and 71.Fa len 72arguments make sense for this particular bit string. 73.Pp 74If the 75.Fa set 76argument is non-zero, 77.Fn ASN1_BIT_STRING_set_bit 78sets the bit with the given 79.Fa bitnumber 80in the 81.Fa bitstr ; 82otherwise, it clears that bit. 83A 84.Fa bitnumber 85of 0 addresses the most significant bit in the first data byte of 86.Fa bitstr , 877 the least significant bit in the same byte, 888 the most significant bit in the second data byte, and so on. 89.Pp 90If setting a bit is requested beyond the last existing data byte, 91additional bytes are added to the 92.Fa bitstr 93as needed. 94After clearing a bit, any trailing NUL bytes are removed from the 95.Fa bitstr . 96.Pp 97.Fn ASN1_BIT_STRING_get_bit 98checks that the bit with the given 99.Fa bitnumber 100is set in 101.Fa bitstr . 102.Pp 103.Fn ASN1_BIT_STRING_check 104checks that all bits set in 105.Fa bitstr 106are also set in 107.Fa goodbits . 108Expressed symbolically, it evaluates: 109.Pp 110.D1 Po Fa bitstr No & Pf \(ti Fa goodbits Pc == 0 111.Pp 112The buffer 113.Fa goodbits 114is expected to contain 115.Fa goodbits_len 116bytes. 117.Sh RETURN VALUES 118.Fn ASN1_BIT_STRING_set 119returns 1 on success or 0 if memory allocation fails or if 120.Fa data 121is 122.Dv NULL 123and 124.Fa len 125is \-1 in the same call. 126.Pp 127.Fn ASN1_BIT_STRING_set_bit 128returns 1 on success or 0 if 129.Fa bitstr 130is 131.Dv NULL 132or if memory allocation fails. 133.Pp 134.Fn ASN1_BIT_STRING_get_bit 135returns 1 if the bit with the given 136.Fa bitnumber 137is set in the 138.Fa bitstr 139or 0 if 140.Fa bitstr 141is 142.Dv NULL , 143if 144.Fa bitnumber 145points beyond the last data byte in 146.Fa bitstr , 147or if the requested bit is not set. 148.Pp 149.Fn ASN1_BIT_STRING_check 150returns 0 151if at least one bit is set in 152.Fa bitstr 153that is not set in 154.Fa goodbits , 155or 1 otherwise. 156In particular, it returns 1 if 157.Fa bitstr 158is 159.Dv NULL 160or if no bit is set in 161.Fa bitstr . 162.Sh SEE ALSO 163.Xr ASN1_BIT_STRING_new 3 , 164.Xr ASN1_BIT_STRING_num_asc 3 , 165.Xr ASN1_STRING_set 3 , 166.Xr d2i_ASN1_BIT_STRING 3 167.Sh HISTORY 168.Fn ASN1_BIT_STRING_set 169first appeared in SSLeay 0.6.5. 170.Fn ASN1_BIT_STRING_set_bit 171and 172.Fn ASN1_BIT_STRING_get_bit 173first appeared in SSLeay 0.9.0. 174These functions have been available since 175.Ox 2.4 . 176.Pp 177.Fn ASN1_BIT_STRING_check 178first appeared in OpenSSL 1.0.0 and has have been available since 179.Ox 4.9 . 180