From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/PKCS7_add_attribute.3 | 365 ---------------------------- 1 file changed, 365 deletions(-) delete mode 100644 src/lib/libcrypto/man/PKCS7_add_attribute.3 (limited to 'src/lib/libcrypto/man/PKCS7_add_attribute.3') diff --git a/src/lib/libcrypto/man/PKCS7_add_attribute.3 b/src/lib/libcrypto/man/PKCS7_add_attribute.3 deleted file mode 100644 index 4a1c350f98..0000000000 --- a/src/lib/libcrypto/man/PKCS7_add_attribute.3 +++ /dev/null @@ -1,365 +0,0 @@ -.\" $OpenBSD: PKCS7_add_attribute.3,v 1.3 2020/06/10 11:39:12 schwarze Exp $ -.\" -.\" Copyright (c) 2020 Ingo Schwarze -.\" -.\" 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: June 10 2020 $ -.Dt PKCS7_ADD_ATTRIBUTE 3 -.Os -.Sh NAME -.Nm PKCS7_add_attribute , -.Nm PKCS7_set_attributes , -.Nm PKCS7_get_attribute , -.Nm PKCS7_add_signed_attribute , -.Nm PKCS7_set_signed_attributes , -.Nm PKCS7_get_signed_attribute , -.Nm PKCS7_add_attrib_content_type , -.Nm PKCS7_add1_attrib_digest , -.Nm PKCS7_add0_attrib_signing_time , -.Nm PKCS7_add_attrib_smimecap -.Nd attributes of SignerInfo objects -.Sh SYNOPSIS -.In openssl/pkcs7.h -.Ft int -.Fo PKCS7_add_attribute -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "int nid" -.Fa "int attrtype" -.Fa "void *value" -.Fc -.Ft int -.Fo PKCS7_set_attributes -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "STACK_OF(X509_ATTRIBUTE) *sk" -.Fc -.Ft ASN1_TYPE * -.Fo PKCS7_get_attribute -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "int nid" -.Fc -.Ft int -.Fo PKCS7_add_signed_attribute -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "int nid" -.Fa "int attrtype" -.Fa "void *value" -.Fc -.Ft int -.Fo PKCS7_set_signed_attributes -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "STACK_OF(X509_ATTRIBUTE) *sk" -.Fc -.Ft ASN1_TYPE * -.Fo PKCS7_get_signed_attribute -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "int nid" -.Fc -.Ft int -.Fo PKCS7_add_attrib_content_type -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "ASN1_OBJECT *coid" -.Fc -.Ft int -.Fo PKCS7_add1_attrib_digest -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "const unsigned char *md" -.Fa "int mdlen" -.Fc -.Ft int -.Fo PKCS7_add0_attrib_signing_time -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "ASN1_TIME *t" -.Fc -.Ft int -.Fo PKCS7_add_attrib_smimecap -.Fa "PKCS7_SIGNER_INFO *si" -.Fa "STACK_OF(X509_ALGOR) *cap" -.Fc -.Sh DESCRIPTION -.Fn PKCS7_add_attribute -appends a new attribute of type -.Fa nid -to the -.Fa unauthenticatedAttributes -list of -.Fa si , -and it adds a new ASN.1 ANY object of type -.Fa attrtype -with the given -.Fa value -to the new attribute. -Ownership of the -.Fa value -is transferred into the new attribute object, so the calling code -must not -.Xr free 3 -the -.Fa value . -If the list already contains an unauthenticated attribute of type -.Fa nid -before the call, the new attribute replaces the old one -instead of being appended to the end of the list. -.Pp -.Fn PKCS7_set_attributes -frees the -.Fa unauthenticatedAttributes -list of -.Fa si -and all the attributes contained in it and replaces it with a deep copy of -.Fa sk . -.Pp -.Fn PKCS7_get_attribute -retrieves the first ASN.1 ANY member of the attribute of type -.Fa nid -from the -.Fa unauthenticatedAttributes -list of -.Fa si . -.Pp -The behaviour of -.Fn PKCS7_add_signed_attribute , -.Fn PKCS7_set_signed_attributes , -and -.Fn PKCS7_get_signed_attribute -is identical except that they operate on the list of -.Fa authenticatedAttributes . -.Pp -The normal way to use -.Fn PKCS7_add_signed_attribute -is to first create a -.Vt SignedInfo -object with -.Xr PKCS7_sign 3 -using the -.Dv PKCS7_PARTIAL -or -.Dv PKCS7_STREAM -flag, retrieve the -.Vt PKCS7_SIGNER_INFO -object with -.Xr PKCS7_get_signer_info 3 -or add an additional one with -.Xr PKCS7_sign_add_signer 3 , -call -.Fn PKCS7_add_signed_attribute -for each desired additional attribute, then do the signing with -.Xr PKCS7_final 3 -or with another finalizing function. -.Pp -The four remaining functions are wrappers around -.Fn PKCS7_add_signed_attribute . -.Pp -.Fn PKCS7_add_attrib_content_type -sets the -.Dv NID_pkcs9_contentType -attribute to -.Fa coid , -which specifies the content type of the -.Vt ContentInfo -value to be signed. -This attribute is mandatory and automatically added by -.Xr PKCS7_sign 3 -and -.Xr PKCS7_sign_add_signer 3 -unless the -.Dv PKCS7_NOATTR -flag is present. -Objects suitable as -.Fa coid -arguments can for example be obtained with -.Xr OBJ_nid2obj 3 . -If -.Fa coid -is -.Dv NULL , -the content type defaults to -.Dv NID_pkcs7_data . -.Pp -.Fn PKCS7_add1_attrib_digest -sets or replaces the -.Dv NID_pkcs9_messageDigest -attribute, which is the message digest of the contents octets -of the DER-encoding of the content field of the -.Vt ContentInfo -value being signed, to a copy of -.Fa md , -which is assumed to be -.Fa mdlen -bytes long. -If -.Fa mdlen -is -1, then -.Fn strlen md -is used instead of -.Fa mdlen . -This attribute is mandatory and automatically added by -.Xr PKCS7_dataFinal 3 -and -.Xr PKCS7_final 3 . -.Pp -.Fn PKCS7_add0_attrib_signing_time -sets or replaces the optional -.Dv NID_pkcs9_signingTime -attribute to -.Fa t , -specifying the time at which the signer performed the signing process. -Ownership of -.Fa t -is transferred into the new attribute object, so the calling code -must not -.Xr free 3 -.Fa t . -If -.Fa t -is -.Dv NULL , -a new -.Vt ASN1_TIME -structure is allocated. -This attribute is automatically added by -.Xr PKCS7_dataFinal 3 -and -.Xr PKCS7_final 3 . -.Pp -.Fn PKCS7_add_attrib_smimecap -sets or replaces the optional -.Dv NID_SMIMECapabilities -attribute, indicating algorithms the sender is prepared to handle. -The -.Fa cap -pointer is not stored in the new attribute object and can be passed to -.Fn sk_X509_ALGOR_pop_free -after the call. -This attribute is automatically added by -.Xr PKCS7_sign 3 -and -.Xr PKCS7_sign_add_signer 3 -unless the -.Dv PKCS7_NOATTR -or -.Dv PKCS7_NOSMIMECAP -flag is present. -.Sh RETURN VALUES -.Fn PKCS7_add_attribute , -.Fn PKCS7_set_attributes , -.Fn PKCS7_add_signed_attribute , -.Fn PKCS7_set_signed_attributes , -.Fn PKCS7_add_attrib_content_type , -.Fn PKCS7_add1_attrib_digest , -.Fn PKCS7_add0_attrib_signing_time , -and -.Fn PKCS7_add_attrib_smimecap -return 1 on success or 0 on failure. -The most common reason for failure is lack of memory. -.Fn PKCS7_add_attribute -and -.Fn PKCS7_add_signed_attribute -also fail if -.Fa nid -is invalid, and -.Fn PKCS7_add_attrib_content_type -if -.Fa si -already contains an authenticated attribute of type -.Dv NID_pkcs9_contentType . -.Pp -.Fn PKCS7_get_attribute -and -.Fn PKCS7_get_signed_attribute -return an internal pointer to an ASN.1 ANY object or -.Dv NULL -on failure. -They fail if -.Fa nid -is invalid, if the respective list in -.Fa si -contains no attribute of the requested type, or if an invalid element -is found in the list before finding the attribute of the requested type. -.Sh SEE ALSO -.Xr ASN1_TIME_new 3 , -.Xr ASN1_TYPE_new 3 , -.Xr OBJ_nid2obj 3 , -.Xr PKCS7_final 3 , -.Xr PKCS7_get_signer_info 3 , -.Xr PKCS7_new 3 , -.Xr PKCS7_sign 3 , -.Xr PKCS7_sign_add_signer 3 , -.Xr STACK_OF 3 , -.Xr X509_ALGOR_new 3 , -.Xr X509_ATTRIBUTE_new 3 -.Sh STANDARDS -RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5, -section 9.2: SignerInfo type -.Pp -RFC 2985: PKCS #9: Selected Object Classes and Attribute Types Version 2.0, -section 5.3: Attribute types for use in PKCS #7 data -and section 5.6: Attributes defined in S/MIME -.Pp -RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) -Version 4.0 Message Specification, -section 2.5.2: SMIMECapabilities Attribute -.Sh HISTORY -.Fn PKCS7_add_attribute , -.Fn PKCS7_set_attributes , -.Fn PKCS7_get_attribute , -.Fn PKCS7_add_signed_attribute , -.Fn PKCS7_set_signed_attributes , -and -.Fn PKCS7_get_signed_attribute -first appeared in OpenSSL 0.9.1 and have been available since -.Ox 2.6 . -.Pp -.Fn PKCS7_add_attrib_smimecap -first appeared in OpenSSL 0.9.5 and has been available since -.Ox 2.7 . -.Pp -.Fn PKCS7_add_attrib_content_type , -.Fn PKCS7_add1_attrib_digest , -and -.Fn PKCS7_add0_attrib_signing_time -first appeared in OpenSSL 1.0.0 and have been available since -.Ox 4.9 . -.Sh CAVEATS -.Fn PKCS7_set_signed_attributes -does not validate that -.Fa sk -contains the PKCS #9 content type and message digest attributes -required by RFC 2315. -It succeeds even when -.Fa sk -is empty, leaving -.Fa si -in a state that violates the standard. -.Pp -.Fn PKCS7_add0_attrib_signing_time -does not validate -.Fa t -in any way. -In particular, it may set the signing time to the future -or to the remote past. -.Sh BUGS -A function to remove individual attributes from these lists -does not appear to exist. -A program desiring to do that might have to manually iterate the fields -.Fa auth_attr -and -.Fa unauth_attr -of -.Fa si , -which are both of type -.Vt STACK_OF(X509_ATTRIBUTE) , -using the facilities described in -.Xr STACK_OF 3 -and -.Xr OPENSSL_sk_new 3 . -- cgit v1.2.3-55-g6feb