neon API reference                          NESLCLIENTCERT(3)



NAME
     nesslclicertread,                    nesslclicertname,
     nesslclicertencrypted,            nesslclicertdecrypt,
     nesslclicertowner, nesslclicertfree - SL client  cer-
     tificate handling

SYNOPSIS
     #include 


     nesslclientcert *nesslclicertread (const char *filename);

     const char *nesslclicertname (const nesslclientcert *ccert);

     int nesslclicertencrypted (const nesslclientcert *ccert);

     int nesslclicertdecrypt (nesslclientcert *ccert,
                                 const char *password);

     const nesslcertificate *nesslclicertowner (const nesslclientcert *ccert);

     void nesslclicertfree (nesslclientcert *ccert);


DESCRIPTION
     The nesslclicertread function reads a client  certificate
     from    a    PKCS#12-formatted    file,   and   returns   an
     nesslclientcert object. If the client certificate is  en-
     crypted,  it  must  be  decrypted  before  it  is  used.  An
     nesslclientcert 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.


     A client certificate can be in one of two states:  encrypted
     or decrypted. The nesslclicertencrypted function will re-
     turn non-zero if the client certificate is in the  encrypted
     state.    A    client   certificate   object   returned   by
     nesslclicertread  may  be  initially  in  either   state,
     depending on whether the file was encrypted or not.


     nesslclicertdecrypt can be used to decrypt a client  cer-
     tificate  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;  nesslclicertname  will return this name (or



neon 0.25.5       Last change: 20 January 2006                  1






neon API reference                          NESLCLIENTCERT(3)



     NUL if no friendly name was specified). nesslclicertname
     can be used when the client certificate is in either the en-
     crypted or decrypted state, and will return the same  string
     for the lifetime of the object.


     The function nesslclicertowner  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  is  no  longer  needed,  the
     nesslclicertfree  function  should be used to destroy the
     object.


RETURN VALUE
     nesslclicertread returns a client certificate object,  or
     NUL if the file could not be read. nesslclicertencrypted
     returns zero if the object is in  the  decrypted  state,  or
     non-zero    if    it    is    in    the   encrypted   state.
     nesslclicertname returns a NUL-terminated  friendly  name
     string,  or NUL. nesslclicertowner returns a certificate
     object.


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

     nesslclientcert *ccert;

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

     if (ccert == NUL) {
        /* handle error... */
     } else if (nesslclicertencrypted(ccert)) {
        char *password = promptforpassword();

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

     nesslsetclicert(sess, ccert);



SEE ALSO
     nesslcertread(3)





neon 0.25.5       Last change: 20 January 2006                  2






neon API reference                          NESLCLIENTCERT(3)



AUTHOR
     Joe Orton .

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWneon       
    
     Interface Stability  Volatile       
    

NOTES
     Source for Neon is available on http:/opensolaris.org.






































neon 0.25.5       Last change: 20 January 2006                  3