Debian Codegraph @

deps/libneon/doc/ref/clicert.xml

raw
1 <refentry id="refclicert">
2
3 <refmeta>
4 <refentrytitle>ne_ssl_client_cert</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname id="ne_ssl_clicert_read">ne_ssl_clicert_read</refname>
10 <refname id="ne_ssl_clicert_name">ne_ssl_clicert_name</refname>
11 <refname id="ne_ssl_clicert_encrypted">ne_ssl_clicert_encrypted</refname>
12 <refname id="ne_ssl_clicert_decrypt">ne_ssl_clicert_decrypt</refname>
13 <refname id="ne_ssl_clicert_owner">ne_ssl_clicert_owner</refname>
14 <refname id="ne_ssl_clicert_free">ne_ssl_clicert_free</refname>
15 <refpurpose>SSL client certificate handling</refpurpose>
16 </refnamediv>
17
18 <refsynopsisdiv>
19
20 <funcsynopsis>
21
22 <funcsynopsisinfo>#include &lt;ne_ssl.h&gt;</funcsynopsisinfo>
23
24 <funcprototype>
25 <funcdef>ne_ssl_client_cert *<function>ne_ssl_clicert_read</function></funcdef>
26 <paramdef>const char *<parameter>filename</parameter></paramdef>
27 </funcprototype>
28
29 <funcprototype>
30 <funcdef>const char *<function>ne_ssl_clicert_name</function></funcdef>
31 <paramdef>const ne_ssl_client_cert *<parameter>ccert</parameter></paramdef>
32 </funcprototype>
33
34 <funcprototype>
35 <funcdef>int <function>ne_ssl_clicert_encrypted</function></funcdef>
36 <paramdef>const ne_ssl_client_cert *<parameter>ccert</parameter></paramdef>
37 </funcprototype>
38
39 <funcprototype>
40 <funcdef>int <function>ne_ssl_clicert_decrypt</function></funcdef>
41 <paramdef>ne_ssl_client_cert *<parameter>ccert</parameter></paramdef>
42 <paramdef>const char *<parameter>password</parameter></paramdef>
43 </funcprototype>
44
45 <funcprototype>
46 <funcdef>const ne_ssl_certificate *<function>ne_ssl_clicert_owner</function></funcdef>
47 <paramdef>const ne_ssl_client_cert *<parameter>ccert</parameter></paramdef>
48 </funcprototype>
49
50 <funcprototype>
51 <funcdef>void <function>ne_ssl_clicert_free</function></funcdef>
52 <paramdef>ne_ssl_client_cert *<parameter>ccert</parameter></paramdef>
53 </funcprototype>
54
55 </funcsynopsis>
56
57 </refsynopsisdiv>
58
59 <refsect1>
60 <title>Description</title>
61
62 <para>The <function>ne_ssl_clicert_read</function> function reads
63 a <firstterm>client certificate</firstterm> from a
64 PKCS#12-formatted file, and returns an
65 <type>ne_ssl_client_cert</type> object. If the client
66 certificate is encrypted, it must be decrypted before it is used.
67 An <type>ne_ssl_client_cert</type> object holds a client
68 certificate and the associated private key, not just a
69 certificate; the term "<glossterm>client certificate</glossterm>"
70 will used to refer to this pair.</para>
71
72 <para>A client certificate can be in one of two states:
73 <emphasis>encrypted</emphasis> or <emphasis>decrypted</emphasis>.
74 The <function>ne_ssl_clicert_encrypted</function> function will
75 return non-zero if the client certificate is in the
76 <emphasis>encrypted</emphasis> state. A client certificate object
77 returned by <function>ne_ssl_clicert_read</function> may be
78 initially in either state, depending on whether the file was
79 encrypted or not.</para>
80
81 <para><function>ne_ssl_clicert_decrypt</function> can be used to
82 decrypt a client certificate using the appropriate password. This
83 function must only be called if the object is in the
84 <emphasis>encrypted</emphasis> state; if decryption fails, the
85 certificate state does not change, so decryption can be attempted
86 more than once using different passwords.</para>
87
88 <para>A client certificate can be given a "friendly name" when it
89 is created; <function>ne_ssl_clicert_name</function> will return
90 this name (or &null; if no friendly name was specified).
91 <function>ne_ssl_clicert_name</function> can be used when the
92 client certificate is in either the encrypted or decrypted state,
93 and will return the same string for the lifetime of the
94 object.</para>
95
96 <para>The function <function>ne_ssl_clicert_owner</function>
97 returns the certificate part of the client certificate; it must
98 only be called if the client certificate is in the
99 <emphasis>decrypted</emphasis> state.</para>
100
101 <para>When the client certificate is no longer needed, the
102 <function>ne_ssl_clicert_free</function> function should be used
103 to destroy the object.</para>
104
105 </refsect1>
106
107 <refsect1>
108 <title>Return value</title>
109
110 <para><function>ne_ssl_clicert_read</function> returns a client
111 certificate object, or &null; if the file could not be read.
112 <function>ne_ssl_clicert_encrypted</function> returns zero if the
113 object is in the decrypted state, or non-zero if it is in the
114 encrypted state. <function>ne_ssl_clicert_name</function> returns
115 a &nul;-terminated friendly name string, or &null;.
116 <function>ne_ssl_clicert_owner</function> returns a certificate
117 object.</para>
118
119 </refsect1>
120
121 <refsect1>
122 <title>Examples</title>
123
124 <para>The following code reads a client certificate and decrypts
125 it if necessary, then loads it into an HTTP session.</para>
126
127 <programlisting>ne_ssl_client_cert *ccert;
128
129 ccert = ne_ssl_clicert_read("/path/to/client.p12");
130
131 if (ccert == NULL) {
132 /* handle error... */
133 } else if (ne_ssl_clicert_encrypted(ccert)) {
134 char *password = prompt_for_password();
135
136 if (ne_ssl_clicert_decrypt(ccert, password)) {
137 /* could not decrypt! handle error... */
138 }
139 }
140
141 ne_ssl_set_clicert(sess, ccert);
142 </programlisting>
143
144 </refsect1>
145
146 <refsect1>
147 <title>See also</title>
148
149 <para><xref linkend="ne_ssl_cert_read"/></para>
150 </refsect1>
151
152 </refentry>
153