Main Page   Modules   Compound List   File List   File Members  

Certificate Handling API


Defines

#define TQSL_SELECT_CERT_WITHKEYS   1
#define TQSL_SELECT_CERT_EXPIRED   2
#define TQSL_SELECT_CERT_SUPERCEDED   4
#define TQSL_PK_TYPE_ERR   0
#define TQSL_PK_TYPE_NONE   1
#define TQSL_PK_TYPE_UNENC   2
#define TQSL_PK_TYPE_ENC   3

Functions

int tqsl_selectCertificates (tQSL_Cert **certlist, int *ncerts, const char *callsign, int dxcc, const tQSL_Date *date, const TQSL_PROVIDER *issuer, int flag)
int tqsl_getCertificateKeyOnly (tQSL_Cert cert, int *keyonly)
int tqsl_getCertificateEncoded (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateSerial (tQSL_Cert cert, long *serial)
int tqsl_getCertificateIssuer (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateIssuerOrganization (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateIssuerOrganizationalUnit (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateCallSign (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateAROName (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateEmailAddress (tQSL_Cert cert, char *buf, int bufsiz)
int tqsl_getCertificateQSONotBeforeDate (tQSL_Cert cert, tQSL_Date *date)
int tqsl_getCertificateQSONotAfterDate (tQSL_Cert cert, tQSL_Date *date)
int tqsl_getCertificateNotBeforeDate (tQSL_Cert cert, tQSL_Date *date)
int tqsl_getCertificateNotAfterDate (tQSL_Cert cert, tQSL_Date *date)
int tqsl_getCertificateDXCCEntity (tQSL_Cert cert, int *dxcc)
int tqsl_getCertificateRequestAddress1 (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificateRequestAddress2 (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificateRequestCity (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificateRequestState (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificateRequestPostalCode (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificateRequestCountry (tQSL_Cert cert, char *str, int bufsiz)
int tqsl_getCertificatePrivateKeyType (tQSL_Cert cert)
void tqsl_freeCertificate (tQSL_Cert cert)
int tqsl_importTQSLFile (const char *file, int(*cb)(int type, const char *message, void *userdata), void *user)
int tqsl_getNumProviders (int *n)
int tqsl_getProvider (int idx, TQSL_PROVIDER *provider)
int tqsl_createCertRequest (const char *filename, TQSL_CERT_REQ *req, int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user)
int tqsl_exportPKCS12File (tQSL_Cert cert, const char *filename, const char *p12password)
int tqsl_importPKCS12File (const char *filename, const char *p12password, const char *password, int(*pwcb)(char *buf, int bufsiz, void *userdata), int(*cb)(int type, const char *message, void *userdata), void *user)
int tqsl_deleteCertificate (tQSL_Cert cert)

Detailed Description

Certificates are managed by manipulating tQSL_Cert objects. A tQSL_Cert contains:

The certificate management process consists of:


Function Documentation

int tqsl_createCertRequest ( const char * filename,
TQSL_CERT_REQ * req,
int(* pwcb)(char *pwbuf, int pwsize, void *userdata),
void * user )
 

Create a certificate-request Gabbi file.

The req parameter must be properly populated with the required fields.

If req->password is NULL and cb is not NULL, the callback will be called to acquire the password. Otherwise req->password will be used as the password. If the password is NULL or an empty string the generated private key will be stored unencrypted.

If req->signer is not zero and the signing certificate requires a password, the password may be in req->signer_password, else signer_pwcb is called.

int tqsl_deleteCertificate ( tQSL_Cert cert )
 

Delete a certificate and private key

int tqsl_exportPKCS12File ( tQSL_Cert cert,
const char * filename,
const char * p12password )
 

Save a key pair and certificates to a file in PKCS12 format.

The tQSL_Cert must be initialized for signing (see tqsl_beginSigning()) if the user certificate is being exported.

The supplied p12password is used to encrypt the PKCS12 data.

void tqsl_freeCertificate ( tQSL_Cert cert )
 

Free the memory used by the tQSL_Cert. Once this function is called, cert should not be used again in any way.

int tqsl_getCertificateAROName ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the ARO name string from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateCallSign ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the ARO call sign string from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateDXCCEntity ( tQSL_Cert cert,
int * dxcc )
 

Get the DXCC entity number from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • dxcc - Pointer to an int to hold the returned date.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateEmailAddress ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the email address from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateEncoded ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the encoded certificate for inclusion in a GABBI file.

int tqsl_getCertificateIssuer ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the issuer (DN) string from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateIssuerOrganization ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the issuer's organization name from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateIssuerOrganizationalUnit ( tQSL_Cert cert,
char * buf,
int bufsiz )
 

Get the issuer's organizational unit name from a tQSL_Cert.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateKeyOnly ( tQSL_Cert cert,
int * keyonly )
 

Find out if the "certificate" is just a key pair.

int tqsl_getCertificateNotAfterDate ( tQSL_Cert cert,
tQSL_Date * date )
 

Get the certificate's not-after date from a tQSL_Cert.

Returns 0 on success, nonzero on failure.

int tqsl_getCertificateNotBeforeDate ( tQSL_Cert cert,
tQSL_Date * date )
 

Get the certificate's not-before date from a tQSL_Cert.

Returns 0 on success, nonzero on failure.

int tqsl_getCertificatePrivateKeyType ( tQSL_Cert cert )
 

Determine the nature of the private key associated with a certificate.

Returns one of the following values:

  • TQSL_PK_TYPE_ERR - An error occurred. Use tqsl_getErrorString() to examine.
  • TQSL_PK_TYPE_NONE - No matching private key was found.
  • TQSL_PK_TYPE_UNENC - The matching private key is unencrypted.
  • TQSL_PK_TYPE_ENC - The matching private key is encrypted (password protected).

int tqsl_getCertificateQSONotAfterDate ( tQSL_Cert cert,
tQSL_Date * date )
 

Get the QSO not-after date from a tQSL_Cert.

Returns 0 on success, nonzero on failure.

int tqsl_getCertificateQSONotBeforeDate ( tQSL_Cert cert,
tQSL_Date * date )
 

Get the QSO not-before date from a tQSL_Cert.

Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestAddress1 ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the first address line from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestAddress2 ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the second address line from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestCity ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the city from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestCountry ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the country from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestPostalCode ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the postal (ZIP) code from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateRequestState ( tQSL_Cert cert,
char * str,
int bufsiz )
 

Get the state from the certificate request used in applying for a tQSL_Cert certificate.

  • cert - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
  • buf - Buffer to hold the returned string.
  • bufsiz - Size of buf.
Returns 0 on success, nonzero on failure.

int tqsl_getCertificateSerial ( tQSL_Cert cert,
long * serial )
 

Get the issuer's serial number of the certificate.

int tqsl_getNumProviders ( int * n )
 

Get the number of certificate providers known to tqsllib.

int tqsl_getProvider ( int idx,
TQSL_PROVIDER * provider )
 

Get the information for a certificate provider.

int tqsl_importPKCS12File ( const char * filename,
const char * p12password,
const char * password,
int(* pwcb)(char *buf, int bufsiz, void *userdata),
int(* cb)(int type, const char *message, void *userdata),
void * user )
 

Load certificates and a private key from a PKCS12 file.

int tqsl_importTQSLFile ( const char * file,
int(* cb)(int type, const char *message, void *userdata),
void * user )
 

Import a Gabbi cert file received from a CA

The callback, cb, will be called whenever a certificate is ready to be imported:

cb(type, message);

type has several fields that can be accessed via macros:

TQSL_CERT_CB_CALL_TYPE(type) := TQSL_CERT_CB_MILESTONE | TQSL_CERT_CB_RESULT

TQSL_CERT_CB_CERT_TYPE(type) := TQSL_CERT_CB_ROOT | TQSL_CERT_CB_CA | TQSL_CERT_CB_USER

TQSL_CERT_CB_RESULT_TYPE(type) := TQSL_CERT_CB_PROMPT | TQSL_CERT_CB_WARNING | TQSL_CERT_CB_ERROR

TQSL_CERT_CB_RESULT_TYPE() is meaningful only if TQSL_CERT_CB_CALL_TYPE() == TQSL_CERT_CB_RESULT

int tqsl_selectCertificates ( tQSL_Cert ** certlist,
int * ncerts,
const char * callsign,
int dxcc,
const tQSL_Date * date,
const TQSL_PROVIDER * issuer,
int flag )
 

Get a list of certificates

Selects a set of certificates from the user's certificate store based on optional selection criteria. The function produces a list of tQSL_Cert objects.

  • certlist - Pointer to a variable that is set by the function to point to the list of tQSL_Cert objects.
  • ncerts - Pointer to an int that is set to the number of objects in the certlist list.
  • callsign - Optional call sign to match.
  • date - Optional QSO date string in ISO format. Only certs that have a QSO date range that encompasses this date will be returned.
  • issuer - Optional issuer (DN) string to match.
  • flag - OR of TQSL_SELECT_CERT_EXPIRED (include expired certs), TQSL_SELECT_CERT_SUPERCEDED and TQSL_SELECT_CERT_WITHKEYS (keys that don't have associated certs will be returned).
Returns 0 on success, nonzero on failure.

Each of the tQSL_Cert objects in the list should be freed by calling tqsl_freeCertificate().


Generated at Tue Oct 21 04:59:43 2003 for TrustedQSL Library API by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001