New manuals ESS_SIGNING_CERT_new(3) and TS_REQ_new(3) written

from scratch.  All these functions are listed in <openssl/ts.h>
and in OpenSSL doc/man3/X509_dup.pod.
Note that the OpenSSL documentation specifies the wrong header file.

3 files changed, 279 insertions, 1 deletions

diff --git a/src/lib/libcrypto/man/ESS_SIGNING_CERT_new.3 b/src/lib/libcrypto/man/ESS_SIGNING_CERT_new.3
new file mode 100644
index 0000000000..d942a03e34
--- /dev/null
+++ b/src/lib/libcrypto/man/ESS_SIGNING_CERT_new.3
@@ -0,0 +1,107 @@
+.\"     $OpenBSD: ESS_SIGNING_CERT_new.3,v 1.1 2016/12/14 02:03:50 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 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: December 14 2016 $
+.Dt ESS_SIGNING_CERT_NEW 3
+.Os
+.Sh NAME
+.Nm ESS_SIGNING_CERT_new ,
+.Nm ESS_SIGNING_CERT_free ,
+.Nm ESS_CERT_ID_new ,
+.Nm ESS_CERT_ID_free ,
+.Nm ESS_ISSUER_SERIAL_new ,
+.Nm ESS_ISSUER_SERIAL_free
+.Nd signing certificates for S/MIME
+.Sh SYNOPSIS
+.In openssl/ts.h
+.Ft ESS_SIGNING_CERT *
+.Fn ESS_SIGNING_CERT_new void
+.Ft void
+.Fn ESS_SIGNING_CERT_free "ESS_SIGNING_CERT *signing_cert"
+.Ft ESS_CERT_ID *
+.Fn ESS_CERT_ID_new void
+.Ft void
+.Fn ESS_CERT_ID_free "ESS_CERT_ID *cert_id"
+.Ft ESS_ISSUER_SERIAL *
+.Fn ESS_ISSUER_SERIAL_new void
+.Ft void
+.Fn ESS_ISSUER_SERIAL_free "ESS_ISSUER_SERIAL *issuer_serial"
+.Sh DESCRIPTION
+The signing certificate may be included in the signedAttributes
+field of a SignerInfo structure to mitigate simple substitution and
+re-issue attacks.
+.Pp
+.Fn ESS_SIGNING_CERT_new
+allocates and initializes an empty
+.Vt ESS_SIGNING_CERT
+object, representing an ASN.1 SigningCertificate structure
+defined in RFC 2634 section 5.4.
+It can hold the certificate used for signing the data,
+additional authorization certificates that can be used during
+validation, and policies applying to the certificate.
+.Fn ESS_SIGNING_CERT_free
+frees
+.Fa signing_cert .
+.Pp
+.Fn ESS_CERT_ID_new
+allocates and initializes an empty
+.Vt ESS_CERT_ID
+object, representing an ASN.1 ESSCertID structure
+defined in RFC 2634 section 5.4.1.
+Such objects can be used inside
+.Vt ESS_SIGNING_CERT
+objects, and each one can hold an SHA1 hash of one certificate.
+.Fn ESS_CERT_ID_free
+frees
+.Fa cert_id .
+.Pp
+.Fn ESS_ISSUER_SERIAL_new
+allocates and initializes an empty
+.Vt ESS_ISSUER_SERIAL
+object, representing an ASN.1 IssuerSerial structure
+defined in RFC 2634 section 5.4.1.
+It can hold an issuer name and a serial number and can be included in an
+.Vt ESS_CERT_ID
+object, which is useful for additional authorization certificates,
+but redundant for the signing certificate itself.
+.Fn ESS_ISSUER_SERIAL_free
+frees
+.Fa issuer_serial .
+.Sh RETURN VALUES
+.Fn ESS_SIGNING_CERT_new ,
+.Fn ESS_CERT_ID_new ,
+and
+.Fn ESS_ISSUER_SERIAL_new
+return the new
+.Vt ESS_SIGNING_CERT ,
+.Vt ESS_CERT_ID ,
+or
+.Vt ESS_ISSUER_SERIAL
+object, respectively, or
+.Dv NULL
+if an error occurred.
+.Sh STANDARDS
+RFC 2634: Enhanced Security Services for S/MIME,
+section 5: Signing Certificate Attribute
+.Pp
+Note that RFC 2634 has been updated by RFC 5035:
+Enhanced Security Services (ESS) Update:
+Adding CertID Algorithm Agility.
+But the current implementation only supports the
+Signing Certificate Attribute Definition Version 1
+according to RFC 2634, not the
+Signing Certificate Attribute Definition Version 2
+according to RFC 5035.
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 02895f010a..426b3c4c9b 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.77 2016/12/13 20:41:35 schwarze Exp $
+# $OpenBSD: Makefile,v 1.78 2016/12/14 02:03:50 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -94,6 +94,7 @@ MAN=	\
         ERR_put_error.3 \
         ERR_remove_state.3 \
         ERR_set_mark.3 \
+        ESS_SIGNING_CERT_new.3 \
         EVP_AEAD_CTX_init.3 \
         EVP_BytesToKey.3 \
         EVP_DigestInit.3 \
@@ -172,6 +173,7 @@ MAN=	\
         SHA1.3 \
         SMIME_read_PKCS7.3 \
         SMIME_write_PKCS7.3 \
+        TS_REQ_new.3 \
         UI_new.3 \
         X509V3_get_d2i.3 \
         X509_ALGOR_dup.3 \
diff --git a/src/lib/libcrypto/man/TS_REQ_new.3 b/src/lib/libcrypto/man/TS_REQ_new.3
new file mode 100644
index 0000000000..0613279b57
--- /dev/null
+++ b/src/lib/libcrypto/man/TS_REQ_new.3
@@ -0,0 +1,169 @@
+.\"     $OpenBSD: TS_REQ_new.3,v 1.1 2016/12/14 02:03:50 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 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: December 14 2016 $
+.Dt TS_REQ_NEW 3
+.Os
+.Sh NAME
+.Nm TS_REQ_new ,
+.Nm TS_REQ_free ,
+.Nm TS_RESP_new ,
+.Nm TS_RESP_free ,
+.Nm TS_STATUS_INFO_new ,
+.Nm TS_STATUS_INFO_free ,
+.Nm TS_TST_INFO_new ,
+.Nm TS_TST_INFO_free ,
+.Nm TS_ACCURACY_new ,
+.Nm TS_ACCURACY_free ,
+.Nm TS_MSG_IMPRINT_new ,
+.Nm TS_MSG_IMPRINT_free ,
+.Nd X.509 time-stamp protocol
+.Sh SYNOPSIS
+.In openssl/ts.h
+.Ft TS_REQ *
+.Fn TS_REQ_new void
+.Ft void
+.Fn TS_REQ_free "TS_REQ *req"
+.Ft TS_RESP *
+.Fn TS_RESP_new void
+.Ft void
+.Fn TS_RESP_free "TS_RESP *resp"
+.Ft TS_STATUS_INFO *
+.Fn TS_STATUS_INFO_new void
+.Ft void
+.Fn TS_STATUS_INFO_free "TS_STATUS_INFO *status"
+.Ft TS_TST_INFO *
+.Fn TS_TST_INFO_new void
+.Ft void
+.Fn TS_TST_INFO_free "TS_TST_INFO *token"
+.Ft TS_ACCURACY *
+.Fn TS_ACCURACY_new void
+.Ft void
+.Fn TS_ACCURACY_free "TS_ACCURACY *accuracy"
+.Ft TS_MSG_IMPRINT *
+.Fn TS_MSG_IMPRINT_new void
+.Ft void
+.Fn TS_MSG_IMPRINT_free "TS_MSG_IMPRINT *imprint"
+.Sh DESCRIPTION
+A time-stamping authority is a trusted third party allowing its
+clients to prove that specific data existed at a particular point
+in time.  Clients send time-stamping requests to the time-stamping
+server, which returns time-stamp tokens to the clients.
+.Pp
+.Fn TS_REQ_new
+allocates and initializes an empty
+.Vt TS_REQ
+object, representing an ASN.1 TimeStampReq structure
+defined in RFC 3161 section 2.4.1.
+It can hold a hash of the datum to be time-stamped and some
+auxiliary, optional information.
+.Fn TS_REQ_free
+frees
+.Fa req .
+.Pp
+.Fn TS_RESP_new
+allocates and initializes an empty
+.Vt TS_RESP
+object, representing an ASN.1 TimeStampResp structure
+defined in RFC 3161 section 2.4.2.
+It can hold status information and a time-stamp token.
+.Fn TS_RESP_free
+frees
+.Fa resp .
+.Pp
+.Fn TS_STATUS_INFO_new
+allocates and initializes an empty
+.Vt TS_STATUS_INFO
+object, representing an ASN.1 PKIStatusInfo structure
+defined in RFC 3161 section 2.4.2.
+It is used inside
+.Vt TS_RESP
+and describes the outcome of one time-stamp request.
+.Fn TS_STATUS_INFO_free
+frees
+.Fa status .
+.Pp
+.Fn TS_TST_INFO_new
+allocates and initializes an empty
+.Vt TS_TST_INFO
+object, representing an ASN.1 TSTInfo structure
+defined in RFC 3161 section 2.4.2.
+It is the time-stamp token included in a
+.Vt TS_RESP
+object in case of success, and it can hold the hash of the datum
+copied from a request, the time of generation, and some auxiliary
+information.
+.Fn TS_TST_INFO_free
+frees
+.Fa token .
+.Pp
+.Fn TS_ACCURACY_new
+allocates and initializes an empty
+.Vt TS_ACCURACY
+object, representing an ASN.1 Accuracy structure
+defined in RFC 3161 section 2.4.2.
+It can be used inside a
+.Vt TS_TST_INFO
+object and indicates the maximum error of the time stated in the token.
+.Fn TS_ACCURACY_free
+frees
+.Fa accuracy .
+.Pp
+.Fn TS_MSG_IMPRINT_new
+allocates and initializes an empty
+.Vt TS_MSG_IMPRINT
+object, representing an ASN.1 MessageImprint structure
+defined in RFC 3161 section 2.4.1.
+It is used inside
+.Vt TS_REQ
+and
+.Vt TS_RESP
+objects.
+It specifies a hash algorithm and stores the hash value of the datum.
+.Fn TS_MSG_IMPRINT_free
+frees
+.Fa imprint .
+.Sh RETURN VALUES
+.Fn TS_REQ_new ,
+.Fn TS_RESP_new ,
+.Fn TS_STATUS_INFO_new ,
+.Fn TS_TST_INFO_new ,
+.Fn TS_ACCURACY_new ,
+and
+.Fn TS_MSG_IMPRINT_new
+return the new
+.Vt TS_REQ ,
+.Vt TS_RESP ,
+.Vt TS_STATUS_INFO ,
+.Vt TS_TST_INFO ,
+.Vt TS_ACCURACY ,
+or
+.Vt TS_MSG_IMPRINT
+object, respectively, or
+.Dv NULL
+if an error occurred.
+.Sh SEE ALSO
+.Xr ESS_SIGNING_CERT_new 3
+.Sh STANDARDS
+RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol
+.Pp
+Note that RFC 3161 has been updated
+by RFC 5816: ESSCertIDv2 Update for RFC 3161.
+That update allows using the Signing Certificate Attribute Definition
+Version 2 according to RFC 5035, but the current implementation
+only supports the Signing Certificate Attribute Definition Version
+1 according to RFC 2634, and hence only supports RFC 3161, but not
+RFC 5816 functionality.