1.\" $OpenBSD: DSA_meth_new.3,v 1.3 2022/07/10 13:41:59 schwarze Exp $ 2.\" selective merge up to: OpenSSL c4d3c19b Apr 3 13:57:12 2018 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2018, 2022 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 Matt Caswell <matt@openssl.org>. 22.\" Copyright (c) 2016 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: July 10 2022 $ 69.Dt DSA_METH_NEW 3 70.Os 71.Sh NAME 72.Nm DSA_meth_new , 73.Nm DSA_meth_free , 74.Nm DSA_meth_dup , 75.Nm DSA_meth_get0_name , 76.Nm DSA_meth_set1_name , 77.Nm DSA_meth_set_sign , 78.Nm DSA_meth_set_finish 79.Nd build up DSA methods 80.Sh SYNOPSIS 81.In openssl/dsa.h 82.Ft DSA_METHOD * 83.Fo DSA_meth_new 84.Fa "const char *name" 85.Fa "int flags" 86.Fc 87.Ft void 88.Fo DSA_meth_free 89.Fa "DSA_METHOD *meth" 90.Fc 91.Ft DSA_METHOD * 92.Fo DSA_meth_dup 93.Fa "const DSA_METHOD *meth" 94.Fc 95.Ft const char * 96.Fo DSA_meth_get0_name 97.Fa "const DSA_METHOD *meth" 98.Fc 99.Ft int 100.Fo DSA_meth_set1_name 101.Fa "DSA_METHOD *meth" 102.Fa "const char *name" 103.Fc 104.Ft int 105.Fo DSA_meth_set_sign 106.Fa "DSA_METHOD *meth" 107.Fa "DSA_SIG *(*sign)(const unsigned char *, int, DSA *)" 108.Fc 109.Ft int 110.Fo DSA_meth_set_finish 111.Fa "DSA_METHOD *meth" 112.Fa "int (*finish)(DSA *)" 113.Fc 114.Sh DESCRIPTION 115The 116.Vt DSA_METHOD 117structure holds function pointers for custom DSA implementations. 118.Pp 119.Fn DSA_meth_new 120creates a new 121.Vt DSA_METHOD 122structure. 123A copy of the NUL-terminated 124.Fa name 125is stored in the new 126.Vt DSA_METHOD 127object. 128Any new 129.Vt DSA 130object constructed from this 131.Vt DSA_METHOD 132will have the given 133.Fa flags 134set by default. 135.Pp 136.Fn DSA_meth_dup 137creates a deep copy of 138.Fa meth . 139This might be useful for creating a new 140.Vt DSA_METHOD 141based on an existing one, but with some differences. 142.Pp 143.Fn DSA_meth_free 144destroys 145.Fa meth 146and frees any memory associated with it. 147.Pp 148.Fn DSA_meth_get0_name 149returns an internal pointer to the name of 150.Fa meth . 151.Fn DSA_meth_set1_name 152stores a copy of the NUL-terminated 153.Fa name 154in 155.Fa meth 156after freeing the previously stored name. 157Method names are ignored by the default DSA implementation but can be 158used by alternative implementations and by the application program. 159.Pp 160.Fn DSA_meth_set_sign 161sets the function used for creating a DSA signature. 162This function will be called from 163.Xr DSA_do_sign 3 164and indirectly from 165.Xr DSA_sign 3 . 166The parameters of 167.Fa sign 168have the same meaning as for 169.Xr DSA_do_sign 3 . 170.Pp 171.Fn DSA_meth_set_finish 172sets an optional function for destroying a 173.Vt DSA 174object. 175Unless 176.Fa finish 177is 178.Dv NULL , 179it will be called from 180.Xr DSA_free 3 . 181It takes the same argument 182and is intended to do DSA implementation specific cleanup. 183The memory used by the 184.Vt DSA 185object itself should not be freed by the 186.Fa finish 187function. 188.Sh RETURN VALUES 189.Fn DSA_meth_new 190and 191.Fn DSA_meth_dup 192return the newly allocated 193.Vt DSA_METHOD 194object or 195.Dv NULL 196on failure. 197.Pp 198.Fn DSA_meth_get0_name 199returns an internal pointer which must not be freed by the caller. 200.Pp 201.Fn DSA_meth_set1_name 202and all 203.Fn DSA_meth_set_* 204functions return 1 on success or 0 on failure. 205In the current implementation, only 206.Fn DSA_meth_set1_name 207can actually fail. 208.Sh SEE ALSO 209.Xr DSA_do_sign 3 , 210.Xr DSA_new 3 , 211.Xr DSA_set_method 3 , 212.Xr DSA_SIG_new 3 , 213.Xr DSA_sign 3 214.Sh HISTORY 215These functions first appeared in OpenSSL 1.1.0. 216.Pp 217.Fn DSA_meth_new , 218.Fn DSA_meth_free , 219.Fn DSA_meth_dup , 220.Fn DSA_meth_set_sign , 221and 222.Fn DSA_meth_set_finish 223have been available since 224.Ox 6.3 . 225.Pp 226.Fn DSA_meth_get0_name 227and 228.Fn DSA_meth_set1_name 229have been available since 230.Ox 7.2 . 231