1.\" $OpenBSD: X509_REQ_add1_attr.3,v 1.2 2021/10/26 18:50:38 jmc 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: October 26 2021 $ 18.Dt X509_REQ_ADD1_ATTR 3 19.Os 20.Sh NAME 21.Nm X509_REQ_add1_attr , 22.Nm X509_REQ_add1_attr_by_OBJ , 23.Nm X509_REQ_add1_attr_by_NID , 24.Nm X509_REQ_add1_attr_by_txt , 25.Nm X509_REQ_delete_attr , 26.Nm X509_REQ_get_attr , 27.Nm X509_REQ_get_attr_count , 28.Nm X509_REQ_get_attr_by_OBJ , 29.Nm X509_REQ_get_attr_by_NID 30.Nd X.501 Attributes of PKCS#10 certification requests 31.Sh SYNOPSIS 32.In openssl/x509.h 33.Ft int 34.Fo X509_REQ_add1_attr 35.Fa "X509_REQ *req" 36.Fa "X509_ATTRIBUTE *attr" 37.Fc 38.Ft int 39.Fo X509_REQ_add1_attr_by_OBJ 40.Fa "X509_REQ *req" 41.Fa "const ASN1_OBJECT *obj" 42.Fa "int type" 43.Fa "const unsigned char *data" 44.Fa "int len" 45.Fc 46.Ft int 47.Fo X509_REQ_add1_attr_by_NID 48.Fa "X509_REQ *req" 49.Fa "int nid" 50.Fa "int type" 51.Fa "const unsigned char *data" 52.Fa "int len" 53.Fc 54.Ft int 55.Fo X509_REQ_add1_attr_by_txt 56.Fa "X509_REQ *req" 57.Fa "const char *name" 58.Fa "int type" 59.Fa "const unsigned char *data" 60.Fa "int len" 61.Fc 62.Ft X509_ATTRIBUTE * 63.Fo X509_REQ_delete_attr 64.Fa "X509_REQ *req" 65.Fa "int index" 66.Fc 67.Ft X509_ATTRIBUTE * 68.Fo X509_REQ_get_attr 69.Fa "const X509_REQ *req" 70.Fa "int index" 71.Fc 72.Ft int 73.Fo X509_REQ_get_attr_count 74.Fa "const X509_REQ *req" 75.Fc 76.Ft int 77.Fo X509_REQ_get_attr_by_OBJ 78.Fa "const X509_REQ *req" 79.Fa "const ASN1_OBJECT *obj" 80.Fa "int start_after" 81.Fc 82.Ft int 83.Fo X509_REQ_get_attr_by_NID 84.Fa "const X509_REQ *req" 85.Fa "int nid" 86.Fa "int start_after" 87.Fc 88.Sh DESCRIPTION 89These functions support associating an array of X.501 Attributes 90with a PKCS#10 certification request. 91.Pp 92.Fn X509_REQ_add1_attr 93appends a deep copy of the 94.Fa attr 95using 96.Xr X509at_add1_attr 3 . 97.Pp 98.Fn X509_REQ_add1_attr_by_OBJ , 99.Fn X509_REQ_add1_attr_by_NID , 100and 101.Fn X509_REQ_add1_attr_by_txt 102create a new X.501 Attribute object using 103.Xr X509_ATTRIBUTE_create_by_OBJ 3 , 104.Xr X509_ATTRIBUTE_create_by_NID 3 , 105or 106.Xr X509_ATTRIBUTE_create_by_txt 3 , 107respectively, and append it using 108.Xr X509at_add1_attr 3 . 109.Pp 110.Fn X509_REQ_delete_attr 111deletes the attribute with the zero-based 112.Fa index 113using 114.Xr X509at_delete_attr 3 . 115.Pp 116.Fn X509_REQ_get_attr 117returns the attribute with the zero-based 118.Fa index 119using 120.Xr X509at_get_attr 3 . 121.Pp 122.Fn X509_REQ_get_attr_count 123returns the number of attributes currently associated with 124.Fa req 125using 126.Xr X509at_get_attr_count 3 . 127.Pp 128.Fn X509_REQ_get_attr_by_OBJ 129and 130.Fn X509_REQ_get_attr_by_NID 131search for an attribute of the type 132.Fa obj 133or 134.Fa nid 135using 136.Xr X509at_get_attr_by_OBJ 3 137or 138.Xr X509at_get_attr_by_NID 3 , 139respectively. 140.Sh RETURN VALUES 141.Fn X509_REQ_add1_attr , 142.Fn X509_REQ_add1_attr_by_OBJ , 143.Fn X509_REQ_add1_attr_by_NID , 144and 145.Fn X509_REQ_add1_attr_by_txt 146return 1 for success or 0 for failure. 147.Pp 148.Fn X509_REQ_delete_attr 149and 150.Fn X509_REQ_get_attr 151return the deleted or requested attribute or 152.Dv NULL 153if the requested index is negative or greater than or equal to 154the current number of attributes associated with 155.Fa req . 156.Pp 157.Fn X509_REQ_get_attr_count 158returns the current number of attributes. 159.Pp 160.Fn X509_REQ_get_attr_by_OBJ 161and 162.Fn X509_REQ_get_attr_by_NID 163return the index of the first attribute that has an index greater than 164.Fa start_after 165and a type matching 166.Fa obj 167or 168.Fa nid , 169respectively, or \-1 on failure. 170In addition, 171.Fn X509_REQ_get_attr_by_NID 172returns \-2 if 173.Xr OBJ_nid2obj 3 174fails on the requested 175.Fa nid . 176.Sh SEE ALSO 177.Xr OBJ_nid2obj 3 , 178.Xr X509_ATTRIBUTE_create_by_OBJ 3 , 179.Xr X509_ATTRIBUTE_new 3 , 180.Xr X509_REQ_new 3 , 181.Xr X509at_add1_attr 3 , 182.Xr X509at_get_attr 3 183.Sh HISTORY 184These functions first appeared in OpenSSL 0.9.5 185and have been available since 186.Ox 2.7 . 187