ne_ssl_clicert_read.3

linux subdivision ying gai ke yi le ba

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NE_SSL_CLIENT_CERT" 3 "5 July 2004" "neon 0.24.7" "neon API reference"
.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"
.ad l
.hy 0

#include <ne_ssl\&.h>
.sp
.HP 41
ne_ssl_client_cert\ *\fBne_ssl_clicert_read\fR\ (const\ char\ *\fIfilename\fR);
.HP 34
const\ char\ *\fBne_ssl_clicert_name\fR\ (const\ ne_ssl_client_cert\ *\fIccert\fR);
.HP 30
int\ \fBne_ssl_clicert_encrypted\fR\ (const\ ne_ssl_client_cert\ *\fIccert\fR);
.HP 28
int\ \fBne_ssl_clicert_decrypt\fR\ (ne_ssl_client_cert\ *\fIccert\fR, const\ char\ *\fIpassword\fR);
.HP 49
const\ ne_ssl_certificate\ *\fBne_ssl_clicert_owner\fR\ (const\ ne_ssl_client_cert\ *\fIccert\fR);
.HP 26
void\ \fBne_ssl_clicert_free\fR\ (ne_ssl_client_cert\ *\fIccert\fR);
.ad
.hy

.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_certificate\fR object\&. If the client certificate is encrypted, it must be decrypted before it is used\&. An \fBne_ssl_client_certificate\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: encrypted or decrypted\&. The \fBne_ssl_clicert_encrypted\fR function will return non\-zero if the client certificate is in the encrypted 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 encrypted 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 decrypted 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\&.

.nf
ne_ssl_client_certificate *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
\fBne_ssl_cert_read\fR(3)

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.