.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "NE_SSL_CLIENT_CERT" "3" "23 May 2006" "neon 0.26.1" "neon API reference"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
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
.SH "SYNOPSIS"
.PP
\fB#include <ne_ssl.h>\fR
.HP 40
\fBne_ssl_client_cert\ *\fBne_ssl_clicert_read\fR\fR\fB(\fR\fBconst\ char\ *\fR\fB\fIfilename\fR\fR\fB);\fR
.HP 32
\fBconst\ char\ *\fBne_ssl_clicert_name\fR\fR\fB(\fR\fBconst\ ne_ssl_client_cert\ *\fR\fB\fIccert\fR\fR\fB);\fR
.HP 29
\fBint\ \fBne_ssl_clicert_encrypted\fR\fR\fB(\fR\fBconst\ ne_ssl_client_cert\ *\fR\fB\fIccert\fR\fR\fB);\fR
.HP 27
\fBint\ \fBne_ssl_clicert_decrypt\fR\fR\fB(\fR\fBne_ssl_client_cert\ *\fR\fB\fIccert\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIpassword\fR\fR\fB);\fR
.HP 47
\fBconst\ ne_ssl_certificate\ *\fBne_ssl_clicert_owner\fR\fR\fB(\fR\fBconst\ ne_ssl_client_cert\ *\fR\fB\fIccert\fR\fR\fB);\fR
.HP 25
\fBvoid\ \fBne_ssl_clicert_free\fR\fR\fB(\fR\fBne_ssl_client_cert\ *\fR\fB\fIccert\fR\fR\fB);\fR
.SH "DESCRIPTION"
.PP
The
\fBne_ssl_clicert_read\fR
function reads a
client certificate
from a PKCS#12\-formatted file, and returns an
\fBne_ssl_client_cert\fR
object. If the client certificate is encrypted, it must be decrypted before it is used. An
\fBne_ssl_client_cert\fR
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.
.PP
A client certificate can be in one of two states:
\fIencrypted\fR
or
\fIdecrypted\fR. The
\fBne_ssl_clicert_encrypted\fR
function will return non\-zero if the client certificate is in the
\fIencrypted\fR
state. A client certificate object returned by
\fBne_ssl_clicert_read\fR
may be initially in either state, depending on whether the file was encrypted or not.
.PP
\fBne_ssl_clicert_decrypt\fR
can be used to decrypt a client certificate using the appropriate password. This function must only be called if the object is in the
\fIencrypted\fR
state; if decryption fails, the certificate state does not change, so decryption can be attempted more than once using different passwords.
.PP
A client certificate can be given a "friendly name" when it is created;
\fBne_ssl_clicert_name\fR
will return this name (or
NULL
if no friendly name was specified).
\fBne_ssl_clicert_name\fR
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.
.PP
The function
\fBne_ssl_clicert_owner\fR
returns the certificate part of the client certificate; it must only be called if the client certificate is in the
\fIdecrypted\fR
state.
.PP
When the client certificate is no longer needed, the
\fBne_ssl_clicert_free\fR
function should be used to destroy the object.
.SH "RETURN VALUE"
.PP
\fBne_ssl_clicert_read\fR
returns a client certificate object, or
NULL
if the file could not be read.
\fBne_ssl_clicert_encrypted\fR
returns zero if the object is in the decrypted state, or non\-zero if it is in the encrypted state.
\fBne_ssl_clicert_name\fR
returns a
NUL\-terminated friendly name string, or
NULL.
\fBne_ssl_clicert_owner\fR
returns a certificate object.
.SH "EXAMPLES"
.PP
The following code reads a client certificate and decrypts it if necessary, then loads it into an HTTP session.
.sp
.nf
ne_ssl_client_cert *ccert;

ccert = ne_ssl_clicert_read("/path/to/client.p12");

if (ccert == NULL) {
   /* handle error... */
} else if (ne_ssl_clicert_encrypted(ccert)) {
   char *password = prompt_for_password();

   if (ne_ssl_clicert_decrypt(ccert, password)) {
      /* could not decrypt! handle error... */
   }
}

ne_ssl_set_clicert(sess, ccert);
.fi
.SH "SEE ALSO"
.PP
ne_ssl_cert_read