new manual page X509_PURPOSE_set(3) documenting 11 functions

related to X509_PURPOSE objects, purpose identifiers, and purpose indices

4 files changed, 303 insertions, 5 deletions

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 <bsd.own.mk>
 
@@ -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 <schwarze@openbsd.org>
+.\"
+.\" 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 <schwarze@openbsd.org>
 .\"
 .\" 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 ,