From 26f0d6e6975de532ec5905b2c17ee75351354be2 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 23 Jul 2021 14:27:32 +0000 Subject: new manual page X509_PURPOSE_set(3) documenting 11 functions related to X509_PURPOSE objects, purpose identifiers, and purpose indices --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/X509_PURPOSE_set.3 | 295 +++++++++++++++++++++++++++++ src/lib/libcrypto/man/X509_check_purpose.3 | 5 +- src/lib/libcrypto/man/X509_new.3 | 5 +- 4 files changed, 303 insertions(+), 5 deletions(-) create mode 100644 src/lib/libcrypto/man/X509_PURPOSE_set.3 (limited to 'src') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index fd8655d5b6..300a37686a 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.184 2021/07/22 17:11:14 schwarze Exp $ +# $OpenBSD: Makefile,v 1.185 2021/07/23 14:27:32 schwarze Exp $ .include @@ -292,6 +292,7 @@ MAN= \ X509_NAME_print_ex.3 \ X509_OBJECT_get0_X509.3 \ X509_PUBKEY_new.3 \ + X509_PURPOSE_set.3 \ X509_REQ_new.3 \ X509_REVOKED_new.3 \ X509_SIG_new.3 \ diff --git a/src/lib/libcrypto/man/X509_PURPOSE_set.3 b/src/lib/libcrypto/man/X509_PURPOSE_set.3 new file mode 100644 index 0000000000..1f723e9b9f --- /dev/null +++ b/src/lib/libcrypto/man/X509_PURPOSE_set.3 @@ -0,0 +1,295 @@ +.\" $OpenBSD: X509_PURPOSE_set.3,v 1.1 2021/07/23 14:27:32 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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. +.\" +.Dd $Mdocdate: July 23 2021 $ +.Dt X509_PURPOSE_SET 3 +.Os +.Sh NAME +.Nm X509_PURPOSE_set , +.Nm X509_PURPOSE_get_by_id , +.Nm X509_PURPOSE_add , +.Nm X509_PURPOSE_get_count , +.Nm X509_PURPOSE_cleanup , +.Nm X509_PURPOSE_get0 , +.Nm X509_PURPOSE_get_by_sname , +.Nm X509_PURPOSE_get_id , +.Nm X509_PURPOSE_get0_name , +.Nm X509_PURPOSE_get0_sname , +.Nm X509_PURPOSE_get_trust +.Nd purpose objects, indices, and identifiers +.Sh SYNOPSIS +.In openssl/x509v3.h +.Ft int +.Fo X509_PURPOSE_set +.Fa "int *id_out" +.Fa "int id_in" +.Fc +.Ft int +.Fn X509_PURPOSE_get_by_id "int identifier" +.Ft int +.Fo X509_PURPOSE_add +.Fa "int identifier" +.Fa "int trust" +.Fa "int flags" +.Fa "int (*check_purpose)(const X509_PURPOSE *, const X509 *, int)" +.Fa "const char *name" +.Fa "const char *sname" +.Fa "void *usr_data" +.Fc +.Ft int +.Fn X509_PURPOSE_get_count void +.Ft void +.Fn X509_PURPOSE_cleanup void +.Ft X509_PURPOSE * +.Fn X509_PURPOSE_get0 "int index" +.Ft int +.Fn X509_PURPOSE_get_by_sname "const char *sname" +.Ft int +.Fn X509_PURPOSE_get_id "const X509_PURPOSE *object" +.Ft char * +.Fn X509_PURPOSE_get0_name "const X509_PURPOSE *object" +.Ft char * +.Fn X509_PURPOSE_get0_sname "const X509_PURPOSE *object" +.Ft int +.Fn X509_PURPOSE_get_trust "const X509_PURPOSE *object" +.Sh DESCRIPTION +The purposes that an X.509 certificate is intended to be used for +can be identified in three equivalent ways: +.Bl -enum +.It +By purpose identifiers, which are positive integer constants. +Standard purpose identifiers lie in the range from +.Dv X509_PURPOSE_MIN +to +.Dv X509_PURPOSE_MAX , +inclusive, and are listed in the +.Xr X509_check_purpose 3 +manual page. +User defined purpose identifiers are larger than +.Dv X509_PURPOSE_MAX . +.It +By purpose indices, which are non-negative integer constants +but differ from the purpose identifiers for the same purpose. +Standard purpose indices are smaller than +.Dv X509_PURPOSE_MAX . +User defined purpose indices are larger than or equal to +.Dv X509_PURPOSE_MAX . +.It +By purpose objects of the type +.Vt X509_PURPOSE . +Standard purpose objects are available in static storage. +User defined purpose objects can be created with +.Fn X509_PURPOSE_add . +.El +.Pp +Application programmers cannot choose the way to identify purposes +that they like best; depending on the circumstances, all three ways +are needed. +Be warned that the naming of most functions is misleading. +.Pp +Most API functions documented outside the present manual page +use purpose identifiers rather than purpose indices. +.Ss Using purpose identifiers +.Fn X509_PURPOSE_set +validates the purpose identifier +.Fa id_in . +If it is valid, it is copied to +.Pf * Fa id_out . +Otherwise, +.Pf * Fa id_out +remains unchanged. +.Pp +.Fn X509_PURPOSE_get_by_id +converts the purpose +.Fa identifier +to the corresponding purpose index. +To find the corresponding purpose object, pass the result to +.Fn X509_PURPOSE_get0 . +.Pp +.Fn X509_PURPOSE_add +defines a purpose with the given +.Fa identifier +or modifies its properties if it already exists. +The purpose +.Fa identifier , +the +.Fa trust +identifier, the +.Fa flags , +the +.Fa check_purpose +function, the +.Fa name , +the short name +.Fa sname , +and the +.Fa usr_data +pointer are copied into the +.Vt X509_PURPOSE +object. +When modifying an existing purpose object, previous values of fields are +overwritten and previous +.Fa name +and +.Fa sname +strings are freed if they were dynamically allocated. +When creating a new purpose object, +it is added to the global array of user-defined purpose objects. +.Pp +.Dv X509_PURPOSE_DYNAMIC +and +.Dv X509_PURPOSE_DYNAMIC_NAME +are always ignored in the +.Fa flags +argument. +.Dv X509_PURPOSE_DYNAMIC +is automatically set if the object was created by the user. +It is never set for standard objects, not even if they were +modified by the user. +.Dv X509_PURPOSE_DYNAMIC_NAME +is automatically set if the object was created or modified by the user. +It is only unset for unmodified standard objects. +The library does not appear to define any other flags, so the +.Fa flags +argument is probably useless unless users define their own flags +and use them in the +.Fa check_purpose +function. +.Pp +The third and final argument of the +.Fa check_purpose +function is the +.Fa ca +argument documented in +.Xr X509_check_purpose 3 . +.Pp +.Fn X509_PURPOSE_get_count +returns the total number of purposes currently defined, +including both standard and user-defined purposes. +If no user-defined purposes exist, the returned value is +.Dv X509_PURPOSE_MAX . +.Pp +.Fn X509_PURPOSE_cleanup +deletes all user-defined purpose objects +and invalidates their purpose identifiers and purpose indices. +If any of the standard purpose objects were modified by the user, +those changes are +.Em not +reverted. +.Ss Using purpose indices +.Fn X509_PURPOSE_get0 +converts the purpose +.Fa index +to a pointer to the corresponding purpose object. +To find the corresponding purpose identifier, pass the result to +.Fn X509_PURPOSE_get_id . +.Pp +.Fn X509_PURPOSE_get_by_sname +returns the lowest index of a purpose with the given short name. +.Ss Using purpose objects +.Fn X509_PURPOSE_get_id +converts a pointer to a purpose +.Fa object +to the corresponding purpose identifier. +To find the corresponding purpose index, pass the result to +.Fn X509_PURPOSE_get_by_id . +.Pp +.Fn X509_PURPOSE_get0_name , +.Fn X509_PURPOSE_get0_sname , +and +.Fn X509_PURPOSE_get_trust +retrieve the name, short name, and trust identifier from the +.Fa object , +respectively. +.Sh RETURN VALUES +.Fn X509_PURPOSE_set +returns 1 if +.Fa id_in +is valid or 0 otherwise. +.Pp +.Fn X509_PURPOSE_get_by_id +and +.Fn X509_PURPOSE_get_by_sname +return the corresponding purpose index +or \-1 if no matching purpose is found. +.Pp +.Fn X509_PURPOSE_add +returns 1 for success or 0 for failure. +.Pp +.Fn X509_PURPOSE_get_count +returns the total number of purposes currently defined. +.Pp +.Fn X509_PURPOSE_get0 +returns a standard or user-defined purpose object or +.Dv NULL +if the +.Fa index +is invalid. +.Pp +.Fn X509_PURPOSE_get_id +always returns a valid purpose identifier. +.Pp +.Fn X509_PURPOSE_get0_name +and +.Fn X509_PURPOSE_get0_sname +return pointers to storage owned by the +.Fa object . +.Pp +.Fn X509_PURPOSE_get_trust +returns the trust identifier associated with the +.Fa object . +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509V3_R_INVALID_PURPOSE Qq "invalid purpose" +.Fn X509_PURPOSE_set +was called with an invalid +.Fa id_in +argument. +.It Dv X509V3_R_INVALID_NULL_ARGUMENT Qq "invalid null argument" +.Fn X509_PURPOSE_add +was called with a +.Fa name +or +.Fa sname +argument of +.Dv NULL . +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +.Fn X509_PURPOSE_add +failed to allocate memory. +.El +.Pp +The other functions provide no diagnostics. +.Sh SEE ALSO +.Xr X509_check_purpose 3 , +.Xr X509_new 3 , +.Xr X509_STORE_set_purpose 3 , +.Xr X509_VERIFY_PARAM_set_purpose 3 +.Sh HISTORY +.Fn X509_PURPOSE_set +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +The other functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . +.Sh CAVEATS +The difference between purpose identifiers and purpose indices provides +an ideal breeding ground for off-by-one bugs. diff --git a/src/lib/libcrypto/man/X509_check_purpose.3 b/src/lib/libcrypto/man/X509_check_purpose.3 index 8e98a62239..935b7eed86 100644 --- a/src/lib/libcrypto/man/X509_check_purpose.3 +++ b/src/lib/libcrypto/man/X509_check_purpose.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_check_purpose.3,v 1.2 2021/06/12 17:04:41 jmc Exp $ +.\" $OpenBSD: X509_check_purpose.3,v 1.3 2021/07/23 14:27:32 schwarze Exp $ .\" Copyright (c) 2019 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,7 +13,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 12 2021 $ +.Dd $Mdocdate: July 23 2021 $ .Dt X509_CHECK_PURPOSE 3 .Os .Sh NAME @@ -370,6 +370,7 @@ can be used as a CA for the .Xr BASIC_CONSTRAINTS_new 3 , .Xr EXTENDED_KEY_USAGE_new 3 , .Xr X509_new 3 , +.Xr X509_PURPOSE_set 3 , .Xr X509V3_get_d2i 3 , .Xr x509v3.cnf 5 .Sh STANDARDS diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3 index 8a38cf5b72..ef99015ddb 100644 --- a/src/lib/libcrypto/man/X509_new.3 +++ b/src/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.24 2021/07/12 15:56:54 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.25 2021/07/23 14:27:32 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. @@ -66,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: July 12 2021 $ +.Dd $Mdocdate: July 23 2021 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -194,6 +194,7 @@ if an error occurs. .Xr X509_NAME_new 3 , .Xr X509_print_ex 3 , .Xr X509_PUBKEY_new 3 , +.Xr X509_PURPOSE_set 3 , .Xr X509_REQ_new 3 , .Xr X509_SIG_new 3 , .Xr X509_sign 3 , -- cgit v1.2.3-55-g6feb