1.\" $OpenBSD: X509_add1_trust_object.3,v 1.4 2024/09/02 08:04:32 tb Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 2 2024 $ 18.Dt X509_ADD1_TRUST_OBJECT 3 19.Os 20.Sh NAME 21.Nm X509_add1_trust_object , 22.Nm X509_trust_clear , 23.Nm X509_add1_reject_object , 24.Nm X509_reject_clear 25.Nd mark an X.509 certificate as intended for a specific purpose 26.Sh SYNOPSIS 27.In openssl/x509.h 28.Ft int 29.Fo X509_add1_trust_object 30.Fa "X509 *x" 31.Fa "const ASN1_OBJECT *purpose" 32.Fc 33.Ft void 34.Fo X509_trust_clear 35.Fa "X509 *x" 36.Fc 37.Ft int 38.Fo X509_add1_reject_object 39.Fa "X509 *x" 40.Fa "const ASN1_OBJECT *purpose" 41.Fc 42.Ft void 43.Fo X509_reject_clear 44.Fa "X509 *x" 45.Fc 46.Sh DESCRIPTION 47.Fn X509_add1_trust_object 48appends a deep copy of the 49.Fa purpose 50object to the set of intended purposes that 51.Fa x 52contains as non-standard auxiliary data. 53The function 54.Xr OBJ_nid2obj 3 55can be used to create appropriate purpose objects from the 56.Dv NID_* 57constants mentioned in 58.Xr X509_check_purpose 3 , 59even though the 60.Dv X509_PURPOSE_* 61constants listed in that manual page are not intended for use with 62.Fn X509_add1_trust_object . 63.Pp 64.Fn X509_trust_clear 65frees and removes all purpose objects from the set of intended 66purposes in the non-standard auxiliary data of 67.Fa x . 68.Pp 69.Fn X509_add1_reject_object 70and 71.Fn X509_reject_clear 72are similar except that they operate on a set of unintended purposes. 73.Pp 74As an alternative to using the functions documented in the present 75manual page, X.509 certificate extensions can be used. 76At the price of higher complexity, those allow storing the purpose 77inside the certificate itself in a standard-conforming way rather than 78merely in non-standard auxiliary data associated with the certificate. 79See 80.Xr EXTENDED_KEY_USAGE_new 3 81for details. 82.Sh RETURN VALUES 83.Fn X509_add1_trust_object 84and 85.Fn X509_add1_reject_object 86return the new number of purposes in the respective set 87or 0 if an error occurs, in particular if memory 88allocation fails or if 89.Fa x 90does not contain a sub-object that can hold non-standard auxiliary data. 91.Sh SEE ALSO 92.Xr ASN1_OBJECT_new 3 , 93.Xr EXTENDED_KEY_USAGE_new 3 , 94.Xr OBJ_nid2obj 3 , 95.Xr X509_CERT_AUX_new 3 , 96.Xr X509_new 3 97.Sh HISTORY 98These functions first appeared in OpenSSL 0.9.4 and have been available since 99.Ox 2.7 . 100