lib/libcrypto/man/DSA_SIG_new.3

   1 .\" $OpenBSD: DSA_SIG_new.3,v 1.7 2018/03/23 23:18:17 schwarze Exp $
   2 .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
   5 .\" Dr. Stephen Henson <steve@openssl.org>, and
   6 .\" TJ Saunders <tj@castaglia.org>.
   7 .\" Copyright (c) 2000, 2016 The OpenSSL Project.  All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\"
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\"
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in
  18 .\"    the documentation and/or other materials provided with the
  19 .\"    distribution.
  20 .\"
  21 .\" 3. All advertising materials mentioning features or use of this
  22 .\"    software must display the following acknowledgment:
  23 .\"    "This product includes software developed by the OpenSSL Project
  24 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  25 .\"
  26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  27 .\"    endorse or promote products derived from this software without
  28 .\"    prior written permission. For written permission, please contact
  29 .\"    openssl-core@openssl.org.
  30 .\"
  31 .\" 5. Products derived from this software may not be called "OpenSSL"
  32 .\"    nor may "OpenSSL" appear in their names without prior written
  33 .\"    permission of the OpenSSL Project.
  34 .\"
  35 .\" 6. Redistributions of any form whatsoever must retain the following
  36 .\"    acknowledgment:
  37 .\"    "This product includes software developed by the OpenSSL Project
  38 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  52 .\"
  53 .Dd $Mdocdate: March 23 2018 $
  54 .Dt DSA_SIG_NEW 3
  55 .Os
  56 .Sh NAME
  57 .Nm DSA_SIG_new ,
  58 .Nm DSA_SIG_free ,
  59 .Nm DSA_SIG_get0 ,
  60 .Nm DSA_SIG_set0
  61 .Nd manipulate DSA signature objects
  62 .Sh SYNOPSIS
  63 .In openssl/dsa.h
  64 .Ft DSA_SIG *
  65 .Fn DSA_SIG_new void
  66 .Ft void
  67 .Fo DSA_SIG_free
  68 .Fa "DSA_SIG *sig"
  69 .Fc
  70 .Ft void
  71 .Fo DSA_SIG_get0
  72 .Fa "const DSA_SIG *sig"
  73 .Fa "const BIGNUM **r"
  74 .Fa "const BIGNUM **s"
  75 .Fc
  76 .Ft int
  77 .Fo DSA_SIG_set0
  78 .Fa "DSA_SIG *sig"
  79 .Fa "BIGNUM *r"
  80 .Fa "BIGNUM *s"
  81 .Fc
  82 .Sh DESCRIPTION
  83 .Fn DSA_SIG_new
  84 allocates an empty
  85 .Vt DSA_SIG
  86 structure.
  87 .Pp
  88 .Fn DSA_SIG_free
  89 frees the
  90 .Vt DSA_SIG
  91 structure and its components.
  92 The values are erased before the memory is returned to the system.
  93 If
  94 .Fa sig
  95 is a
  96 .Dv NULL
  97 pointer, no action occurs.
  98 .Pp
  99 .Fn DSA_SIG_get0
 100 retrieves internal pointers to the
 101 .Fa r
 102 and
 103 .Fa s
 104 values contained in
 105 .Fa sig .
 106 .Pp
 107 The
 108 .Fa r
 109 and
 110 .Fa s
 111 values can be set by calling
 112 .Fn DSA_SIG_set0 .
 113 Calling this function transfers the memory management of the values to
 114 .Fa sig ,
 115 and therefore they should not be freed by the caller.
 116 .Sh RETURN VALUES
 117 If the allocation fails,
 118 .Fn DSA_SIG_new
 119 returns
 120 .Dv NULL
 121 and sets an error code that can be obtained by
 122 .Xr ERR_get_error 3 .
 123 Otherwise it returns a pointer to the newly allocated structure.
 124 .Pp
 125 .Fn DSA_SIG_set0
 126 returns 1 on success or 0 on failure.
 127 .Sh SEE ALSO
 128 .Xr DSA_do_sign 3 ,
 129 .Xr DSA_new 3 ,
 130 .Xr ERR_get_error 3
 131 .Sh HISTORY
 132 .Fn DSA_SIG_new
 133 and
 134 .Fn DSA_SIG_free
 135 first appeared in OpenSSL 0.9.3 and have been available since
 136 .Ox 2.6 .
 137 .Pp
 138 .Fn DSA_SIG_get0
 139 and
 140 .Fn DSA_SIG_set0
 141 first appeared in OpenSSL 1.1.0 and have been available since
 142 .Ox 6.3 .