Debian Codegraph @

deps/libneon/doc/man/ne_ssl_clicert_read.3

raw
1 '\" t
2 .\" Title: ne_ssl_client_cert
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_SSL_CLIENT_CERT" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_ssl_clicert_read, ne_ssl_clicert_name, ne_ssl_clicert_encrypted, ne_ssl_clicert_decrypt, ne_ssl_clicert_owner, ne_ssl_clicert_free \- SSL client certificate handling
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_ssl\&.h>
37 .fi
38 .ft
39 .HP \w'ne_ssl_client_cert\ *ne_ssl_clicert_read('u
40 .BI "ne_ssl_client_cert *ne_ssl_clicert_read(const\ char\ *" "filename" ");"
41 .HP \w'const\ char\ *ne_ssl_clicert_name('u
42 .BI "const char *ne_ssl_clicert_name(const\ ne_ssl_client_cert\ *" "ccert" ");"
43 .HP \w'int\ ne_ssl_clicert_encrypted('u
44 .BI "int ne_ssl_clicert_encrypted(const\ ne_ssl_client_cert\ *" "ccert" ");"
45 .HP \w'int\ ne_ssl_clicert_decrypt('u
46 .BI "int ne_ssl_clicert_decrypt(ne_ssl_client_cert\ *" "ccert" ", const\ char\ *" "password" ");"
47 .HP \w'const\ ne_ssl_certificate\ *ne_ssl_clicert_owner('u
48 .BI "const ne_ssl_certificate *ne_ssl_clicert_owner(const\ ne_ssl_client_cert\ *" "ccert" ");"
49 .HP \w'void\ ne_ssl_clicert_free('u
50 .BI "void ne_ssl_clicert_free(ne_ssl_client_cert\ *" "ccert" ");"
51 .SH "DESCRIPTION"
52 .PP
53 The
54 \fBne_ssl_clicert_read\fR
55 function reads a
56 client certificate
57 from a PKCS#12\-formatted file, and returns an
58 \fBne_ssl_client_cert\fR
59 object\&. If the client certificate is encrypted, it must be decrypted before it is used\&. An
60 \fBne_ssl_client_cert\fR
61 object holds a client certificate and the associated private key, not just a certificate; the term "client certificate" will used to refer to this pair\&.
62 .PP
63 A client certificate can be in one of two states:
64 \fIencrypted\fR
65 or
66 \fIdecrypted\fR\&. The
67 \fBne_ssl_clicert_encrypted\fR
68 function will return non\-zero if the client certificate is in the
69 \fIencrypted\fR
70 state\&. A client certificate object returned by
71 \fBne_ssl_clicert_read\fR
72 may be initially in either state, depending on whether the file was encrypted or not\&.
73 .PP
74 \fBne_ssl_clicert_decrypt\fR
75 can be used to decrypt a client certificate using the appropriate password\&. This function must only be called if the object is in the
76 \fIencrypted\fR
77 state; if decryption fails, the certificate state does not change, so decryption can be attempted more than once using different passwords\&.
78 .PP
79 A client certificate can be given a "friendly name" when it is created;
80 \fBne_ssl_clicert_name\fR
81 will return this name (or
82 NULL
83 if no friendly name was specified)\&.
84 \fBne_ssl_clicert_name\fR
85 can be used when the client certificate is in either the encrypted or decrypted state, and will return the same string for the lifetime of the object\&.
86 .PP
87 The function
88 \fBne_ssl_clicert_owner\fR
89 returns the certificate part of the client certificate; it must only be called if the client certificate is in the
90 \fIdecrypted\fR
91 state\&.
92 .PP
93 When the client certificate is no longer needed, the
94 \fBne_ssl_clicert_free\fR
95 function should be used to destroy the object\&.
96 .SH "RETURN VALUE"
97 .PP
98 \fBne_ssl_clicert_read\fR
99 returns a client certificate object, or
100 NULL
101 if the file could not be read\&.
102 \fBne_ssl_clicert_encrypted\fR
103 returns zero if the object is in the decrypted state, or non\-zero if it is in the encrypted state\&.
104 \fBne_ssl_clicert_name\fR
105 returns a
106 NUL\-terminated friendly name string, or
107 NULL\&.
108 \fBne_ssl_clicert_owner\fR
109 returns a certificate object\&.
110 .SH "EXAMPLES"
111 .PP
112 The following code reads a client certificate and decrypts it if necessary, then loads it into an HTTP session\&.
113 .sp
114 .if n \{\
115 .RS 4
116 .\}
117 .nf
118 ne_ssl_client_cert *ccert;
119
120 ccert = ne_ssl_clicert_read("/path/to/client\&.p12");
121
122 if (ccert == NULL) {
123 /* handle error\&.\&.\&. */
124 } else if (ne_ssl_clicert_encrypted(ccert)) {
125 char *password = prompt_for_password();
126
127 if (ne_ssl_clicert_decrypt(ccert, password)) {
128 /* could not decrypt! handle error\&.\&.\&. */
129 }
130 }
131
132 ne_ssl_set_clicert(sess, ccert);
133 .fi
134 .if n \{\
135 .RE
136 .\}
137 .SH "SEE ALSO"
138 .PP
139 ne_ssl_cert_read
140 .SH "AUTHOR"
141 .PP
142 \fBJoe Orton\fR <\&[email protected]\&>
143 .RS 4
144 Author.
145 .RE
146 .SH "COPYRIGHT"
147 .br