1.\" $OpenBSD: CMS_signed_add1_attr.3,v 1.5 2024/09/02 07:54:21 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: September 2 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 start_after" 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 start_after" 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 start_after" 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 start_after" 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 start_after" 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 start_after" 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 180.Fn CMS_signed_* 181and 182.Fn CMS_unsigned_* 183functions are similar, except 184.Fn CMS_signed_* 185modifies the 186.Vt CMS_SignerInfo 187object's set of signed attributes and 188.Fn CMS_unsigned_* 189modifies the 190.Vt CMS_SignerInfo 191object's set of unsigned attributes. 192For brevity only the 193.Fn CMS_signed_* 194functions are described below. 195.Pp 196.Fn CMS_signed_add1_attr 197appends a deep copy of 198.Fa attr 199to the 200.Fa signedAttrs 201array of 202.Fa si , 203allocating a new array if necessary. 204.Pp 205.Fn CMS_signed_add1_attr_by_NID , 206.Fn CMS_signed_add1_attr_by_OBJ , 207and 208.Fn CMS_signed_add1_attr_by_txt 209create a new X.501 Attribute object using 210.Xr X509_ATTRIBUTE_create_by_NID 3 , 211.Xr X509_ATTRIBUTE_create_by_OBJ 3 , 212or 213.Xr X509_ATTRIBUTE_create_by_txt 3 , 214respectively, 215and append it to the 216.Fa signedAttrs 217array of 218.Fa si . 219.Pp 220.Fn CMS_signed_delete_attr 221deletes the element with the zero-based 222.Fa loc 223in 224.Fa signedAttrs 225of 226.Fa si . 227.Pp 228.Fn CMS_signed_get0_data_by_OBJ , 229.Fn CMS_signed_get_attr_by_NID , 230and 231.Fn CMS_signed_get_attr_by_OBJ 232search the array starting after the index 233.Fa start_after . 234They fail if no matching object is found. 235.Fn CMS_signed_get0_data_by_OBJ 236also fails if the data is not of the requested 237.Fa type . 238.Pp 239Additionally, the 240.Fa start_after 241argument of 242.Fn CMS_signed_get0_data_by_OBJ 243is interpreted in a special way. 244If 245.Fa start_after 246is \-2 or smaller, the function also fails if the 247.Fa signedAttrs 248array of 249.Fa si , 250contains more than one matching object. 251If 252.Fa start_after 253is \-3 or smaller, it also fails unless the matching object contains exactly 254one value. 255.Pp 256.Fn CMS_signed_get_attr 257returns the array element at the zero-based 258.Fa loc . 259It fails if the 260.Fa loc 261argument is negative or greater than or equal to the number of objects in the 262array. 263.Pp 264.Fn CMS_signed_get_attr_count 265returns the number of objects currently stored in the 266.Fa signedAttrs 267array of 268.Fa si . 269.Sh RETURN VALUES 270.Fn CMS_signed_add1_attr , 271.Fn CMS_signed_add1_attr_by_NID , 272.Fn CMS_signed_add1_attr_by_OBJ , 273.Fn CMS_signed_add1_attr_by_txt , 274.Fn CMS_unsigned_add1_attr , 275.Fn CMS_unsigned_add1_attr_by_NID , 276.Fn CMS_unsigned_add1_attr_by_OBJ , 277and 278.Fn CMS_unsigned_add1_attr_by_txt 279return 1 for success or 0 if an error occurs. 280.Pp 281.Fn CMS_signed_delete_attr 282returns the deleted element or 283.Dv NULL 284if the 285.Fa signedAttrs 286array is 287.Dv NULL , 288or if the requested 289.Fa loc 290argument is negative, or greater than or equal to the number of objects in it. 291.Pp 292.Fn CMS_unsigned_delete_attr 293returns the deleted element or 294.Dv NULL 295if the 296.Fa unsignedAttrs 297array is 298.Dv NULL , 299or if the requested 300.Fa loc 301argument is negative, or greater than or equal to the number of objects in it. 302.Pp 303.Fn CMS_signed_get0_data_by_OBJ 304and 305.Fn CMS_unsigned_get0_data_by_OBJ 306return an internal pointer to the data contained in the value of the first 307object that has an index greater than 308.Fa start_after 309and a type matching 310.Fa type , 311or NULL on failure. 312.Pp 313.Fn CMS_signed_get_attr 314and 315.Fn CMS_unsigned_get_attr 316return an internal pointer or NULL on failure. 317.Pp 318.Fn CMS_signed_get_attr_by_NID , 319.Fn CMS_signed_get_attr_by_OBJ , 320.Fn CMS_unsigned_get_attr_by_NID , 321and 322.Fn CMS_unsigned_get_attr_by_OBJ 323return the index of the first object in the array that has an index greater than 324.Fa start_after 325and a type matching 326.Fa nid 327or 328.Fa oid , 329respectively, or \-1 on failure. 330In addition, 331.Fn CMS_signed_get_attr_by_OBJ 332and 333.Fn CMS_unsigned_get_attr_by_OBJ 334return \-2 if 335.Xr OBJ_nid2obj 3 336fails on the requested 337.Fa nid . 338.Pp 339.Fn CMS_signed_get_attr_count 340and 341.Fn CMS_unsigned_get_attr_count 342return the number of array elements or \-1 on failure. 343.Sh SEE ALSO 344.Xr CMS_add1_signer 3 , 345.Xr CMS_ContentInfo_new 3 , 346.Xr CMS_get0_SignerInfos 3 , 347.Xr OBJ_nid2obj 3 , 348.Xr X509_ATTRIBUTE_create_by_OBJ 3 , 349.Xr X509_ATTRIBUTE_new 3 350.Sh STANDARDS 351RFC 5652: Cryptographic Message Syntax (CMS) 352.Bl -dash -compact -offset indent 353.It 354section 5.3: SignerInfo Type 355.It 356section 11: Useful Attributes 357.El 358.Sh HISTORY 359These functions first appeared in OpenSSL 0.9.9 and have been available since 360.Ox 6.6 . 361