From 95c37c6aa06e6ca31d39a5a96c5f2dcbbcbac35a Mon Sep 17 00:00:00 2001 From: schwarze Date: Thu, 8 Jul 2021 12:30:27 +0000 Subject: [PATCH] add new manual page for X509_add1_trust_object(3) and X509_trust_clear(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_CINF_new.3 | 5 +- lib/libcrypto/man/X509_add1_trust_object.3 | 82 ++++++++++++++++++++++ 3 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/X509_add1_trust_object.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 974fd918f3a..ff7fc4fd95a 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.173 2021/07/06 16:05:44 schwarze Exp $ +# $OpenBSD: Makefile,v 1.174 2021/07/08 12:30:27 schwarze Exp $ .include @@ -299,6 +299,7 @@ MAN= \ X509_STORE_set_verify_cb_func.3 \ X509_STORE_set1_param.3 \ X509_VERIFY_PARAM_set_flags.3 \ + X509_add1_trust_object.3 \ X509_check_ca.3 \ X509_check_host.3 \ X509_check_issued.3 \ diff --git a/lib/libcrypto/man/X509_CINF_new.3 b/lib/libcrypto/man/X509_CINF_new.3 index 4a0e24dfa2c..52d5acef6e0 100644 --- a/lib/libcrypto/man/X509_CINF_new.3 +++ b/lib/libcrypto/man/X509_CINF_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_CINF_new.3,v 1.6 2019/06/06 01:06:59 schwarze Exp $ +.\" $OpenBSD: X509_CINF_new.3,v 1.7 2021/07/08 12:30:27 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -14,7 +14,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 6 2019 $ +.Dd $Mdocdate: July 8 2021 $ .Dt X509_CINF_NEW 3 .Os .Sh NAME @@ -94,6 +94,7 @@ object, respectively, or if an error occurs. .Sh SEE ALSO .Xr d2i_X509_CINF 3 , +.Xr X509_add1_trust_object 3 , .Xr X509_new 3 .Sh STANDARDS RFC 5280: Internet X.509 Public Key Infrastructure Certificate and diff --git a/lib/libcrypto/man/X509_add1_trust_object.3 b/lib/libcrypto/man/X509_add1_trust_object.3 new file mode 100644 index 00000000000..ed21a6da377 --- /dev/null +++ b/lib/libcrypto/man/X509_add1_trust_object.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: X509_add1_trust_object.3,v 1.1 2021/07/08 12:30:27 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 8 2021 $ +.Dt X509_ADD1_TRUST_OBJECT 3 +.Os +.Sh NAME +.Nm X509_add1_trust_object , +.Nm X509_trust_clear +.Nd mark an X.509 certificate as intended for a specific purpose +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_add1_trust_object +.Fa "X509 *x" +.Fa "const ASN1_OBJECT *purpose" +.Fc +.Ft void +.Fo X509_trust_clear +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +.Fn X509_add1_trust_object +appends a deep copy of the +.Fa purpose +object to the set of intended purposes that +.Fa x +contains as non-standard auxiliary data. +The function +.Xr OBJ_nid2obj 3 +can be used to create appropriate purpose objects from the +.Dv NID_* +constants mentioned in +.Xr X509_check_purpose 3 , +even though the +.Dv X509_PURPOSE_* +constants listed in that manual page are not intended for use with +.Fn X509_add1_trust_object . +.Pp +.Fn X509_trust_clear +frees and removes all purpose objects +contained in the non-standard auxiliary data of +.Fa x . +.Pp +As an alternative to using the functions documented in the present +manual page, X.509 certificate extensions can be used. +At the price of higher complexity, those allow storing the purpose +inside the certificate itself in a standard-conforming way rather than +merely in non-standard auxiliary data associated with the certificate. +See +.Xr EXTENDED_KEY_USAGE_new 3 +for details. +.Sh RETURN VALUES +.Fn X509_add1_trust_object +returns the new number of purposes that +.Fa x +is intended for, or 0 if an error occurs, in particular if memory +allocation fails or if +.Fa x +does not contain a sub-object that can hold non-standard auxiliary data. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.7 . -- 2.20.1