lib/libcrypto/man/X509_REVOKED_new.3

   1 .\" $OpenBSD: X509_REVOKED_new.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $
   2 .\" full merge up to:
   3 .\" OpenSSL man3/X509_CRL_get0_by_serial cdd6c8c5 Mar 20 12:29:37 2017 +0100
   4 .\"
   5 .\" This file is a derived work.
   6 .\" The changes are covered by the following Copyright and license:
   7 .\"
   8 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   9 .\"
  10 .\" Permission to use, copy, modify, and distribute this software for any
  11 .\" purpose with or without fee is hereby granted, provided that the above
  12 .\" copyright notice and this permission notice appear in all copies.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  15 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  16 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  17 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  18 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  19 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  20 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21 .\"
  22 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
  23 .\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
  24 .\"
  25 .\" Redistribution and use in source and binary forms, with or without
  26 .\" modification, are permitted provided that the following conditions
  27 .\" are met:
  28 .\"
  29 .\" 1. Redistributions of source code must retain the above copyright
  30 .\"    notice, this list of conditions and the following disclaimer.
  31 .\"
  32 .\" 2. Redistributions in binary form must reproduce the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer in
  34 .\"    the documentation and/or other materials provided with the
  35 .\"    distribution.
  36 .\"
  37 .\" 3. All advertising materials mentioning features or use of this
  38 .\"    software must display the following acknowledgment:
  39 .\"    "This product includes software developed by the OpenSSL Project
  40 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  41 .\"
  42 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  43 .\"    endorse or promote products derived from this software without
  44 .\"    prior written permission. For written permission, please contact
  45 .\"    openssl-core@openssl.org.
  46 .\"
  47 .\" 5. Products derived from this software may not be called "OpenSSL"
  48 .\"    nor may "OpenSSL" appear in their names without prior written
  49 .\"    permission of the OpenSSL Project.
  50 .\"
  51 .\" 6. Redistributions of any form whatsoever must retain the following
  52 .\"    acknowledgment:
  53 .\"    "This product includes software developed by the OpenSSL Project
  54 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  55 .\"
  56 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  57 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  58 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  59 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  60 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  61 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  62 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  63 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  64 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  65 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  66 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  67 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  68 .\"
  69 .Dd $Mdocdate: March 27 2018 $
  70 .Dt X509_REVOKED_NEW 3
  71 .Os
  72 .Sh NAME
  73 .Nm X509_REVOKED_new ,
  74 .Nm X509_REVOKED_dup ,
  75 .Nm X509_REVOKED_free ,
  76 .Nm X509_REVOKED_get0_serialNumber ,
  77 .Nm X509_REVOKED_get0_revocationDate ,
  78 .Nm X509_REVOKED_set_serialNumber ,
  79 .Nm X509_REVOKED_set_revocationDate
  80 .Nd create, change, and inspect an X.509 CRL revoked entry
  81 .Sh SYNOPSIS
  82 .In openssl/x509.h
  83 .Ft X509_REVOKED *
  84 .Fn X509_REVOKED_new void
  85 .Ft X509_REVOKED *
  86 .Fo X509_REVOKED_dup
  87 .Fa "X509_REVOKED *r"
  88 .Fc
  89 .Ft void
  90 .Fn X509_REVOKED_free "X509_REVOKED *r"
  91 .Ft const ASN1_INTEGER *
  92 .Fo X509_REVOKED_get0_serialNumber
  93 .Fa "const X509_REVOKED *r"
  94 .Fc
  95 .Ft const ASN1_TIME *
  96 .Fo X509_REVOKED_get0_revocationDate
  97 .Fa "const X509_REVOKED *r"
  98 .Fc
  99 .Ft int
 100 .Fo X509_REVOKED_set_serialNumber
 101 .Fa "X509_REVOKED *r"
 102 .Fa "ASN1_INTEGER *serial"
 103 .Fc
 104 .Ft int
 105 .Fo X509_REVOKED_set_revocationDate
 106 .Fa "X509_REVOKED *r"
 107 .Fa "ASN1_TIME *tm"
 108 .Fc
 109 .Sh DESCRIPTION
 110 .Fn X509_REVOKED_new
 111 allocates and initializes an empty
 112 .Vt X509_REVOKED
 113 object, representing one of the elements of
 114 the revokedCertificates field of the ASN.1
 115 .Vt TBSCertList
 116 structure defined in RFC 5280 section 5.1.
 117 It is used by
 118 .Vt X509_CRL
 119 objects and can hold information about one revoked certificate
 120 including issuer names, serial number, revocation date, and revocation
 121 reason.
 122 .Pp
 123 .Fn X509_REVOKED_dup
 124 creates a deep copy of
 125 .Fa r .
 126 .Pp
 127 .Fn X509_REVOKED_free
 128 frees
 129 .Fa r .
 130 .Pp
 131 .Fn X509_REVOKED_set_serialNumber
 132 sets the serial number of
 133 .Fa r
 134 to
 135 .Fa serial .
 136 The supplied
 137 .Fa serial
 138 pointer is not used internally so it should be freed up after use.
 139 .Pp
 140 .Fn X509_REVOKED_set_revocationDate
 141 sets the revocation date of
 142 .Fa r
 143 to
 144 .Fa tm .
 145 The supplied
 146 .Fa tm
 147 pointer is not used internally so it should be freed up after use.
 148 .Sh RETURN VALUES
 149 .Fn X509_REVOKED_new
 150 and
 151 .Fn X509_REVOKED_dup
 152 return the new
 153 .Vt X509_REVOKED
 154 object or
 155 .Dv NULL
 156 if an error occurs.
 157 .Pp
 158 .Fn X509_REVOKED_get0_serialNumber
 159 returns an internal pointer to the serial number of
 160 .Fa r .
 161 .Pp
 162 .Fn X509_REVOKED_get0_revocationDate
 163 returns an internal pointer to the revocation date of
 164 .Fa r .
 165 .Pp
 166 .Fn X509_REVOKED_set_serialNumber
 167 and
 168 .Fn X509_REVOKED_set_revocationDate
 169 return 1 for success or 0 for failure.
 170 .Sh SEE ALSO
 171 .Xr d2i_X509_CRL 3 ,
 172 .Xr ERR_get_error 3 ,
 173 .Xr PEM_read_X509_CRL 3 ,
 174 .Xr X509_CRL_get0_by_serial 3 ,
 175 .Xr X509_EXTENSION_new 3 ,
 176 .Xr X509_REVOKED_get_ext 3 ,
 177 .Xr X509_REVOKED_get_ext_d2i 3
 178 .Sh STANDARDS
 179 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 180 Certificate Revocation List (CRL) Profile, section 5.1: CRL Fields
 181 .Sh HISTORY
 182 .Fn X509_REVOKED_new
 183 and
 184 .Fn X509_REVOKED_free
 185 first appeared in SSLeay 0.4.4 and have been available since
 186 .Ox 2.4 .
 187 .Pp
 188 .Fn X509_REVOKED_set_serialNumber
 189 and
 190 .Fn X509_REVOKED_set_revocationDate
 191 first appeared in OpenSSL 0.9.7 and have been available since
 192 .Ox 3.2 .
 193 .Pp
 194 .Fn X509_REVOKED_dup
 195 first appeared in OpenSSL 1.0.2.
 196 .Fn X509_REVOKED_get0_serialNumber
 197 and
 198 .Fn X509_REVOKED_get0_revocationDate
 199 first appeared in OpenSSL 1.1.0.
 200 These functions have been available since
 201 .Ox 6.3 .