lib/libcrypto/man/DSA_get0_pqg.3

   1 .\" $OpenBSD: DSA_get0_pqg.3,v 1.4 2018/03/23 23:18:17 schwarze Exp $
   2 .\" full merge up to: OpenSSL e90fc053 Jul 15 09:39:45 2017 -0400
   3 .\"
   4 .\" This file was written by Matt Caswell <matt@openssl.org>.
   5 .\" Copyright (c) 2016 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 23 2018 $
  52 .Dt DSA_GET0_PQG 3
  53 .Os
  54 .Sh NAME
  55 .Nm DSA_get0_pqg ,
  56 .Nm DSA_set0_pqg ,
  57 .Nm DSA_get0_key ,
  58 .Nm DSA_set0_key ,
  59 .Nm DSA_clear_flags ,
  60 .Nm DSA_test_flags ,
  61 .Nm DSA_set_flags ,
  62 .Nm DSA_get0_engine
  63 .Nd get data from and set data in a DSA object
  64 .Sh SYNOPSIS
  65 .In openssl/dsa.h
  66 .Ft void
  67 .Fo DSA_get0_pqg
  68 .Fa "const DSA *d"
  69 .Fa "const BIGNUM **p"
  70 .Fa "const BIGNUM **q"
  71 .Fa "const BIGNUM **g"
  72 .Fc
  73 .Ft int
  74 .Fo DSA_set0_pqg
  75 .Fa "DSA *d"
  76 .Fa "BIGNUM *p"
  77 .Fa "BIGNUM *q"
  78 .Fa "BIGNUM *g"
  79 .Fc
  80 .Ft void
  81 .Fo DSA_get0_key
  82 .Fa "const DSA *d"
  83 .Fa "const BIGNUM **pub_key"
  84 .Fa "const BIGNUM **priv_key"
  85 .Fc
  86 .Ft int
  87 .Fo DSA_set0_key
  88 .Fa "DSA *d"
  89 .Fa "BIGNUM *pub_key"
  90 .Fa "BIGNUM *priv_key"
  91 .Fc
  92 .Ft void
  93 .Fo DSA_clear_flags
  94 .Fa "DSA *d"
  95 .Fa "int flags"
  96 .Fc
  97 .Ft int
  98 .Fo DSA_test_flags
  99 .Fa "const DSA *d"
 100 .Fa "int flags"
 101 .Fc
 102 .Ft void
 103 .Fo DSA_set_flags
 104 .Fa "DSA *d"
 105 .Fa "int flags"
 106 .Fc
 107 .Ft ENGINE *
 108 .Fo DSA_get0_engine
 109 .Fa "DSA *d"
 110 .Fc
 111 .Sh DESCRIPTION
 112 A
 113 .Vt DSA
 114 object contains the parameters
 115 .Fa p ,
 116 .Fa q ,
 117 and
 118 .Fa g .
 119 It also contains a public key
 120 .Fa pub_key
 121 and an optional private key
 122 .Fa priv_key .
 123 .Pp
 124 The
 125 .Fa p ,
 126 .Fa q ,
 127 and
 128 .Fa g
 129 parameters can be obtained by calling
 130 .Fn DSA_get0_pqg .
 131 If the parameters have not yet been set, then
 132 .Pf * Fa p ,
 133 .Pf * Fa q ,
 134 and
 135 .Pf * Fa g
 136 are set to
 137 .Dv NULL .
 138 Otherwise, they are set to pointers to the internal representations
 139 of the values that should not be freed by the application.
 140 .Pp
 141 The
 142 .Fa p ,
 143 .Fa q ,
 144 and
 145 .Fa g
 146 values can be set by calling
 147 .Fn DSA_set0_pqg .
 148 Calling this function transfers the memory management of the values to
 149 .Fa d ,
 150 and therefore they should not be freed by the caller.
 151 .Pp
 152 The
 153 .Fn DSA_get0_key
 154 function stores pointers to the internal representations
 155 of the public key in
 156 .Pf * Fa pub_key
 157 and to the private key in
 158 .Pf * Fa priv_key .
 159 Either may be
 160 .Dv NULL
 161 if it has not yet been set.
 162 If the private key has been set, then the public key must be.
 163 .Pp
 164 The public and private key values can be set using
 165 .Fn DSA_set0_key .
 166 The public key must be
 167 .Pf non- Dv NULL
 168 the first time this function is called on a given
 169 .Vt DSA
 170 object.
 171 The private key may be
 172 .Dv NULL .
 173 On subsequent calls, either may be
 174 .Dv NULL ,
 175 which means the corresponding
 176 .Vt DSA
 177 field is left untouched.
 178 .Fn DSA_set0_key
 179 transfers the memory management of the key values to
 180 .Fa d ,
 181 and therefore they should not be freed by the caller.
 182 .Pp
 183 Values retrieved with
 184 .Fn DSA_get0_pqg
 185 and
 186 .Fn DSA_get0_key
 187 are owned by the
 188 .Vt DSA
 189 object and may therefore not be passed to
 190 .Fn DSA_set0_pqg
 191 or
 192 .Fn DSA_set0_key .
 193 If needed, duplicate the received values using
 194 .Xr BN_dup 3
 195 and pass the duplicates.
 196 .Pp
 197 .Fn DSA_clear_flags
 198 clears the specified
 199 .Fa flags
 200 in
 201 .Fa d .
 202 .Fn DSA_test_flags
 203 tests the
 204 .Fa flags
 205 in
 206 .Fa d .
 207 .Fn DSA_set_flags
 208 sets the
 209 .Fa flags
 210 in
 211 .Fa d ;
 212 any flags already set remain set.
 213 For all three functions, multiple flags can be passed in one call,
 214 OR'ed together bitwise.
 215 .Sh RETURN VALUES
 216 .Fn DSA_set0_pqg
 217 and
 218 .Fn DSA_set0_key
 219 return 1 on success or 0 on failure.
 220 .Pp
 221 .Fn DSA_test_flags
 222 returns those of the given
 223 .Fa flags
 224 currently set in
 225 .Fa d
 226 or 0 if none of the given
 227 .Fa flags
 228 are set.
 229 .Pp
 230 .Fn DSA_get0_engine
 231 returns a pointer to the
 232 .Vt ENGINE
 233 used by the
 234 .Vt DSA
 235 object
 236 Fa d ,
 237 or
 238 .Dv NULL
 239 if no engine was set for this object.
 240 .Sh SEE ALSO
 241 .Xr DSA_do_sign 3 ,
 242 .Xr DSA_dup_DH 3 ,
 243 .Xr DSA_generate_key 3 ,
 244 .Xr DSA_generate_parameters 3 ,
 245 .Xr DSA_new 3 ,
 246 .Xr DSA_print 3 ,
 247 .Xr DSA_sign 3 ,
 248 .Xr DSA_size 3
 249 .Sh HISTORY
 250 These functions first appeared in OpenSSL 1.1.0
 251 and have been available since
 252 .Ox 6.3 .