lib/libcrypto/man/X509_ALGOR_dup.3

   1 .\"     $OpenBSD: X509_ALGOR_dup.3,v 1.5 2016/12/25 22:15:10 schwarze Exp $
   2 .\"     OpenSSL 4692340e Jun 7 15:49:08 2016 -0400
   3 .\"
   4 .\" This file is a derived work.
   5 .\" The changes are covered by the following Copyright and license:
   6 .\"
   7 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
  22 .\" Copyright (c) 2002, 2015 The OpenSSL Project.  All rights reserved.
  23 .\"
  24 .\" Redistribution and use in source and binary forms, with or without
  25 .\" modification, are permitted provided that the following conditions
  26 .\" are met:
  27 .\"
  28 .\" 1. Redistributions of source code must retain the above copyright
  29 .\"    notice, this list of conditions and the following disclaimer.
  30 .\"
  31 .\" 2. Redistributions in binary form must reproduce the above copyright
  32 .\"    notice, this list of conditions and the following disclaimer in
  33 .\"    the documentation and/or other materials provided with the
  34 .\"    distribution.
  35 .\"
  36 .\" 3. All advertising materials mentioning features or use of this
  37 .\"    software must display the following acknowledgment:
  38 .\"    "This product includes software developed by the OpenSSL Project
  39 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  40 .\"
  41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  42 .\"    endorse or promote products derived from this software without
  43 .\"    prior written permission. For written permission, please contact
  44 .\"    openssl-core@openssl.org.
  45 .\"
  46 .\" 5. Products derived from this software may not be called "OpenSSL"
  47 .\"    nor may "OpenSSL" appear in their names without prior written
  48 .\"    permission of the OpenSSL Project.
  49 .\"
  50 .\" 6. Redistributions of any form whatsoever must retain the following
  51 .\"    acknowledgment:
  52 .\"    "This product includes software developed by the OpenSSL Project
  53 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  54 .\"
  55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  58 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  67 .\"
  68 .Dd $Mdocdate: December 25 2016 $
  69 .Dt X509_ALGOR_DUP 3
  70 .Os
  71 .Sh NAME
  72 .Nm X509_ALGOR_new ,
  73 .Nm X509_ALGOR_free ,
  74 .Nm X509_ALGOR_dup ,
  75 .Nm X509_ALGOR_set0 ,
  76 .Nm X509_ALGOR_get0 ,
  77 .Nm X509_ALGOR_set_md ,
  78 .Nm X509_ALGOR_cmp
  79 .Nd create, change, and inspect algorithm identifiers
  80 .Sh SYNOPSIS
  81 .In openssl/x509.h
  82 .Ft X509_ALGOR *
  83 .Fn X509_ALGOR_new void
  84 .Ft void
  85 .Fn X509_ALGOR_free "X509_ALGOR *alg"
  86 .Ft X509_ALGOR *
  87 .Fo X509_ALGOR_dup
  88 .Fa "X509_ALGOR *alg"
  89 .Fc
  90 .Ft int
  91 .Fo X509_ALGOR_set0
  92 .Fa "X509_ALGOR *alg"
  93 .Fa "ASN1_OBJECT *aobj"
  94 .Fa "int ptype"
  95 .Fa "void *pval"
  96 .Fc
  97 .Ft void
  98 .Fo X509_ALGOR_get0
  99 .Fa "ASN1_OBJECT **paobj"
 100 .Fa "int *pptype"
 101 .Fa "const void **ppval"
 102 .Fa "const X509_ALGOR *alg"
 103 .Fc
 104 .Ft void
 105 .Fo X509_ALGOR_set_md
 106 .Fa "X509_ALGOR *alg"
 107 .Fa "const EVP_MD *md"
 108 .Fc
 109 .Ft int
 110 .Fo X509_ALGOR_cmp
 111 .Fa "const X509_ALGOR *a"
 112 .Fa "const X509_ALGOR *b"
 113 .Fc
 114 .Sh DESCRIPTION
 115 .Fn X509_ALGOR_new
 116 allocates and initializes an empty
 117 .Vt X509_ALGOR
 118 object, representing an ASN.1
 119 .Vt AlgorithmIdentifier
 120 structure defined in RFC 5280 section 4.1.1.2.
 121 Such objects can specify a cryptographic algorithm together
 122 with algorithm-specific parameters.
 123 They are used by many other objects, for example certificates,
 124 certificate revocation lists, and certificate requests.
 125 .Pp
 126 .Fn X509_ALGOR_free
 127 frees
 128 .Fa alg .
 129 .Pp
 130 .Fn X509_ALGOR_dup
 131 copies
 132 .Fa alg
 133 by calling
 134 .Xr i2d_X509_ALGOR 3
 135 and
 136 .Xr d2i_X509_ALGOR 3 .
 137 .Pp
 138 .Fn X509_ALGOR_set0
 139 sets the algorithm OID of
 140 .Fa alg
 141 to
 142 .Fa aobj
 143 and the associated parameter type to
 144 .Fa ptype
 145 with value
 146 .Fa pval .
 147 If
 148 .Fa ptype
 149 is
 150 .Dv V_ASN1_UNDEF
 151 the parameter is omitted, otherwise
 152 .Fa ptype
 153 and
 154 .Fa pval
 155 have the same meaning as the
 156 .Fa type
 157 and
 158 .Fa value
 159 parameters to
 160 .Xr ASN1_TYPE_set 3 .
 161 All the supplied parameters are used internally so must
 162 .Sy NOT
 163 be freed after this call.
 164 .Pp
 165 .Fn X509_ALGOR_get0
 166 is the inverse of
 167 .Fn X509_ALGOR_set0 :
 168 it returns the algorithm OID in
 169 .Pf * Fa paobj
 170 and the associated parameter in
 171 .Pf * Fa pptype
 172 and
 173 .Pf * Fa ppval
 174 from
 175 .Fa alg .
 176 .Pp
 177 .Fn X509_ALGOR_set_md
 178 sets
 179 .Fa alg
 180 to appropriate values for the message digest
 181 .Fa md .
 182 .Pp
 183 .Fn X509_ALGOR_cmp
 184 compares
 185 .Fa a
 186 and
 187 .Fa b .
 188 .Sh RETURN VALUES
 189 .Fn X509_ALGOR_new
 190 and
 191 .Fn X509_ALGOR_dup
 192 return a new
 193 .Vt X509_ALGOR
 194 object or
 195 .Dv NULL
 196 if an error occurs.
 197 .Pp
 198 .Fn X509_ALGOR_set0
 199 returns 1 for success or 0 for failure.
 200 .Pp
 201 .Fn X509_ALGOR_cmp
 202 returns 0 if
 203 .Fa a
 204 and
 205 .Fa b
 206 have identical encodings or non-zero otherwise.
 207 .Sh SEE ALSO
 208 .Xr ASN1_TYPE_set 3 ,
 209 .Xr d2i_X509_ALGOR 3 ,
 210 .Xr X509_PUBKEY_get0_param 3
 211 .Sh STANDARDS
 212 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 213 Certificate Revocation List (CRL) Profile