ne_ssl_client_cert
Prev | neon API reference | Next

## 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

## Synopsis

    #include <ne_ssl.h>

``ne_ssl_client_cert *ne_ssl_clicert_read(`const char *filename`)`;`
``ne_ssl_client_cert *ne_ssl_clicert_import(`const unsigned char *filename, size_t buflen`)`;`
``ne_ssl_client_cert *ne_ssl_clicert_fromuri(`const char *uri, unsigned flags`)`;`
``const char *ne_ssl_clicert_name(`const ne_ssl_client_cert *ccert`)`;`
``int ne_ssl_clicert_encrypted(`const ne_ssl_client_cert *ccert`)`;`
``int ne_ssl_clicert_decrypt(`ne_ssl_client_cert *ccert, const char *password`)`;`
``const ne_ssl_certificate *ne_ssl_clicert_owner(`const ne_ssl_client_cert *ccert`)`;`
``void ne_ssl_clicert_free(`ne_ssl_client_cert *ccert`)`;`

## Description

The `ne_ssl_clicert_read` function reads a client certificate from a PKCS#12-formatted file, and returns an ne_ssl_client_cert object. The `ne_ssl_clicert_import` function reads a client certificate from a memory buffer using the PKCS#12 format. The `ne_ssl_clicert_fromuri` function loads a client certificate from a URI. URI schemes supported are defined by the SSL/TLS toolkit, and may include PKCS#11 URIs.

A ne_ssl_client_cert 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: encrypted or decrypted. The `ne_ssl_clicert_encrypted` function will return non-zero if the client certificate is in the encrypted state.

A client certificate must be in the decrypted state before it is associated with a session. `ne_ssl_clicert_decrypt` 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.

A client certificate can be given a "friendly name" when it is created; `ne_ssl_clicert_name` will return this name (or `NULL` if no friendly name was specified). `ne_ssl_clicert_name` 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.

The function `ne_ssl_clicert_owner` returns the certificate part of the client certificate; it must only be called if the client certificate is in the decrypted state.

When the client certificate object is no longer needed, the `ne_ssl_clicert_free` function should be used to destroy the object.

## Return value

`ne_ssl_clicert_read`, `ne_ssl_clicert_import` and `ne_ssl_clicert_fromuri` all return a client certificate object, or `NULL` if the certificate could not be read/imported. `ne_ssl_clicert_encrypted` returns zero if the object is in the decrypted state, or non-zero if it is in the encrypted state. `ne_ssl_clicert_name` returns a `NUL`-terminated friendly name string, or `NULL`. `ne_ssl_clicert_owner` returns a certificate object.

## Examples

The following code reads a client certificate and decrypts it if necessary, then loads it into an HTTP session.

    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);

## History

`ne_ssl_clicert_import` was added in neon 0.30.0. `ne_ssl_clicert_fromuri` was added in neon 0.35.0.

## See also

ne_ssl_cert_read

Prev | Up | Next
ne_sock_handshake | Home | ne_status