From: Job Snijders Subject: libcrypto/man: add CMS_signed_add1_attr.3 To: tech@openbsd.org Date: Fri, 19 Jan 2024 15:41:04 +0000 Dear all, Here is a starting point to document the CMS_{signed,unsigned}_* adders, getters, and counter functions. OK? Feedback? Kind regards, Job Index: CMS_signed_add1_attr.3 =================================================================== RCS file: CMS_signed_add1_attr.3 diff -N CMS_signed_add1_attr.3 --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ CMS_signed_add1_attr.3 19 Jan 2024 15:30:15 -0000 @@ -0,0 +1,367 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2024 Job Snijders +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt CMS_SIGNED_ADD1_ATTR 3 +.Os +.Sh NAME +.Nm CMS_signed_add1_attr , +.Nm CMS_signed_add1_attr_by_NID , +.Nm CMS_signed_add1_attr_by_OBJ , +.Nm CMS_signed_add1_attr_by_txt , +.Nm CMS_signed_delete_attr , +.Nm CMS_signed_get0_data_by_OBJ , +.Nm CMS_signed_get_attr , +.Nm CMS_signed_get_attr_by_NID , +.Nm CMS_signed_get_attr_by_OBJ , +.Nm CMS_signed_get_attr_count , +.Nm CMS_unsigned_add1_attr , +.Nm CMS_unsigned_add1_attr_by_NID , +.Nm CMS_unsigned_add1_attr_by_OBJ , +.Nm CMS_unsigned_add1_attr_by_txt , +.Nm CMS_unsigned_delete_attr , +.Nm CMS_unsigned_get0_data_by_OBJ , +.Nm CMS_unsigned_get_attr , +.Nm CMS_unsigned_get_attr_by_NID , +.Nm CMS_unsigned_get_attr_by_OBJ , +.Nm CMS_unsigned_get_attr_count +.Nd CMS signed and unsigned attribute functions +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_signed_add1_attr +.Fa "CMS_SignerInfo *si" +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_NID +.Fa "CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_txt +.Fa "CMS_SignerInfo *si" +.Fa "const char *attrname" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft "X509_ATTRIBUTE *" +.Fo CMS_signed_delete_attr +.Fa "CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft "void *" +.Fo CMS_signed_get0_data_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *oid" +.Fa "int lastpos" +.Fa "int type" +.Fc +.Ft "X509_ATTRIBUTE *" +.Fo CMS_signed_get_attr +.Fa "const CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft int +.Fo CMS_signed_get_attr_by_NID +.Fa "const CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo CMS_signed_get_attr_by_OBJ +.Fa "const CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo CMS_signed_get_attr_count +.Fa "const CMS_SignerInfo *si" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr +.Fa "CMS_SignerInfo *si" +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_NID +.Fa "CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_txt +.Fa "CMS_SignerInfo *si" +.Fa "const char *attrname" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft "X509_ATTRIBUTE *" +.Fo CMS_unsigned_delete_attr +.Fa "CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft "void *" +.Fo CMS_unsigned_get0_data_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "ASN1_OBJECT *oid" +.Fa "int lastpos" +.Fa "int type" +.Fc +.Ft "X509_ATTRIBUTE *" +.Fo CMS_unsigned_get_attr +.Fa "const CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_by_NID +.Fa "const CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_by_OBJ +.Fa "const CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_count +.Fa "const CMS_SignerInfo *si" +.Fc +.Sh DESCRIPTION +.Fn CMS_signed_add1_attr +and +.Fn CMS_unsigned_add1_attr +append a deep copy of +.Fa attr +to +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively, allocating a new array if necessary. +.Pp +.Fn CMS_signed_add1_attr_by_NID , +.Fn CMS_signed_add1_attr_by_OBJ , +.Fn CMS_signed_add1_attr_by_txt , +.Fn CMS_unsigned_add1_attr_by_NID , +.Fn CMS_unsigned_add1_attr_by_OBJ , +and +.Fn CMS_unsigned_add1_attr_by_txt +create a new X.501 Attribute object using +.Xr X509at_add1_attr_by_NID 3 , +.Xr X509at_add1_attr_by_OBJ 3 , +and +.Xr X509at_add1_attr_by_txt 3 , +and append it to +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively. +.Pp +.Fn CMS_signed_delete_attr +and +.Fn CMS_unsigned_delete_attr +delete the element with the zero-based +.Fa loc +in +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively. +.Pp +.Fn CMS_signed_get0_data_by_OBJ , +.Fn CMS_signed_get_attr_by_NID , +.Fn CMS_signed_get_attr_by_OBJ , +.Fn CMS_unsigned_get0_data_by_OBJ , +.Fn CMS_unsigned_get_attr_by_NID , +and +.Fn CMS_unsigned_get_attr_by_OBJ +search the array starting after the index +.Fa lastpos . +They fail if no matching object is found. +.Fn CMS_signed_get0_data_by_OBJ +and +.Fn CMS_unsigned_get0_data_by_OBJ +also fail if the data is not of the requested +.Fa type . +.Pp +Additionally, the +.Fa lastpos +argument of +.Fn CMS_signed_get0_data_by_OBJ +and +.Fn CMS_unsigned_get0_data_by_OBJ +is interpreted in a special way. +If +.Fa lastpos +is -2 or smaller, the function also fails if +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively, contains more than one matching object. +If +.Fa lastpos +is -3 or smaller, it also fails unless the matching object contains exactly +one value. +.Pp +.Fn CMS_signed_get_attr +and +.Fn CMS_unsigned_get_attr +returns the array element at the zero-based +.Fa loc . +They fail if the +.Fa loc +is negative or great than or equal to the number of objects in the array. +.Pp +.Fn CMS_signed_get_attr_count +and +.Fn CMS_unsigned_get_attr_count +return the number of objects currently stored in +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively. +.Pp +.Sh RETURN VALUES +.Fn CMS_signed_add1_attr , +.Fn CMS_signed_add1_attr_by_NID , +.Fn CMS_signed_add1_attr_by_OBJ , +.Fn CMS_signed_add1_attr_by_txt , +.Fn CMS_unsigned_add1_attr , +.Fn CMS_unsigned_add1_attr_by_NID , +.Fn CMS_unsigned_add1_attr_by_OBJ and +.Fn CMS_unsigned_add1_attr_by_txt +return 1 for success or 0 if an error occurs. +.Pp +.Fn CMS_signed_delete_attr +and +.Fn CMS_unsigned_delete_attr +returns the deleted element or NULL if +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively, are NULL, or if the requested +.Fa loc +is negative or greater than or equal to the number of objects in +.Fa signedAttrs +and +.Fa unsignedAttrs +of +.Fa si , +respectively. +.Pp +.Fn CMS_signed_get0_data_by_OBJ +and +.Fn CMS_unsigned_get0_data_by_OBJ +return an internal pointer to the data contained in the value of the first +object that has an index greater than +.Fa lastpos +and a type matching +.Fa type , +or NULL on failure. +.Pp +.Fn CMS_signed_get_attr +and +.Fn CMS_unsigned_get_attr +return an internal pointer or NULL on failure. +.Pp +.Fn CMS_signed_get_attr_by_NID , +.Fn CMS_signed_get_attr_by_OBJ , +.Fn CMS_unsigned_get_attr_by_NID , +and +.Fn CMS_unsigned_get_attr_by_OBJ +return the index of the first object in the array that has an index greater than +.Fa lastpos +and a type matching +.Fa nid +or +.Fa oid , +respectively, or -1 on failure. +In addition, +.Fn CMS_signed_get_attr_by_OBJ +and +.Fn CMS_unsigned_get_attr_by_OBJ +return -2 if +.Xr OBJ_nid2obj 3 +fails on the requested +.Fa nid . +.Pp +.Fn CMS_signed_get_attr_count +and +.Fn CMS_unsigned_get_attr_count +return the number of array elements or -1 on failure. +.Sh SEE ALSO +.Xr X509_ATTRIBUTE_new 3 +.Sh HISTORY +.Fn CMS_signed_add1_attr , +.Fn CMS_signed_add1_attr_by_NID , +.Fn CMS_signed_add1_attr_by_OBJ , +.Fn CMS_signed_add1_attr_by_txt , +.Fn CMS_signed_delete_attr , +.Fn CMS_signed_get0_data_by_OBJ , +.Fn CMS_signed_get_attr , +.Fn CMS_signed_get_attr_by_NID , +.Fn CMS_signed_get_attr_by_OBJ , +.Fn CMS_signed_get_attr_count , +.Fn CMS_unsigned_add1_attr , +.Fn CMS_unsigned_add1_attr_by_NID , +.Fn CMS_unsigned_add1_attr_by_OBJ , +.Fn CMS_unsigned_add1_attr_by_txt , +.Fn CMS_unsigned_delete_attr , +.Fn CMS_unsigned_get0_data_by_OBJ , +.Fn CMS_unsigned_get_attr , +.Fn CMS_unsigned_get_attr_by_NID , +.Fn CMS_unsigned_get_attr_by_OBJ +and +.Fn CMS_unsigned_get_attr_count +first appeared in OpenSSL 0.9.9 and have been available since +.Ox 6.6 . Index: Makefile =================================================================== RCS file: /cvs/src/lib/libcrypto/man/Makefile,v diff -u -p -r1.280 Makefile --- Makefile 29 Dec 2023 19:15:15 -0000 1.280 +++ Makefile 19 Jan 2024 15:30:15 -0000 @@ -100,6 +100,7 @@ MAN= \ CMS_get1_ReceiptRequest.3 \ CMS_sign.3 \ CMS_sign_receipt.3 \ + CMS_signed_add1_attr.3 \ CMS_uncompress.3 \ CMS_verify.3 \ CMS_verify_receipt.3 \