From ae8c27c4410d3494a37f436b324383ac1f79f7c5 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 14 Dec 2016 02:03:50 +0000 Subject: 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. --- src/lib/libcrypto/man/ESS_SIGNING_CERT_new.3 | 107 +++++++++++++++++ src/lib/libcrypto/man/Makefile | 4 +- src/lib/libcrypto/man/TS_REQ_new.3 | 169 +++++++++++++++++++++++++++ 3 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 src/lib/libcrypto/man/ESS_SIGNING_CERT_new.3 create mode 100644 src/lib/libcrypto/man/TS_REQ_new.3 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. -- cgit v1.2.3-55-g6feb