Main Page | Modules | Class 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

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

DLLEXPORT 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.

DLLEXPORT int tqsl_deleteCertificate tQSL_Cert  cert  ) 
 

Delete a certificate and private key

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT int tqsl_getCertificateEncoded tQSL_Cert  cert,
char *  buf,
int  bufsiz
 

Get the encoded certificate for inclusion in a GABBI file.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT int tqsl_getCertificateKeyOnly tQSL_Cert  cert,
int *  keyonly
 

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

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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).

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT 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.

DLLEXPORT int tqsl_getCertificateSerial tQSL_Cert  cert,
long *  serial
 

Get the issuer's serial number of the certificate.

DLLEXPORT int tqsl_getNumProviders int *  n  ) 
 

Get the number of certificate providers known to tqsllib.

DLLEXPORT int tqsl_getProvider int  idx,
TQSL_PROVIDER provider
 

Get the information for a certificate provider.

DLLEXPORT int tqsl_getSelectedCertificate tQSL_Cert *  cert,
const tQSL_Cert **  certlist,
int  idx
 

Get a particulat certificate from the list returnded by tqsl_selectCertificates. This function exists principally to make it easier for VB programs to access the list of certificates.

It is the caller's responsibility to ensure that 0 <= idx < ncerts (where ncerts is the value returned by tqsl_selectCertificates)

DLLEXPORT 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.

DLLEXPORT 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

DLLEXPORT 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 on Tue Feb 22 08:15:36 2005 for TrustedQSL Library API by doxygen 1.3.4