lib/libcrypto/man/TS_REQ_new.3

   1 .\"     $OpenBSD: TS_REQ_new.3,v 1.4 2016/12/25 22:15:10 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: December 25 2016 $
  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
  61 A time-stamping authority is a trusted third party which allows its
  62 clients to prove that specific data existed at a particular point
  63 in time.
  64 Clients send time-stamping requests to the time-stamping server,
  65 which returns time-stamp tokens to the clients.
  66 .Pp
  67 .Fn TS_REQ_new
  68 allocates and initializes an empty
  69 .Vt TS_REQ
  70 object, representing an ASN.1
  71 .Vt TimeStampReq
  72 structure defined in RFC 3161 section 2.4.1.
  73 It can hold a hash of the datum to be time-stamped and some
  74 auxiliary, optional information.
  75 .Fn TS_REQ_free
  76 frees
  77 .Fa req .
  78 .Pp
  79 .Fn TS_RESP_new
  80 allocates and initializes an empty
  81 .Vt TS_RESP
  82 object, representing an ASN.1
  83 .Vt TimeStampResp
  84 structure defined in RFC 3161 section 2.4.2.
  85 It can hold status information and a time-stamp token.
  86 .Fn TS_RESP_free
  87 frees
  88 .Fa resp .
  89 .Pp
  90 .Fn TS_STATUS_INFO_new
  91 allocates and initializes an empty
  92 .Vt TS_STATUS_INFO
  93 object, representing an ASN.1
  94 .Vt PKIStatusInfo
  95 structure defined in RFC 3161 section 2.4.2.
  96 It is used inside
  97 .Vt TS_RESP
  98 and describes the outcome of one time-stamp request.
  99 .Fn TS_STATUS_INFO_free
 100 frees
 101 .Fa status .
 102 .Pp
 103 .Fn TS_TST_INFO_new
 104 allocates and initializes an empty
 105 .Vt TS_TST_INFO
 106 object, representing an ASN.1
 107 .Vt TSTInfo
 108 structure defined in RFC 3161 section 2.4.2.
 109 It is the time-stamp token included in a
 110 .Vt TS_RESP
 111 object in case of success, and it can hold the hash of the datum
 112 copied from a request, the time of generation, and some auxiliary
 113 information.
 114 .Fn TS_TST_INFO_free
 115 frees
 116 .Fa token .
 117 .Pp
 118 .Fn TS_ACCURACY_new
 119 allocates and initializes an empty
 120 .Vt TS_ACCURACY
 121 object, representing an ASN.1
 122 .Vt Accuracy
 123 structure defined in RFC 3161 section 2.4.2.
 124 It can be used inside a
 125 .Vt TS_TST_INFO
 126 object and indicates the maximum error of the time stated in the token.
 127 .Fn TS_ACCURACY_free
 128 frees
 129 .Fa accuracy .
 130 .Pp
 131 .Fn TS_MSG_IMPRINT_new
 132 allocates and initializes an empty
 133 .Vt TS_MSG_IMPRINT
 134 object, representing an ASN.1
 135 .Vt MessageImprint
 136 structure defined in RFC 3161 section 2.4.1.
 137 It is used inside
 138 .Vt TS_REQ
 139 and
 140 .Vt TS_RESP
 141 objects.
 142 It specifies a hash algorithm and stores the hash value of the datum.
 143 .Fn TS_MSG_IMPRINT_free
 144 frees
 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 ,
 152 and
 153 .Fn TS_MSG_IMPRINT_new
 154 return the new
 155 .Vt TS_REQ ,
 156 .Vt TS_RESP ,
 157 .Vt TS_STATUS_INFO ,
 158 .Vt TS_TST_INFO ,
 159 .Vt TS_ACCURACY ,
 160 or
 161 .Vt TS_MSG_IMPRINT
 162 object, respectively, or
 163 .Dv NULL
 164 if an error occurred.
 165 .Sh SEE ALSO
 166 .Xr ACCESS_DESCRIPTION_new 3 ,
 167 .Xr ESS_SIGNING_CERT_new 3
 168 .Sh STANDARDS
 169 RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol
 170 .Pp
 171 Note that RFC 3161 has been updated
 172 by RFC 5816: ESSCertIDv2 Update for RFC 3161.
 173 That update allows using the Signing Certificate Attribute Definition
 174 Version 2 according to RFC 5035, but the current implementation
 175 only supports the Signing Certificate Attribute Definition Version
 176 1 according to RFC 2634, and hence only supports RFC 3161, but not
 177 RFC 5816 functionality.