1 files changed, 107 insertions, 0 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.