1.\" $OpenBSD: ESS_SIGNING_CERT_new.3,v 1.5 2019/06/06 01:06:58 schwarze Exp $ 2.\" 3.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: June 6 2019 $ 18.Dt ESS_SIGNING_CERT_NEW 3 19.Os 20.Sh NAME 21.Nm ESS_SIGNING_CERT_new , 22.Nm ESS_SIGNING_CERT_free , 23.Nm ESS_CERT_ID_new , 24.Nm ESS_CERT_ID_free , 25.Nm ESS_ISSUER_SERIAL_new , 26.Nm ESS_ISSUER_SERIAL_free 27.Nd signing certificates for S/MIME 28.Sh SYNOPSIS 29.In openssl/ts.h 30.Ft ESS_SIGNING_CERT * 31.Fn ESS_SIGNING_CERT_new void 32.Ft void 33.Fn ESS_SIGNING_CERT_free "ESS_SIGNING_CERT *signing_cert" 34.Ft ESS_CERT_ID * 35.Fn ESS_CERT_ID_new void 36.Ft void 37.Fn ESS_CERT_ID_free "ESS_CERT_ID *cert_id" 38.Ft ESS_ISSUER_SERIAL * 39.Fn ESS_ISSUER_SERIAL_new void 40.Ft void 41.Fn ESS_ISSUER_SERIAL_free "ESS_ISSUER_SERIAL *issuer_serial" 42.Sh DESCRIPTION 43The signing certificate may be included in the signedAttributes 44field of a 45.Vt SignerInfo 46structure to mitigate simple substitution and re-issue attacks. 47.Pp 48.Fn ESS_SIGNING_CERT_new 49allocates and initializes an empty 50.Vt ESS_SIGNING_CERT 51object, representing an ASN.1 52.Vt SigningCertificate 53structure defined in RFC 2634 section 5.4. 54It can hold the certificate used for signing the data, 55additional authorization certificates that can be used during 56validation, and policies applying to the certificate. 57.Fn ESS_SIGNING_CERT_free 58frees 59.Fa signing_cert . 60.Pp 61.Fn ESS_CERT_ID_new 62allocates and initializes an empty 63.Vt ESS_CERT_ID 64object, representing an ASN.1 65.Vt ESSCertID 66structure defined in RFC 2634 section 5.4.1. 67Such objects can be used inside 68.Vt ESS_SIGNING_CERT 69objects, and each one can hold a SHA1 hash of one certificate. 70.Fn ESS_CERT_ID_free 71frees 72.Fa cert_id . 73.Pp 74.Fn ESS_ISSUER_SERIAL_new 75allocates and initializes an empty 76.Vt ESS_ISSUER_SERIAL 77object, representing an ASN.1 78.Vt IssuerSerial 79structure defined in RFC 2634 section 5.4.1. 80It can hold an issuer name and a serial number and can be included in an 81.Vt ESS_CERT_ID 82object, which is useful for additional authorization certificates, 83but redundant for the signing certificate itself. 84.Fn ESS_ISSUER_SERIAL_free 85frees 86.Fa issuer_serial . 87.Sh RETURN VALUES 88.Fn ESS_SIGNING_CERT_new , 89.Fn ESS_CERT_ID_new , 90and 91.Fn ESS_ISSUER_SERIAL_new 92return the new 93.Vt ESS_SIGNING_CERT , 94.Vt ESS_CERT_ID , 95or 96.Vt ESS_ISSUER_SERIAL 97object, respectively, or 98.Dv NULL 99if an error occurred. 100.Sh SEE ALSO 101.Xr d2i_ESS_SIGNING_CERT 3 102.Sh STANDARDS 103RFC 2634: Enhanced Security Services for S/MIME, 104section 5: Signing Certificate Attribute 105.Pp 106Note that RFC 2634 has been updated by RFC 5035: 107Enhanced Security Services (ESS) Update: 108Adding CertID Algorithm Agility. 109But the current implementation only supports the 110Signing Certificate Attribute Definition Version 1 111according to RFC 2634, not the 112Signing Certificate Attribute Definition Version 2 113according to RFC 5035. 114.Sh HISTORY 115These functions first appeared in OpenSSL 1.0.0 116and have been available since 117.Ox 4.9 . 118