new manual page PKCS7_add_attribute(3);

tweaks and OK tb@

7 files changed, 201 insertions, 12 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 05b992e132..7effea8379 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.165 2020/06/03 13:41:27 schwarze Exp $
+# $OpenBSD: Makefile,v 1.166 2020/06/04 10:24:27 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -214,6 +214,7 @@ MAN=	\
         PKCS12_parse.3 \
         PKCS12_SAFEBAG_new.3 \
         PKCS5_PBKDF2_HMAC.3 \
+        PKCS7_add_attribute.3 \
         PKCS7_dataFinal.3 \
         PKCS7_dataInit.3 \
         PKCS7_decrypt.3 \
diff --git a/src/lib/libcrypto/man/PKCS7_add_attribute.3 b/src/lib/libcrypto/man/PKCS7_add_attribute.3
new file mode 100644
index 0000000000..09c36a4d5d
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_add_attribute.3
@@ -0,0 +1,179 @@
+.\" $OpenBSD: PKCS7_add_attribute.3,v 1.1 2020/06/04 10:24:27 schwarze Exp $
+.\"
+.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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 4 2020 $
+.Dt PKCS7_ADD_ATTRIBUTE 3
+.Os
+.Sh NAME
+.Nm PKCS7_add_attribute ,
+.Nm PKCS7_get_attribute ,
+.Nm PKCS7_add_signed_attribute ,
+.Nm PKCS7_get_signed_attribute
+.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 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 ASN1_TYPE *
+.Fo PKCS7_get_signed_attribute
+.Fa "PKCS7_SIGNER_INFO *si"
+.Fa "int nid"
+.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_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
+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 the undocumented function
+.Fn PKCS7_get_signer_info
+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
+For particular types of attributes, undocumented wrapper functions
+.Fn PKCS7_add_attrib_content_type ,
+.Fn PKCS7_add1_attrib_digest ,
+.Fn PKCS7_add0_attrib_signing_time ,
+and
+.Fn PKCS7_add_attrib_smimecap
+exist.
+.Sh RETURN VALUES
+.Fn PKCS7_add_attribute
+and
+.Fn PKCS7_add_signed_attribute
+return 1 on success or 0 on failure.
+The most common reason for failure is lack of memory.
+.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_TYPE_new 3 ,
+.Xr PKCS7_final 3 ,
+.Xr PKCS7_new 3 ,
+.Xr PKCS7_sign 3 ,
+.Xr PKCS7_sign_add_signer 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_ATTRIBUTE_new 3
+.Sh STANDARDS
+RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5,
+section 9.2: SignerInfo type
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.1
+and have been available since
+.Ox 2.6 .
+.Sh BUGS
+Adding an attribute with an invalid
+.Fa nid
+ought to fail, but it actually succeeds
+setting the type of the new attribute to
+.Dv NULL .
+Subsequent attempts to retrieve attributes
+may cause the program to crash due to
+.Dv NULL
+pointer access.
+.Pp
+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 .
diff --git a/src/lib/libcrypto/man/PKCS7_final.3 b/src/lib/libcrypto/man/PKCS7_final.3
index 593483bb6d..7c9e51521a 100644
--- a/src/lib/libcrypto/man/PKCS7_final.3
+++ b/src/lib/libcrypto/man/PKCS7_final.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_final.3,v 1.1 2020/06/03 13:41:27 schwarze Exp $
+.\" $OpenBSD: PKCS7_final.3,v 1.2 2020/06/04 10:24:27 schwarze Exp $
 .\"
 .\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 3 2020 $
+.Dd $Mdocdate: June 4 2020 $
 .Dt PKCS7_FINAL 3
 .Os
 .Sh NAME
@@ -186,6 +186,7 @@ Signers lacking private keys do not cause failure but are silently skipped.
 .Xr BIO_new 3 ,
 .Xr i2d_PKCS7_bio_stream 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PKCS7_add_attribute 3 ,
 .Xr PKCS7_dataFinal 3 ,
 .Xr PKCS7_dataInit 3 ,
 .Xr PKCS7_encrypt 3 ,
diff --git a/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3
index 4abe3698e6..c5eebe96d5 100644
--- a/src/lib/libcrypto/man/PKCS7_new.3
+++ b/src/lib/libcrypto/man/PKCS7_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_new.3,v 1.10 2020/05/27 12:00:44 schwarze Exp $
+.\" $OpenBSD: PKCS7_new.3,v 1.11 2020/06/04 10:24:27 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: May 27 2020 $
+.Dd $Mdocdate: June 4 2020 $
 .Dt PKCS7_NEW 3
 .Os
 .Sh NAME
@@ -246,6 +246,7 @@ frees
 .Xr i2d_PKCS7_bio_stream 3 ,
 .Xr PEM_read_PKCS7 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PKCS7_add_attribute 3 ,
 .Xr PKCS7_dataFinal 3 ,
 .Xr PKCS7_dataInit 3 ,
 .Xr PKCS7_decrypt 3 ,
diff --git a/src/lib/libcrypto/man/PKCS7_sign.3 b/src/lib/libcrypto/man/PKCS7_sign.3
index d5f4c89c61..c9b13680c3 100644
--- a/src/lib/libcrypto/man/PKCS7_sign.3
+++ b/src/lib/libcrypto/man/PKCS7_sign.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_sign.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $
+.\" $OpenBSD: PKCS7_sign.3,v 1.12 2020/06/04 10:24:27 schwarze Exp $
 .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 3 2020 $
+.Dd $Mdocdate: June 4 2020 $
 .Dt PKCS7_SIGN 3
 .Os
 .Sh NAME
@@ -196,7 +196,9 @@ if the
 .Dv PKCS7_PARTIAL
 flag is set.
 One or more signers can be added using the function
-.Xr PKCS7_sign_add_signer 3 .
+.Xr PKCS7_sign_add_signer 3
+and attributes can be added using the functions described in
+.Xr PKCS7_add_attribute 3 .
 .Xr PKCS7_final 3
 must also be called to finalize the structure if streaming is not
 enabled.
@@ -228,6 +230,7 @@ if an error occurred.
 The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr PKCS7_add_attribute 3 ,
 .Xr PKCS7_encrypt 3 ,
 .Xr PKCS7_final 3 ,
 .Xr PKCS7_new 3 ,
diff --git a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
index f8024d9b5c..28d327fefc 100644
--- a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
+++ b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $
+.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.12 2020/06/04 10:24:27 schwarze Exp $
 .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 3 2020 $
+.Dd $Mdocdate: June 4 2020 $
 .Dt PKCS7_SIGN_ADD_SIGNER 3
 .Os
 .Sh NAME
@@ -162,6 +162,8 @@ If any of these algorithms is disabled, then it will not be included.
 returns an internal pointer to the
 .Vt PKCS7_SIGNER_INFO
 structure just added, which can be used to set additional attributes
+with the functions described in
+.Xr PKCS7_add_attribute 3
 before it is finalized.
 .Sh RETURN VALUES
 .Fn PKCS7_sign_add_signer
@@ -174,6 +176,7 @@ In some cases of failure, the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr EVP_DigestInit 3 ,
+.Xr PKCS7_add_attribute 3 ,
 .Xr PKCS7_final 3 ,
 .Xr PKCS7_new 3 ,
 .Xr PKCS7_sign 3
diff --git a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3
index b5c78ee8d4..66779d637b 100644
--- a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3
+++ b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: X509_ATTRIBUTE_new.3,v 1.7 2019/06/06 01:06:59 schwarze Exp $
+.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.8 2020/06/04 10:24:27 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 6 2019 $
+.Dd $Mdocdate: June 4 2020 $
 .Dt X509_ATTRIBUTE_NEW 3
 .Os
 .Sh NAME
@@ -65,6 +65,7 @@ if an error occurs.
 .Sh SEE ALSO
 .Xr d2i_X509_ATTRIBUTE 3 ,
 .Xr PKCS12_SAFEBAG_new 3 ,
+.Xr PKCS7_add_attribute 3 ,
 .Xr PKCS8_PRIV_KEY_INFO_new 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_new 3 ,