winscp/libs/neon/doc/man/ne_ssl_clicert_read.3

'\" t
.\"     Title: ne_ssl_client_cert
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 15 July 2025
.\"    Manual: neon API reference
.\"    Source: neon 0.35.0
.\"  Language: English
.\"
.TH "NE_SSL_CLIENT_CERT" "3" "15 July 2025" "neon 0.35.0" "neon API reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ne_ssl_clicert_read, ne_ssl_clicert_import, ne_ssl_clicert_fromuri, 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"
.sp
.ft B
.nf
#include <ne_ssl\&.h>
.fi
.ft
.HP \w'ne_ssl_client_cert\ *ne_ssl_clicert_read('u
.BI "ne_ssl_client_cert *ne_ssl_clicert_read(const\ char\ *" "filename" ");"
.HP \w'ne_ssl_client_cert\ *ne_ssl_clicert_import('u
.BI "ne_ssl_client_cert *ne_ssl_clicert_import(const\ unsigned\ char\ *" "filename" ", size_t\ " "buflen" ");"
.HP \w'ne_ssl_client_cert\ *ne_ssl_clicert_fromuri('u
.BI "ne_ssl_client_cert *ne_ssl_clicert_fromuri(const\ char\ *" "uri" ", unsigned\ " "flags" ");"
.HP \w'const\ char\ *ne_ssl_clicert_name('u
.BI "const char *ne_ssl_clicert_name(const\ ne_ssl_client_cert\ *" "ccert" ");"
.HP \w'int\ ne_ssl_clicert_encrypted('u
.BI "int ne_ssl_clicert_encrypted(const\ ne_ssl_client_cert\ *" "ccert" ");"
.HP \w'int\ ne_ssl_clicert_decrypt('u
.BI "int ne_ssl_clicert_decrypt(ne_ssl_client_cert\ *" "ccert" ", const\ char\ *" "password" ");"
.HP \w'const\ ne_ssl_certificate\ *ne_ssl_clicert_owner('u
.BI "const ne_ssl_certificate *ne_ssl_clicert_owner(const\ ne_ssl_client_cert\ *" "ccert" ");"
.HP \w'void\ ne_ssl_clicert_free('u
.BI "void ne_ssl_clicert_free(ne_ssl_client_cert\ *" "ccert" ");"
.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\&. The
\fBne_ssl_clicert_import\fR
function reads a client certificate from a memory buffer using the PKCS#12 format\&. The
\fBne_ssl_clicert_fromuri\fR
function loads a client certificate from a URI\&. URI schemes supported are defined by the SSL/TLS toolkit, and may include
\m[blue]\fBPKCS#11 URIs\fR\m[]\&\s-2\u[1]\d\s+2\&.
.PP
A
\fBne_ssl_client_cert\fR
object represents both a client certificate and the associated private key; the term "client certificate" is used here to refer to this pair\&. A client certificate object loaded by any of the above functions 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\&.
.PP
A client certificate
\fImust\fR
be in the decrypted state before it is associated with a session\&.
\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 object 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,
\fBne_ssl_clicert_import\fR
and
\fBne_ssl_clicert_fromuri\fR
all return a client certificate object, or
NULL
if the certificate could not be read/imported\&.
\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
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.SH "HISTORY"
.PP
\fBne_ssl_clicert_import\fR
was added in neon 0\&.30\&.0\&.
\fBne_ssl_clicert_fromuri\fR
was added in neon 0\&.35\&.0\&.
.SH "SEE ALSO"
.PP
ne_ssl_cert_read
.SH "COPYRIGHT"
.br
Copyright \(co 2001-2025 Joe Orton
.br
.SH "REFERENCES"
.IP " 1." 4
PKCS#11 URIs
.RS 4
\%https://www.rfc-editor.org/rfc/rfc7512.html
.RE