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
129ccert = ne_ssl_clicert_read("/path/to/client.p12");
130
131if (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
141ne_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
154