1.\" $OpenBSD: CMS_signed_add1_attr.3,v 1.3 2024/01/22 14:00:13 tb Exp $ 2.\" 3.\" Copyright (c) 2024 Job Snijders <job@openbsd.org> 4.\" Copyright (c) 2024 Theo Buehler <tb@openbsd.org> 5.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: January 22 2024 $ 20.Dt CMS_SIGNED_ADD1_ATTR 3 21.Os 22.Sh NAME 23.Nm CMS_signed_add1_attr , 24.Nm CMS_signed_add1_attr_by_NID , 25.Nm CMS_signed_add1_attr_by_OBJ , 26.Nm CMS_signed_add1_attr_by_txt , 27.Nm CMS_signed_delete_attr , 28.Nm CMS_signed_get0_data_by_OBJ , 29.Nm CMS_signed_get_attr , 30.Nm CMS_signed_get_attr_by_NID , 31.Nm CMS_signed_get_attr_by_OBJ , 32.Nm CMS_signed_get_attr_count , 33.Nm CMS_unsigned_add1_attr , 34.Nm CMS_unsigned_add1_attr_by_NID , 35.Nm CMS_unsigned_add1_attr_by_OBJ , 36.Nm CMS_unsigned_add1_attr_by_txt , 37.Nm CMS_unsigned_delete_attr , 38.Nm CMS_unsigned_get0_data_by_OBJ , 39.Nm CMS_unsigned_get_attr , 40.Nm CMS_unsigned_get_attr_by_NID , 41.Nm CMS_unsigned_get_attr_by_OBJ , 42.Nm CMS_unsigned_get_attr_count 43.Nd change signed and unsigned attributes of a CMS SignerInfo object 44.Sh SYNOPSIS 45.In openssl/cms.h 46.Ft int 47.Fo CMS_signed_add1_attr 48.Fa "CMS_SignerInfo *si" 49.Fa "X509_ATTRIBUTE *attr" 50.Fc 51.Ft int 52.Fo CMS_signed_add1_attr_by_NID 53.Fa "CMS_SignerInfo *si" 54.Fa "int nid" 55.Fa "int type" 56.Fa "const void *bytes" 57.Fa "int len" 58.Fc 59.Ft int 60.Fo CMS_signed_add1_attr_by_OBJ 61.Fa "CMS_SignerInfo *si" 62.Fa "const ASN1_OBJECT *obj" 63.Fa "int type" 64.Fa "const void *bytes" 65.Fa "int len" 66.Fc 67.Ft int 68.Fo CMS_signed_add1_attr_by_txt 69.Fa "CMS_SignerInfo *si" 70.Fa "const char *attrname" 71.Fa "int type" 72.Fa "const void *bytes" 73.Fa "int len" 74.Fc 75.Ft "X509_ATTRIBUTE *" 76.Fo CMS_signed_delete_attr 77.Fa "CMS_SignerInfo *si" 78.Fa "int loc" 79.Fc 80.Ft "void *" 81.Fo CMS_signed_get0_data_by_OBJ 82.Fa "CMS_SignerInfo *si" 83.Fa "const ASN1_OBJECT *oid" 84.Fa "int lastpos" 85.Fa "int type" 86.Fc 87.Ft "X509_ATTRIBUTE *" 88.Fo CMS_signed_get_attr 89.Fa "const CMS_SignerInfo *si" 90.Fa "int loc" 91.Fc 92.Ft int 93.Fo CMS_signed_get_attr_by_NID 94.Fa "const CMS_SignerInfo *si" 95.Fa "int nid" 96.Fa "int lastpos" 97.Fc 98.Ft int 99.Fo CMS_signed_get_attr_by_OBJ 100.Fa "const CMS_SignerInfo *si" 101.Fa "const ASN1_OBJECT *obj" 102.Fa "int lastpos" 103.Fc 104.Ft int 105.Fo CMS_signed_get_attr_count 106.Fa "const CMS_SignerInfo *si" 107.Fc 108.Ft int 109.Fo CMS_unsigned_add1_attr 110.Fa "CMS_SignerInfo *si" 111.Fa "X509_ATTRIBUTE *attr" 112.Fc 113.Ft int 114.Fo CMS_unsigned_add1_attr_by_NID 115.Fa "CMS_SignerInfo *si" 116.Fa "int nid" 117.Fa "int type" 118.Fa "const void *bytes" 119.Fa "int len" 120.Fc 121.Ft int 122.Fo CMS_unsigned_add1_attr_by_OBJ 123.Fa "CMS_SignerInfo *si" 124.Fa "const ASN1_OBJECT *obj" 125.Fa "int type" 126.Fa "const void *bytes" 127.Fa "int len" 128.Fc 129.Ft int 130.Fo CMS_unsigned_add1_attr_by_txt 131.Fa "CMS_SignerInfo *si" 132.Fa "const char *attrname" 133.Fa "int type" 134.Fa "const void *bytes" 135.Fa "int len" 136.Fc 137.Ft "X509_ATTRIBUTE *" 138.Fo CMS_unsigned_delete_attr 139.Fa "CMS_SignerInfo *si" 140.Fa "int loc" 141.Fc 142.Ft "void *" 143.Fo CMS_unsigned_get0_data_by_OBJ 144.Fa "CMS_SignerInfo *si" 145.Fa "ASN1_OBJECT *oid" 146.Fa "int lastpos" 147.Fa "int type" 148.Fc 149.Ft "X509_ATTRIBUTE *" 150.Fo CMS_unsigned_get_attr 151.Fa "const CMS_SignerInfo *si" 152.Fa "int loc" 153.Fc 154.Ft int 155.Fo CMS_unsigned_get_attr_by_NID 156.Fa "const CMS_SignerInfo *si" 157.Fa "int nid" 158.Fa "int lastpos" 159.Fc 160.Ft int 161.Fo CMS_unsigned_get_attr_by_OBJ 162.Fa "const CMS_SignerInfo *si" 163.Fa "const ASN1_OBJECT *obj" 164.Fa "int lastpos" 165.Fc 166.Ft int 167.Fo CMS_unsigned_get_attr_count 168.Fa "const CMS_SignerInfo *si" 169.Fc 170.Sh DESCRIPTION 171A 172.Em CMS_SignerInfo 173object has two optional sets of X.501 attributes: 174a set of signed attributes in the 175.Fa signedAttrs 176array and a set of unsigned attributes in the 177.Fa unsignedAttrs 178array. 179The functions in this manual are wrappers of the 180.Fn X509at_* 181functions. 182All arguments except 183.Fa si 184are passed to 185.Fn X509at_* . 186The 187.Fn CMS_signed_* 188and 189.Fn CMS_unsigned_* 190functions are similar, except 191.Fn CMS_signed_* 192calls 193.Fn X509at_* 194with the 195.Em CMS_SignerInfo 196object's set of signed attributes and 197.Fn CMS_unsigned_* 198calls 199.Fn X509at_* 200with the 201.Em CMS_SignerInfo 202object's set of unsigned attributes. 203For brevity only the 204.Fn CMS_signed_* 205functions are described below. 206.Pp 207.Fn CMS_signed_add1_attr 208appends a deep copy of 209.Fa attr 210to the 211.Fa signedAttrs 212array of 213.Fa si , 214allocating a new array if necessary. 215.Pp 216.Fn CMS_signed_add1_attr_by_NID , 217.Fn CMS_signed_add1_attr_by_OBJ , 218and 219.Fn CMS_signed_add1_attr_by_txt 220create a new X.501 Attribute object using 221.Xr X509at_add1_attr_by_NID 3 , 222.Xr X509at_add1_attr_by_OBJ 3 , 223and 224.Xr X509at_add1_attr_by_txt 3 , 225and append it to the 226.Fa signedAttrs 227array of 228.Fa si . 229.Pp 230.Fn CMS_signed_delete_attr 231deletes the element with the zero-based 232.Fa loc 233in 234.Fa signedAttrs 235of 236.Fa si . 237.Pp 238.Fn CMS_signed_get0_data_by_OBJ , 239.Fn CMS_signed_get_attr_by_NID , 240and 241.Fn CMS_signed_get_attr_by_OBJ 242search the array starting after the index 243.Fa lastpos . 244They fail if no matching object is found. 245.Fn CMS_signed_get0_data_by_OBJ 246also fails if the data is not of the requested 247.Fa type . 248.Pp 249Additionally, the 250.Fa lastpos 251argument of 252.Fn CMS_signed_get0_data_by_OBJ 253is interpreted in a special way. 254If 255.Fa lastpos 256is \-2 or smaller, the function also fails if the 257.Fa signedAttrs 258array of 259.Fa si , 260contains more than one matching object. 261If 262.Fa lastpos 263is \-3 or smaller, it also fails unless the matching object contains exactly 264one value. 265.Pp 266.Fn CMS_signed_get_attr 267returns the array element at the zero-based 268.Fa loc . 269It fails if the 270.Fa loc 271argument is negative or greater than or equal to the number of objects in the 272array. 273.Pp 274.Fn CMS_signed_get_attr_count 275returns the number of objects currently stored in the 276.Fa signedAttrs 277array of 278.Fa si . 279.Sh RETURN VALUES 280.Fn CMS_signed_add1_attr , 281.Fn CMS_signed_add1_attr_by_NID , 282.Fn CMS_signed_add1_attr_by_OBJ , 283.Fn CMS_signed_add1_attr_by_txt , 284.Fn CMS_unsigned_add1_attr , 285.Fn CMS_unsigned_add1_attr_by_NID , 286.Fn CMS_unsigned_add1_attr_by_OBJ , 287and 288.Fn CMS_unsigned_add1_attr_by_txt 289return 1 for success or 0 if an error occurs. 290.Pp 291.Fn CMS_signed_delete_attr 292returns the deleted element or 293.Dv NULL 294if the 295.Fa signedAttrs 296array is 297.Dv NULL , 298or if the requested 299.Fa loc 300argument is negative, or greater than or equal to the number of objects in it. 301.Pp 302.Fn CMS_unsigned_delete_attr 303returns the deleted element or 304.Dv NULL 305if the 306.Fa unsignedAttrs 307array is 308.Dv NULL , 309or if the requested 310.Fa loc 311argument is negative, or greater than or equal to the number of objects in it. 312.Pp 313.Fn CMS_signed_get0_data_by_OBJ 314and 315.Fn CMS_unsigned_get0_data_by_OBJ 316return an internal pointer to the data contained in the value of the first 317object that has an index greater than 318.Fa lastpos 319and a type matching 320.Fa type , 321or NULL on failure. 322.Pp 323.Fn CMS_signed_get_attr 324and 325.Fn CMS_unsigned_get_attr 326return an internal pointer or NULL on failure. 327.Pp 328.Fn CMS_signed_get_attr_by_NID , 329.Fn CMS_signed_get_attr_by_OBJ , 330.Fn CMS_unsigned_get_attr_by_NID , 331and 332.Fn CMS_unsigned_get_attr_by_OBJ 333return the index of the first object in the array that has an index greater than 334.Fa lastpos 335and a type matching 336.Fa nid 337or 338.Fa oid , 339respectively, or \-1 on failure. 340In addition, 341.Fn CMS_signed_get_attr_by_OBJ 342and 343.Fn CMS_unsigned_get_attr_by_OBJ 344return \-2 if 345.Xr OBJ_nid2obj 3 346fails on the requested 347.Fa nid . 348.Pp 349.Fn CMS_signed_get_attr_count 350and 351.Fn CMS_unsigned_get_attr_count 352return the number of array elements or \-1 on failure. 353.Sh SEE ALSO 354.Xr CMS_add1_signer 3 , 355.Xr CMS_ContentInfo_new 3 , 356.Xr CMS_get0_SignerInfos 3 , 357.Xr OBJ_nid2obj 3 , 358.Xr X509_ATTRIBUTE_create_by_OBJ 3 , 359.Xr X509_ATTRIBUTE_new 3 , 360.Xr X509at_add1_attr 3 361.Sh STANDARDS 362RFC 5652: Cryptographic Message Syntax (CMS) 363.Bl -dash -compact -offset indent 364.It 365section 5.3: SignerInfo Type 366.It 367section 11: Useful Attributes 368.El 369.Sh HISTORY 370These functions first appeared in OpenSSL 0.9.9 and have been available since 371.Ox 6.6 . 372