1.\" $OpenBSD: TS_REQ_new.3,v 1.6 2019/06/06 01:06:59 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 TS_REQ_NEW 3 19.Os 20.Sh NAME 21.Nm TS_REQ_new , 22.Nm TS_REQ_free , 23.Nm TS_RESP_new , 24.Nm TS_RESP_free , 25.Nm TS_STATUS_INFO_new , 26.Nm TS_STATUS_INFO_free , 27.Nm TS_TST_INFO_new , 28.Nm TS_TST_INFO_free , 29.Nm TS_ACCURACY_new , 30.Nm TS_ACCURACY_free , 31.Nm TS_MSG_IMPRINT_new , 32.Nm TS_MSG_IMPRINT_free 33.Nd X.509 time-stamp protocol 34.Sh SYNOPSIS 35.In openssl/ts.h 36.Ft TS_REQ * 37.Fn TS_REQ_new void 38.Ft void 39.Fn TS_REQ_free "TS_REQ *req" 40.Ft TS_RESP * 41.Fn TS_RESP_new void 42.Ft void 43.Fn TS_RESP_free "TS_RESP *resp" 44.Ft TS_STATUS_INFO * 45.Fn TS_STATUS_INFO_new void 46.Ft void 47.Fn TS_STATUS_INFO_free "TS_STATUS_INFO *status" 48.Ft TS_TST_INFO * 49.Fn TS_TST_INFO_new void 50.Ft void 51.Fn TS_TST_INFO_free "TS_TST_INFO *token" 52.Ft TS_ACCURACY * 53.Fn TS_ACCURACY_new void 54.Ft void 55.Fn TS_ACCURACY_free "TS_ACCURACY *accuracy" 56.Ft TS_MSG_IMPRINT * 57.Fn TS_MSG_IMPRINT_new void 58.Ft void 59.Fn TS_MSG_IMPRINT_free "TS_MSG_IMPRINT *imprint" 60.Sh DESCRIPTION 61A time-stamping authority is a trusted third party which allows its 62clients to prove that specific data existed at a particular point 63in time. 64Clients send time-stamping requests to the time-stamping server, 65which returns time-stamp tokens to the clients. 66.Pp 67.Fn TS_REQ_new 68allocates and initializes an empty 69.Vt TS_REQ 70object, representing an ASN.1 71.Vt TimeStampReq 72structure defined in RFC 3161 section 2.4.1. 73It can hold a hash of the datum to be time-stamped and some 74auxiliary, optional information. 75.Fn TS_REQ_free 76frees 77.Fa req . 78.Pp 79.Fn TS_RESP_new 80allocates and initializes an empty 81.Vt TS_RESP 82object, representing an ASN.1 83.Vt TimeStampResp 84structure defined in RFC 3161 section 2.4.2. 85It can hold status information and a time-stamp token. 86.Fn TS_RESP_free 87frees 88.Fa resp . 89.Pp 90.Fn TS_STATUS_INFO_new 91allocates and initializes an empty 92.Vt TS_STATUS_INFO 93object, representing an ASN.1 94.Vt PKIStatusInfo 95structure defined in RFC 3161 section 2.4.2. 96It is used inside 97.Vt TS_RESP 98and describes the outcome of one time-stamp request. 99.Fn TS_STATUS_INFO_free 100frees 101.Fa status . 102.Pp 103.Fn TS_TST_INFO_new 104allocates and initializes an empty 105.Vt TS_TST_INFO 106object, representing an ASN.1 107.Vt TSTInfo 108structure defined in RFC 3161 section 2.4.2. 109It is the time-stamp token included in a 110.Vt TS_RESP 111object in case of success, and it can hold the hash of the datum 112copied from a request, the time of generation, and some auxiliary 113information. 114.Fn TS_TST_INFO_free 115frees 116.Fa token . 117.Pp 118.Fn TS_ACCURACY_new 119allocates and initializes an empty 120.Vt TS_ACCURACY 121object, representing an ASN.1 122.Vt Accuracy 123structure defined in RFC 3161 section 2.4.2. 124It can be used inside a 125.Vt TS_TST_INFO 126object and indicates the maximum error of the time stated in the token. 127.Fn TS_ACCURACY_free 128frees 129.Fa accuracy . 130.Pp 131.Fn TS_MSG_IMPRINT_new 132allocates and initializes an empty 133.Vt TS_MSG_IMPRINT 134object, representing an ASN.1 135.Vt MessageImprint 136structure defined in RFC 3161 section 2.4.1. 137It is used inside 138.Vt TS_REQ 139and 140.Vt TS_RESP 141objects. 142It specifies a hash algorithm and stores the hash value of the datum. 143.Fn TS_MSG_IMPRINT_free 144frees 145.Fa imprint . 146.Sh RETURN VALUES 147.Fn TS_REQ_new , 148.Fn TS_RESP_new , 149.Fn TS_STATUS_INFO_new , 150.Fn TS_TST_INFO_new , 151.Fn TS_ACCURACY_new , 152and 153.Fn TS_MSG_IMPRINT_new 154return the new 155.Vt TS_REQ , 156.Vt TS_RESP , 157.Vt TS_STATUS_INFO , 158.Vt TS_TST_INFO , 159.Vt TS_ACCURACY , 160or 161.Vt TS_MSG_IMPRINT 162object, respectively, or 163.Dv NULL 164if an error occurred. 165.Sh SEE ALSO 166.Xr ACCESS_DESCRIPTION_new 3 , 167.Xr ESS_SIGNING_CERT_new 3 , 168.Xr X509_EXTENSION_new 3 169.Sh STANDARDS 170RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol 171.Pp 172Note that RFC 3161 has been updated 173by RFC 5816: ESSCertIDv2 Update for RFC 3161. 174That update allows using the Signing Certificate Attribute Definition 175Version 2 according to RFC 5035, but the current implementation 176only supports the Signing Certificate Attribute Definition Version 1771 according to RFC 2634, and hence only supports RFC 3161, but not 178RFC 5816 functionality. 179.Sh HISTORY 180These functions first appeared in OpenSSL 1.0.0 181and have been available since 182.Ox 4.9 . 183