1NE_SSL_CLIENT_CERT(3)         neon API reference         NE_SSL_CLIENT_CERT(3)
2
3
4

NAME

6       ne_ssl_clicert_read,   ne_ssl_clicert_name,   ne_ssl_clicert_encrypted,
7       ne_ssl_clicert_decrypt, ne_ssl_clicert_owner, ne_ssl_clicert_free - SSL
8       client certificate handling
9

SYNOPSIS

11       #include <ne_ssl.h>
12
13
14       ne_ssl_client_cert *ne_ssl_clicert_read (const char *filename);
15
16       const char *ne_ssl_clicert_name (const ne_ssl_client_cert *ccert);
17
18       int ne_ssl_clicert_encrypted (const ne_ssl_client_cert *ccert);
19
20       int ne_ssl_clicert_decrypt (ne_ssl_client_cert *ccert,
21                                   const char *password);
22
23       const ne_ssl_certificate *ne_ssl_clicert_owner (const ne_ssl_client_cert *ccert);
24
25       void ne_ssl_clicert_free (ne_ssl_client_cert *ccert);
26
27

DESCRIPTION

29       The  ne_ssl_clicert_read  function  reads  a  client certificate from a
30       PKCS#12-formatted file, and returns an  ne_ssl_client_cert  object.  If
31       the  client certificate is encrypted, it must be decrypted before it is
32       used. An ne_ssl_client_cert object holds a client certificate  and  the
33       associated  private  key, not just a certificate; the term "client cer‐
34       tificate" will used to refer to this pair.
35
36
37       A client certificate can be in one of two states: encrypted or decrypt‐
38       ed.  The  ne_ssl_clicert_encrypted function will return non-zero if the
39       client certificate is in the encrypted state. A client certificate  ob‐
40       ject  returned by ne_ssl_clicert_read may be initially in either state,
41       depending on whether the file was encrypted or not.
42
43
44       ne_ssl_clicert_decrypt can be used to decrypt a client certificate  us‐
45       ing  the appropriate password. This function must only be called if the
46       object is in the encrypted state; if decryption fails, the  certificate
47       state  does  not  change, so decryption can be attempted more than once
48       using different passwords.
49
50
51       A client certificate can be given a "friendly name" when it is created;
52       ne_ssl_clicert_name  will return this name (or NULL if no friendly name
53       was specified). ne_ssl_clicert_name can be used when  the  client  cer‐
54       tificate is in either the encrypted or decrypted state, and will return
55       the same string for the lifetime of the object.
56
57
58       The function ne_ssl_clicert_owner returns the certificate part  of  the
59       client certificate; it must only be called if the client certificate is
60       in the decrypted state.
61
62
63       When   the   client   certificate   is   no    longer    needed,    the
64       ne_ssl_clicert_free function should be used to destroy the object.
65
66

RETURN VALUE

68       ne_ssl_clicert_read returns a client certificate object, or NULL if the
69       file could not be read. ne_ssl_clicert_encrypted returns  zero  if  the
70       object is in the decrypted state, or non-zero if it is in the encrypted
71       state.  ne_ssl_clicert_name  returns  a  NUL-terminated  friendly  name
72       string, or NULL. ne_ssl_clicert_owner returns a certificate object.
73
74

EXAMPLES

76       The following code reads a client certificate and decrypts it if neces‐
77       sary, then loads it into an HTTP session.
78
79       ne_ssl_client_cert *ccert;
80
81       ccert = ne_ssl_clicert_read("/path/to/client.p12");
82
83       if (ccert == NULL) {
84          /* handle error... */
85       } else if (ne_ssl_clicert_encrypted(ccert)) {
86          char *password = prompt_for_password();
87
88          if (ne_ssl_clicert_decrypt(ccert, password)) {
89             /* could not decrypt! handle error... */
90          }
91       }
92
93       ne_ssl_set_clicert(sess, ccert);
94
95
96

SEE ALSO

98       ne_ssl_cert_read(3)
99
100

AUTHOR

102       Joe Orton <neon@webdav.org>.
103
104
105
106neon 0.25.5                     20 January 2006          NE_SSL_CLIENT_CERT(3)