1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384SjkimX509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/x509_vfy.h> 10238384Sjkim 11238384Sjkim int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); 12238384Sjkim int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, 13238384Sjkim unsigned long flags); 14238384Sjkim unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); 15238384Sjkim 16238384Sjkim int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); 17238384Sjkim int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); 18238384Sjkim 19238384Sjkim void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); 20238384Sjkim 21238384Sjkim int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, 22238384Sjkim ASN1_OBJECT *policy); 23238384Sjkim int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, 24238384Sjkim STACK_OF(ASN1_OBJECT) *policies); 25238384Sjkim 26238384Sjkim void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); 27238384Sjkim int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); 28238384Sjkim 29238384Sjkim=head1 DESCRIPTION 30238384Sjkim 31238384SjkimThese functions manipulate the B<X509_VERIFY_PARAM> structure associated with 32238384Sjkima certificate verification operation. 33238384Sjkim 34238384SjkimThe X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring 35238384Sjkimit with B<flags>. See the B<VERIFICATION FLAGS> section for a complete 36238384Sjkimdescription of values the B<flags> parameter can take. 37238384Sjkim 38238384SjkimX509_VERIFY_PARAM_get_flags() returns the flags in B<param>. 39238384Sjkim 40238384SjkimX509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. 41238384Sjkim 42238384SjkimX509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> 43238384Sjkimto B<purpose>. This determines the acceptable purpose of the certificate 44238384Sjkimchain, for example SSL client or SSL server. 45238384Sjkim 46238384SjkimX509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to 47238384SjkimB<trust>. 48238384Sjkim 49238384SjkimX509_VERIFY_PARAM_set_time() sets the verification time in B<param> to 50238384SjkimB<t>. Normally the current time is used. 51238384Sjkim 52238384SjkimX509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled 53238384Sjkimby default) and adds B<policy> to the acceptable policy set. 54238384Sjkim 55238384SjkimX509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled 56238384Sjkimby default) and sets the acceptable policy set to B<policies>. Any existing 57238384Sjkimpolicy set is cleared. The B<policies> parameter can be B<NULL> to clear 58238384Sjkiman existing policy set. 59238384Sjkim 60238384SjkimX509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. 61238384SjkimThat is the maximum number of untrusted CA certificates that can appear in a 62238384Sjkimchain. 63238384Sjkim 64238384Sjkim=head1 RETURN VALUES 65238384Sjkim 66238384SjkimX509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), 67238384SjkimX509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), 68238384SjkimX509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 69238384Sjkimfor success and 0 for failure. 70238384Sjkim 71238384SjkimX509_VERIFY_PARAM_get_flags() returns the current verification flags. 72238384Sjkim 73238384SjkimX509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return 74238384Sjkimvalues. 75238384Sjkim 76238384SjkimX509_VERIFY_PARAM_get_depth() returns the current verification depth. 77238384Sjkim 78238384Sjkim=head1 VERIFICATION FLAGS 79238384Sjkim 80238384SjkimThe verification flags consists of zero or more of the following flags 81238384Sjkimored together. 82238384Sjkim 83238384SjkimB<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf 84238384Sjkimcertificate. An error occurs if a suitable CRL cannot be found. 85238384Sjkim 86238384SjkimB<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate 87238384Sjkimchain. 88238384Sjkim 89238384SjkimB<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default 90238384Sjkimany unhandled critical extensions in certificates or (if checked) CRLs results 91238384Sjkimin a fatal error. If this flag is set unhandled critical extensions are 92238384Sjkimignored. B<WARNING> setting this option for anything other than debugging 93238384Sjkimpurposes can be a security risk. Finer control over which extensions are 94238384Sjkimsupported can be performed in the verification callback. 95238384Sjkim 96238384SjkimTHe B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken 97238384Sjkimcertificates and makes the verification strictly apply B<X509> rules. 98238384Sjkim 99238384SjkimB<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. 100238384Sjkim 101238384SjkimB<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default 102238384Sjkimno policy checking is peformed. Additional information is sent to the 103238384Sjkimverification callback relating to policy checking. 104238384Sjkim 105238384SjkimB<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and 106238384SjkimB<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any 107238384Sjkimpolicy> and B<inhibit policy mapping> flags respectively as defined in 108238384SjkimB<RFC3280>. Policy checking is automatically enabled if any of these flags 109238384Sjkimare set. 110238384Sjkim 111238384SjkimIf B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful 112238384Sjkima special status code is set to the verification callback. This permits it 113238384Sjkimto examine the valid policy tree and perform additional checks or simply 114238384Sjkimlog it for debugging purposes. 115238384Sjkim 116264331SjkimBy default some additional features such as indirect CRLs and CRLs signed by 117238384Sjkimdifferent keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set 118238384Sjkimthey are enabled. 119238384Sjkim 120238384SjkimIf B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to 121238384Sjkimdetermine certificate status. If not set deltas are ignored. 122238384Sjkim 123238384SjkimB<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed 124238384Sjkimcerificate signature. By default this check is disabled because it doesn't 125238384Sjkimadd any additional security but in some cases applications might want to 126238384Sjkimcheck the signature anyway. A side effect of not checking the root CA 127238384Sjkimsignature is that disabled or unsupported message digests on the root CA 128238384Sjkimare not treated as fatal errors. 129238384Sjkim 130238384SjkimThe B<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate 131238384Sjkimissuer checks. It is B<not> needed unless you are logging certificate 132238384Sjkimverification. If this flag is set then additional status codes will be sent 133238384Sjkimto the verification callback and it B<must> be prepared to handle such cases 134238384Sjkimwithout assuming they are hard errors. 135238384Sjkim 136284285SjkimThe B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative 137284285Sjkimchains. By default, when building a certificate chain, if the first certificate 138284285Sjkimchain found is not trusted, then OpenSSL will continue to check to see if an 139284285Sjkimalternative chain can be found that is trusted. With this flag set the behaviour 140284285Sjkimwill match that of OpenSSL versions prior to 1.0.1n and 1.0.2b. 141284285Sjkim 142238384Sjkim=head1 NOTES 143238384Sjkim 144238384SjkimThe above functions should be used to manipulate verification parameters 145238384Sjkiminstead of legacy functions which work in specific structures such as 146238384SjkimX509_STORE_CTX_set_flags(). 147238384Sjkim 148238384Sjkim=head1 BUGS 149238384Sjkim 150238384SjkimDelta CRL checking is currently primitive. Only a single delta can be used and 151238384Sjkim(partly due to limitations of B<X509_STORE>) constructed CRLs are not 152238384Sjkimmaintained. 153238384Sjkim 154238384SjkimIf CRLs checking is enable CRLs are expected to be available in the 155238384Sjkimcorresponding B<X509_STORE> structure. No attempt is made to download 156238384SjkimCRLs from the CRL distribution points extension. 157238384Sjkim 158238384Sjkim=head1 EXAMPLE 159238384Sjkim 160238384SjkimEnable CRL checking when performing certificate verification during SSL 161238384Sjkimconnections associated with an B<SSL_CTX> structure B<ctx>: 162238384Sjkim 163238384Sjkim X509_VERIFY_PARAM *param; 164238384Sjkim param = X509_VERIFY_PARAM_new(); 165238384Sjkim X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); 166238384Sjkim SSL_CTX_set1_param(ctx, param); 167238384Sjkim X509_VERIFY_PARAM_free(param); 168238384Sjkim 169238384Sjkim=head1 SEE ALSO 170238384Sjkim 171238384SjkimL<X509_verify_cert(3)|X509_verify_cert(3)> 172238384Sjkim 173238384Sjkim=head1 HISTORY 174238384Sjkim 175284285SjkimThe B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.0.1n and 1.0.2b 176238384Sjkim 177238384Sjkim=cut 178