From: schwarze Date: Sun, 11 Feb 2018 20:59:30 +0000 (+0000) Subject: Document three more functions recently made public by jsing@ X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=471f033c317b40601f83e748cf82fe6fdb8bc770;p=openbsd Document three more functions recently made public by jsing@ as requested by jsing@, and also document six more related functions that have already been public before that. OpenSSL fails to document any of these. --- diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 index b459e758632..04f38c8ec57 100644 --- a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 +++ b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 @@ -1,8 +1,25 @@ -.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.6 2018/02/11 03:33:21 schwarze Exp $ +.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.7 2018/02/11 20:59:30 schwarze Exp $ .\" full merge up to: OpenSSL d33def66 Feb 9 14:17:13 2016 -0500 .\" selective merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 .\" -.\" This file was written by Dr. Stephen Henson +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Dr. Stephen Henson .\" and Viktor Dukhovni . .\" Copyright (c) 2009, 2013, 2014, 2015, 2016, 2017 The OpenSSL Project. .\" All rights reserved. @@ -55,6 +72,10 @@ .Dt X509_VERIFY_PARAM_SET_FLAGS 3 .Os .Sh NAME +.Nm X509_VERIFY_PARAM_new , +.Nm X509_VERIFY_PARAM_free , +.Nm X509_VERIFY_PARAM_get0_name , +.Nm X509_VERIFY_PARAM_set1_name , .Nm X509_VERIFY_PARAM_set_flags , .Nm X509_VERIFY_PARAM_clear_flags , .Nm X509_VERIFY_PARAM_get_flags , @@ -71,10 +92,32 @@ .Nm X509_VERIFY_PARAM_get0_peername , .Nm X509_VERIFY_PARAM_set1_email , .Nm X509_VERIFY_PARAM_set1_ip , -.Nm X509_VERIFY_PARAM_set1_ip_asc +.Nm X509_VERIFY_PARAM_set1_ip_asc , +.Nm X509_VERIFY_PARAM_add0_table , +.Nm X509_VERIFY_PARAM_lookup , +.Nm X509_VERIFY_PARAM_get_count , +.Nm X509_VERIFY_PARAM_get0 , +.Nm X509_VERIFY_PARAM_table_cleanup .Nd X509 verification parameters .Sh SYNOPSIS .In openssl/x509_vfy.h +.Ft X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_new +.Fa void +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_free +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft const char * +.Fo X509_VERIFY_PARAM_get0_name +.Fa "const X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_name +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *name" +.Fc .Ft int .Fo X509_VERIFY_PARAM_set_flags .Fa "X509_VERIFY_PARAM *param" @@ -161,14 +204,77 @@ .Fa "X509_VERIFY_PARAM *param" .Fa "const char *ipasc" .Fc +.Ft int +.Fo X509_VERIFY_PARAM_add0_table +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft const X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_lookup +.Fa "const char *name" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_get_count +.Fa void +.Fc +.Ft const X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_get0 +.Fa "int id" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_table_cleanup +.Fa void +.Fc .Sh DESCRIPTION -These functions manipulate the +These functions manipulate an .Vt X509_VERIFY_PARAM -structure associated with a certificate verification operation. +object associated with a certificate verification operation. +.Pp +.Fn X509_VERIFY_PARAM_new +allocates and initializes an empty +.Vt X509_VERIFY_PARAM +object. +.Pp +.Fn X509_VERIFY_PARAM_free +clears all data contained in +.Fa param +and releases all memory used by it. +If +.Fa param +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_VERIFY_PARAM_get0_name +returns the name of the given +.Fa param +object, usually describing its purpose, for example +.Qq default , +.Qq pkcs7 , +.Qq smime_sign , +.Qq ssl_client , +or +.Qq ssl_server . +For user-defined objects, the returned pointer may be +.Dv NULL +even if the object is otherwise valid. +.Pp +.Fn X509_VERIFY_PARAM_set1_name +sets the name of +.Fa param +to a copy of +.Fa name , +or to +.Dv NULL +if +.Fa name +is +.Dv NULL . +This function is quite dangerous because it invalidates pointers +previously returned from +.Fn X509_VERIFY_PARAM_get0_name . .Pp -The .Fn X509_VERIFY_PARAM_set_flags -function sets the flags in +sets the flags in .Fa param by OR'ing it with .Fa flags . @@ -283,11 +389,6 @@ When wildcard matching is not disabled, or when a reference identifier specifies a parent domain (starts with ".") rather than a hostname, the peer name may be a wildcard name or a sub-domain of the reference identifier respectively. -The return string is allocated by the library and is no longer valid -once the associated -.Fa param -argument is freed. -Applications must not free the return value. .Pp .Fn X509_VERIFY_PARAM_set1_email sets the expected RFC822 email address to @@ -324,7 +425,54 @@ The argument is a NUL-terminal ASCII string: dotted decimal quad for IPv4 and colon-separated hexadecimal for IPv6. The condensed "::" notation is supported for IPv6 addresses. +.Pp +.Fn X509_VERIFY_PARAM_add0_table +adds +.Fa param +to a static list of +.Vt X509_VERIFY_PARAM +objects maintained by the library. +This function is extremely dangerous because contrary to the name +of the function, if the list already contains an object that happens +to have the same name, that old object is not only silently removed +from the list, but also silently freed, which may silently invalidate +various pointers existing elsewhere in the program. +.Pp +.Fn X509_VERIFY_PARAM_lookup +searches this list for an object of the given +.Fa name . +If no match is found, the predefined objects built-in to the library +are also inspected. +.Pp +.Fn X509_VERIFY_PARAM_get_count +returns the sum of the number of objects on this list and the number +of predefined objects built-in to the library. +Note that this is not necessarily the total number of +.Vt X509_VERIFY_PARAM +objects existing in the program because there may be additional such +objects that were never added to the list. +.Pp +.Fn X509_VERIFY_PARAM_get0 +accesses predefined and user-defined objects using +.Fa id +as an index, useful for looping over objects without knowing their names. +An argument less than the number of predefined objects selects +one of the predefined objects; a higher argument selects an object +from the list. +.Pp +.Fn X509_VERIFY_PARAM_table_cleanup +deletes all objects from this list. +It is extremely dangerous because it also invalidates all data that +was contained in all objects that were on the list and because it +frees all these objects, which may invalidate various pointers +existing elsewhere in the program. .Sh RETURN VALUES +.Fn X509_VERIFY_PARAM_new +returns a pointer to the new object, or +.Dv NULL +on allocation failure. +.Pp +.Fn X509_VERIFY_PARAM_set1_name , .Fn X509_VERIFY_PARAM_set_flags , .Fn X509_VERIFY_PARAM_clear_flags , .Fn X509_VERIFY_PARAM_set_purpose , @@ -335,20 +483,39 @@ The condensed "::" notation is supported for IPv6 addresses. .Fn X509_VERIFY_PARAM_add1_host , .Fn X509_VERIFY_PARAM_set1_email , .Fn X509_VERIFY_PARAM_set1_ip , +.Fn X509_VERIFY_PARAM_set1_ip_asc , and -.Fn X509_VERIFY_PARAM_set1_ip_asc +.Fn X509_VERIFY_PARAM_add0_table return 1 for success or 0 for failure. .Pp .Fn X509_VERIFY_PARAM_get_flags returns the current verification flags. .Pp -.Fn X509_VERIFY_PARAM_set_time -and -.Fn X509_VERIFY_PARAM_set_depth -do not return values. -.Pp .Fn X509_VERIFY_PARAM_get_depth returns the current verification depth. +.Pp +.Fn X509_VERIFY_PARAM_get0_name +and +.Fn X509_VERIFY_PARAM_get0_peername +return pointers to strings that are only valid +during the lifetime of the given +.Fa param +object and that must not be freed by the application program. +.Pp +.Fn X509_VERIFY_PARAM_lookup +and +.Fn X509_VERIFY_PARAM_get0 +return a pointer to an existing built-in or user-defined object, or +.Dv NULL +if no object with the given +.Fa name +is found, or if +.Fa id +is at least +.Fn X509_VERIFY_PARAM_get_count . +.Pp +.Fn X509_VERIFY_PARAM_get_count +returns a number of objects. .Sh VERIFICATION FLAGS The verification flags consists of zero or more of the following flags OR'ed together.