← Back to branch summary

~brian-sidebotham/openssl-cmake/1.0.1e

« back to all changes in this revision

Viewing changes to doc/crypto/X509_STORE_CTX_set_verify_cb.pod

  • Committer: Brian Sidebotham
  • Date: 2013-10-19 21:50:27 UTC
  • Revision ID: brian.sidebotham@gmail.com-20131019215027-yzoyh4svqj87uepu
Import OpenSSL 1.0.1e

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/crypto/X509_STORE_CTX_set_verify_cb.pod
 
1
=pod
 
2
 
 
3
=head1 NAME
 
4
 
 
5
X509_STORE_CTX_set_verify_cb - set verification callback
 
6
 
 
7
=head1 SYNOPSIS
 
8
 
 
9
 #include <openssl/x509_vfy.h>
 
10
 
 
11
 void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
 
12
                                int (*verify_cb)(int ok, X509_STORE_CTX *ctx));
 
13
 
 
14
=head1 DESCRIPTION
 
15
 
 
16
X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
 
17
B<verify_cb> overwriting any existing callback.
 
18
 
 
19
The verification callback can be used to customise the operation of certificate
 
20
verification, either by overriding error conditions or logging errors for
 
21
debugging purposes.
 
22
 
 
23
However a verification callback is B<not> essential and the default operation
 
24
is often sufficient.
 
25
 
 
26
The B<ok> parameter to the callback indicates the value the callback should
 
27
return to retain the default behaviour. If it is zero then and error condition
 
28
is indicated. If it is 1 then no error occurred. If the flag
 
29
B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the
 
30
policy checking is complete.
 
31
 
 
32
The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that
 
33
is performing the verification operation. A callback can examine this
 
34
structure and receive additional information about the error, for example
 
35
by calling X509_STORE_CTX_get_current_cert(). Additional application data can
 
36
be passed to the callback via the B<ex_data> mechanism.
 
37
 
 
38
=head1 WARNING
 
39
 
 
40
In general a verification callback should B<NOT> unconditionally return 1 in
 
41
all circumstances because this will allow verification to succeed no matter
 
42
what the error. This effectively removes all security from the application
 
43
because B<any> certificate (including untrusted generated ones) will be
 
44
accepted.
 
45
 
 
46
=head1 NOTES
 
47
 
 
48
The verification callback can be set and inherited from the parent structure
 
49
performing the operation. In some cases (such as S/MIME verification) the
 
50
B<X509_STORE_CTX> structure is created and destroyed internally and the
 
51
only way to set a custom verification callback is by inheriting it from the
 
52
associated B<X509_STORE>.
 
53
 
 
54
=head1 RETURN VALUES
 
55
 
 
56
X509_STORE_CTX_set_verify_cb() does not return a value.
 
57
 
 
58
=head1 EXAMPLES
 
59
 
 
60
Default callback operation:
 
61
 
 
62
 int verify_callback(int ok, X509_STORE_CTX *ctx)
 
63
        {
 
64
        return ok;
 
65
        }
 
66
 
 
67
Simple example, suppose a certificate in the chain is expired and we wish
 
68
to continue after this error:
 
69
 
 
70
 int verify_callback(int ok, X509_STORE_CTX *ctx)
 
71
        {
 
72
        /* Tolerate certificate expiration */
 
73
        if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
 
74
                        return 1;
 
75
        /* Otherwise don't override */
 
76
        return ok;
 
77
        }
 
78
 
 
79
More complex example, we don't wish to continue after B<any> certificate has
 
80
expired just one specific case:
 
81
 
 
82
 int verify_callback(int ok, X509_STORE_CTX *ctx)
 
83
        {
 
84
        int err = X509_STORE_CTX_get_error(ctx);
 
85
        X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
 
86
        if (err == X509_V_ERR_CERT_HAS_EXPIRED)
 
87
                {
 
88
                if (check_is_acceptable_expired_cert(err_cert)
 
89
                        return 1;
 
90
                }
 
91
        return ok;
 
92
        }
 
93
 
 
94
Full featured logging callback. In this case the B<bio_err> is assumed to be
 
95
a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
 
96
B<ex_data>.
 
97
        
 
98
 int verify_callback(int ok, X509_STORE_CTX *ctx)
 
99
        {
 
100
        X509 *err_cert;
 
101
        int err,depth;
 
102
 
 
103
        err_cert = X509_STORE_CTX_get_current_cert(ctx);
 
104
        err =   X509_STORE_CTX_get_error(ctx);
 
105
        depth = X509_STORE_CTX_get_error_depth(ctx);
 
106
 
 
107
        BIO_printf(bio_err,"depth=%d ",depth);
 
108
        if (err_cert)
 
109
                {
 
110
                X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
 
111
                                        0, XN_FLAG_ONELINE);
 
112
                BIO_puts(bio_err, "\n");
 
113
                }
 
114
        else
 
115
                BIO_puts(bio_err, "<no cert>\n");
 
116
        if (!ok)
 
117
                BIO_printf(bio_err,"verify error:num=%d:%s\n",err,
 
118
                        X509_verify_cert_error_string(err));
 
119
        switch (err)
 
120
                {
 
121
        case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
 
122
                BIO_puts(bio_err,"issuer= ");
 
123
                X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
 
124
                                        0, XN_FLAG_ONELINE);
 
125
                BIO_puts(bio_err, "\n");
 
126
                break;
 
127
        case X509_V_ERR_CERT_NOT_YET_VALID:
 
128
        case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
 
129
                BIO_printf(bio_err,"notBefore=");
 
130
                ASN1_TIME_print(bio_err,X509_get_notBefore(err_cert));
 
131
                BIO_printf(bio_err,"\n");
 
132
                break;
 
133
        case X509_V_ERR_CERT_HAS_EXPIRED:
 
134
        case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
 
135
                BIO_printf(bio_err,"notAfter=");
 
136
                ASN1_TIME_print(bio_err,X509_get_notAfter(err_cert));
 
137
                BIO_printf(bio_err,"\n");
 
138
                break;
 
139
        case X509_V_ERR_NO_EXPLICIT_POLICY:
 
140
                policies_print(bio_err, ctx);
 
141
                break;
 
142
                }
 
143
        if (err == X509_V_OK && ok == 2)
 
144
                /* print out policies */
 
145
 
 
146
        BIO_printf(bio_err,"verify return:%d\n",ok);
 
147
        return(ok);
 
148
        }
 
149
 
 
150
=head1 SEE ALSO
 
151
 
 
152
L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)>
 
153
L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)>
 
154
L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)>
 
155
 
 
156
=head1 HISTORY
 
157
 
 
158
X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and
 
159
OpenSSL.
 
160
 
 
161
=cut