| 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 <ne_ssl.h></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 |
|