1=pod 2 3=head1 NAME 4 5X509_check_purpose, 6X509_PURPOSE_get_count, 7X509_PURPOSE_get_unused_id, 8X509_PURPOSE_get_by_sname, 9X509_PURPOSE_get_by_id, 10X509_PURPOSE_add, 11X509_PURPOSE_cleanup, 12X509_PURPOSE_get0, 13X509_PURPOSE_get_id, 14X509_PURPOSE_get0_name, 15X509_PURPOSE_get0_sname, 16X509_PURPOSE_get_trust, 17X509_PURPOSE_set - functions related to checking the purpose of a certificate 18 19=head1 SYNOPSIS 20 21 #include <openssl/x509v3.h> 22 23 int X509_check_purpose(X509 *x, int id, int ca); 24 25 int X509_PURPOSE_get_count(void); 26 int X509_PURPOSE_get_unused_id(OSSL_LIB_CTX *libctx); 27 int X509_PURPOSE_get_by_sname(const char *sname); 28 int X509_PURPOSE_get_by_id(int id); 29 int X509_PURPOSE_add(int id, int trust, int flags, 30 int (*ck) (const X509_PURPOSE *, const X509 *, int), 31 const char *name, const char *sname, void *arg); 32 void X509_PURPOSE_cleanup(void); 33 34 X509_PURPOSE *X509_PURPOSE_get0(int idx); 35 int X509_PURPOSE_get_id(const X509_PURPOSE *); 36 char *X509_PURPOSE_get0_name(const X509_PURPOSE *xp); 37 char *X509_PURPOSE_get0_sname(const X509_PURPOSE *xp); 38 int X509_PURPOSE_get_trust(const X509_PURPOSE *xp); 39 int X509_PURPOSE_set(int *p, int purpose); 40 41=head1 DESCRIPTION 42 43X509_check_purpose() checks if certificate I<x> was created with the purpose 44represented by I<id>. If I<ca> is nonzero, then certificate I<x> is 45checked to determine if it's a possible CA with various levels of certainty 46possibly returned. The certificate I<x> must be a complete certificate 47otherwise the function returns an error. 48 49Below are the potential ID's that can be checked: 50 51 # define X509_PURPOSE_SSL_CLIENT 1 52 # define X509_PURPOSE_SSL_SERVER 2 53 # define X509_PURPOSE_NS_SSL_SERVER 3 54 # define X509_PURPOSE_SMIME_SIGN 4 55 # define X509_PURPOSE_SMIME_ENCRYPT 5 56 # define X509_PURPOSE_CRL_SIGN 6 57 # define X509_PURPOSE_ANY 7 58 # define X509_PURPOSE_OCSP_HELPER 8 59 # define X509_PURPOSE_TIMESTAMP_SIGN 9 60 # define X509_PURPOSE_CODE_SIGN 10 61 62The checks performed take into account the X.509 extensions 63keyUsage, extendedKeyUsage, and basicConstraints. 64 65X509_PURPOSE_get_count() returns the number of currently defined purposes. 66 67X509_PURPOSE_get_unused_id() returns the smallest purpose id not yet used, 68which is guaranteed to be unique and larger than B<X509_PURPOSE_MAX>. 69The I<libctx> parameter should be used to provide the library context. 70It is currently ignored as the purpose mapping table is global. 71 72X509_PURPOSE_get_by_sname() returns the index of 73the purpose with the given short name or -1 if not found. 74 75X509_PURPOSE_get_by_id() returns the index of 76the purpose with the given id or -1 if not found. 77 78X509_PURPOSE_add() adds or modifies a purpose entry identified by I<sname>. 79Unless the id stays the same for an existing entry, I<id> must be fresh, 80which can be achieved by using the result of X509_PURPOSE_get_unused_id(). 81The function also sets in the entry the trust id I<trust>, the given I<flags>, 82the purpose (long) name I<name>, the short name I<sname>, the purpose checking 83function I<ck> of type B<int (*) (const X509_PURPOSE *, const X509 *, int)>, 84and its user data I<arg> which may be retrieved via the B<X509_PURPOSE> pointer. 85 86X509_PURPOSE_cleanup() removes all purposes that are not pre-defined. 87 88X509_PURPOSE_get0() returns an B<X509_PURPOSE> pointer or NULL on error. 89 90X509_PURPOSE_get_id() returns the id of the given B<X509_PURPOSE> structure. 91 92X509_PURPOSE_get0_name() returns the (long) name of the given B<X509_PURPOSE>. 93 94X509_PURPOSE_get0_sname() returns the short name of the given B<X509_PURPOSE>. 95 96X509_PURPOSE_get_trust() returns the trust id of the given B<X509_PURPOSE>. 97 98X509_PURPOSE_set() assigns the given I<purpose> id to the location pointed at by 99I<p>. 100This resets to the any purpose if I<purpose> is B<X509_PURPOSE_DEFAULT_ANY>. 101 102=head1 RETURN VALUES 103 104X509_check_purpose() returns the following values. 105For non-CA checks 106 107=over 4 108 109=item -1 an error condition has occurred 110 111=item E<32>1 if the certificate was created to perform the purpose represented by I<id> 112 113=item E<32>0 if the certificate was not created to perform the purpose represented by I<id> 114 115=back 116 117For CA checks the below integers could be returned with the following meanings: 118 119=over 4 120 121=item -1 an error condition has occurred 122 123=item E<32>0 not a CA or does not have the purpose represented by I<id> 124 125=item E<32>1 is a CA. 126 127=item E<32>2 Only possible in old versions of openSSL when basicConstraints are absent. 128 New versions will not return this value. May be a CA 129 130=item E<32>3 basicConstraints absent but self signed V1. 131 132=item E<32>4 basicConstraints absent but keyUsage present and keyCertSign asserted. 133 134=item E<32>5 legacy Netscape specific CA Flags present 135 136=back 137 138X509_PURPOSE_get_count() returns the number of currently defined purposes. 139 140X509_PURPOSE_get_unused_id() returns the smallest purpose id not yet used. 141 142X509_PURPOSE_get_by_sname() returns the index of 143the purpose with the given short name or -1 if not found. 144 145X509_PURPOSE_get_by_id() returns the index of 146the purpose with the given id or -1 if not found. 147 148int X509_PURPOSE_add() returns 1 on success, 0 on error. 149 150X509_PURPOSE_cleanup() does not return anything. 151 152X509_PURPOSE_get0() returns an B<X509_PURPOSE> pointer or NULL on error. 153 154X509_PURPOSE_get_id() returns the id of the given B<X509_PURPOSE> structure. 155 156X509_PURPOSE_get0_name() returns the (long) name of the given B<X509_PURPOSE>. 157 158X509_PURPOSE_get0_sname() returns the short name of the given B<X509_PURPOSE>. 159 160X509_PURPOSE_get_trust() returns the trust id of the given B<X509_PURPOSE>. 161 162X509_PURPOSE_set() returns 1 on success, 0 on error. 163 164=head1 BUGS 165 166The X509_PURPOSE implementation so far is not thread-safe. 167There may be race conditions retrieving purpose information while 168X509_PURPOSE_add() or X509_PURPOSE_cleanup(void) is being called. 169 170=head1 HISTORY 171 172X509_PURPOSE_get_unused_id() was added in OpensSL 3.5. 173 174=head1 COPYRIGHT 175 176Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 177Licensed under the Apache License 2.0 (the "License"). You may not use this 178file except in compliance with the License. You can obtain a copy in the file 179LICENSE in the source distribution or at L<https://www.openssl.org/source/license.html>. 180 181=cut 182