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 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