Fix typos
[openssl.git] / doc / crypto / X509_get_extension_flags.pod
1 =pod
2
3 =head1 NAME
4
5 X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage -
6 retrieve certificate extension flags.
7
8 =head1 SYNOPSIS
9
10    #include <openssl/x509v3.h>
11
12    uint32_t X509_get_extension_flags(X509 *x);
13    uint32_t X509_get_key_usage(X509 *x);
14    uint32_t X509_get_extended_key_usage(X509 *x);
15    const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
16
17 =head1 DESCRIPTION
18
19 These functions retrieve flags related to commonly used certificate extensions.
20
21 X509_get_extension_flags() retrieves general information about a certificate,
22 it will return one or more of the following flags ored together.
23
24 =over 4
25
26 =item B<EXFLAG_V1>
27
28 The certificate is an obsolete version 1 certificate.
29
30 =item B<EXFLAG_BCONS>
31
32 The certificate contains a basic constraints extension.
33
34 =item B<EXFLAG_CA>
35
36 The certificate contains basic constraints and asserts the CA flag.
37
38 =item B<EXFLAG_PROXY>
39
40 The certificate is a valid proxy certificate.
41
42 =item B<EXFLAG_SI>
43
44 The certificate is self issued (that is subject and issuer names match).
45
46 =item B<EXFLAG_SS>
47
48 The subject and issuer names match and extension values imply it is self
49 signed.
50
51 =item B<EXFLAG_FRESHEST>
52
53 The freshest CRL extension is present in the certificate.
54
55 =item B<EXFLAG_CRITICAL>
56
57 The certificate contains an unhandled critical extension.
58
59 =item B<EXFLAG_INVALID>
60
61 Some certificate extension values are invalid or inconsistent. The
62 certificate should be rejected.
63
64 =item B<EXFLAG_KUSAGE>
65
66 The certificate contains a key usage extension. The value can be retrieved
67 using X509_get_key_usage().
68
69 =item B<EXFLAG_XKUSAGE>
70
71 The certificate contains an extended key usage extension. The value can be
72 retrieved using X509_get_extended_key_usage().
73
74 =back
75
76 X509_get_key_usage() returns the value of the key usage extension.  If key
77 usage is present will return zero or more of the flags:
78 B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>,
79 B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>,
80 B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to
81 individual key usage bits. If key usage is absent then B<UINT32_MAX> is
82 returned.
83
84 X509_get_extended_key_usage() returns the value of the extended key usage
85 extension. If extended key usage is present it will return zero or more of the
86 flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN>
87 B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These
88 correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>,
89 B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>,
90 B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively.
91 Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are
92 present.
93
94 X509_get_extended_key_usage() return an internal pointer to the subject key
95 identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension
96 is not present or cannot be parsed.
97
98 =head1 NOTES
99
100 The value of the flags correspond to extension values which are cached
101 in the B<X509> structure. If the flags returned do not provide sufficient
102 information an application should examine extension values directly
103 for example using X509_get_ext_d2i().
104
105 If the key usage or extended key usage extension is absent then typically usage
106 is unrestricted. For this reason X509_get_key_usage() and
107 X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding
108 extension is absent. Applications can additionally check the return value of
109 X509_get_extension_flags() and take appropriate action is an extension is
110 absent.
111
112 If X509_get0_subject_key_id() returns B<NULL> then the extension may be
113 absent or malformed. Applications can determine the precise reason using
114 X509_get_ext_d2i().
115
116 =head1 RETURN VALUE
117
118 X509_get_extension_flags(), X509_get_key_usage() and
119 X509_get_extended_key_usage() return sets of flags corresponding to the
120 certificate extension values.
121
122 X509_get0_subject_key_id() returns the subject key identifier as a
123 pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension
124 is absent or an error occurred during parsing.
125
126 =head1 SEE ALSO
127
128 L<X509_check_purpose(3)>
129
130 =cut