TrustedQSL Library API
Macros | Functions
Certificate Handling API

Macros

#define TQSL_SELECT_CERT_WITHKEYS   1
 Private keys only (no cert)
 
#define TQSL_SELECT_CERT_EXPIRED   2
 Include expired certs.
 
#define TQSL_SELECT_CERT_SUPERCEDED   4
 Include superseded certs.
 
#define TQSL_PK_TYPE_ERR   0
 Error retrieving private key.
 
#define TQSL_PK_TYPE_NONE   1
 No private key.
 
#define TQSL_PK_TYPE_UNENC   2
 Private key is not encrypted.
 
#define TQSL_PK_TYPE_ENC   3
 Private key is encrypted.
 
#define TQSL_CERT_STATUS_UNK   0
 Status is unknown.
 
#define TQSL_CERT_STATUS_SUP   1
 Certificate is superceded.
 
#define TQSL_CERT_STATUS_EXP   2
 Certificate is expired.
 
#define TQSL_CERT_STATUS_OK   3
 Certificate is valid.
 
#define TQSL_CERT_STATUS_INV   4
 Invalid serial number.
 

Functions

DLLEXPORT int CALLCONVENTION tqsl_selectCertificates (tQSL_Cert **certlist, int *ncerts, const char *callsign, int dxcc, const tQSL_Date *date, const TQSL_PROVIDER *issuer, int flag)
 
DLLEXPORT int CALLCONVENTION tqsl_selectCACertificates (tQSL_Cert **certlist, int *ncerts, const char *type)
 
DLLEXPORT int CALLCONVENTION tqsl_getSelectedCertificate (tQSL_Cert *cert, const tQSL_Cert **certlist, int idx)
 
DLLEXPORT int CALLCONVENTION tqsl_isCertificateExpired (tQSL_Cert cert, int *status)
 
DLLEXPORT int CALLCONVENTION tqsl_isCertificateSuperceded (tQSL_Cert cert, int *status)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateKeyOnly (tQSL_Cert cert, int *keyonly)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateEncoded (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getKeyEncoded (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_importKeyPairEncoded (const char *callsign, const char *type, const char *keybuf, const char *certbuf)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerial (tQSL_Cert cert, long *serial)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialExt (tQSL_Cert cert, char *serial, int serialsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialLength (tQSL_Cert cert)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuer (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganization (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganizationalUnit (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateCallSign (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateAROName (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateEmailAddress (tQSL_Cert cert, char *buf, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotBeforeDate (tQSL_Cert cert, tQSL_Date *date)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotAfterDate (tQSL_Cert cert, tQSL_Date *date)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotBeforeDate (tQSL_Cert cert, tQSL_Date *date)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotAfterDate (tQSL_Cert cert, tQSL_Date *date)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateDXCCEntity (tQSL_Cert cert, int *dxcc)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress1 (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress2 (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCity (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestState (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestPostalCode (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCountry (tQSL_Cert cert, char *str, int bufsiz)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificatePrivateKeyType (tQSL_Cert cert)
 
DLLEXPORT void CALLCONVENTION tqsl_freeCertificate (tQSL_Cert cert)
 
DLLEXPORT void CALLCONVENTION tqsl_freeCertificateList (tQSL_Cert *list, int ncerts)
 
DLLEXPORT int CALLCONVENTION tqsl_getCertificateStatus (long serial)
 
DLLEXPORT int CALLCONVENTION tqsl_setCertificateStatus (long serial, const char *status)
 
DLLEXPORT int CALLCONVENTION tqsl_importTQSLFile (const char *file, int(*cb)(int type, const char *message, void *userdata), void *user)
 
DLLEXPORT int CALLCONVENTION tqsl_getSerialFromTQSLFile (const char *file, long *serial)
 
DLLEXPORT int CALLCONVENTION tqsl_getNumProviders (int *n)
 
DLLEXPORT int CALLCONVENTION tqsl_getProvider (int idx, TQSL_PROVIDER *provider)
 
DLLEXPORT int CALLCONVENTION tqsl_createCertRequest (const char *filename, TQSL_CERT_REQ *req, int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user)
 
DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12File (tQSL_Cert cert, const char *filename, const char *p12password)
 
DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12Base64 (tQSL_Cert cert, char *base64, int b64len, const char *p12password)
 
DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_importPKCS12Base64 (const char *base64, 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 CALLCONVENTION tqsl_getDeletedCallsignCertificates (char ***calls, int *ncall, const char *filter)
 
DLLEXPORT void CALLCONVENTION tqsl_freeDeletedCertificateList (char **list, int nloc)
 
DLLEXPORT int CALLCONVENTION tqsl_restoreCallsignCertificate (const char *callsign)
 
DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_createCertRequest ( const char *  filename,
TQSL_CERT_REQ req,
int(*)(char *pwbuf, int pwsize, void *userdata)  pwcb,
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 CALLCONVENTION tqsl_deleteCertificate ( tQSL_Cert  cert)

Delete a certificate and private key

DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12Base64 ( tQSL_Cert  cert,
char *  base64,
int  b64len,
const char *  p12password 
)

Save a key pair and certificates to a Base64 string 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 int CALLCONVENTION 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 CALLCONVENTION 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 void CALLCONVENTION tqsl_freeCertificateList ( tQSL_Cert list,
int  ncerts 
)

Free the memory used by a certificate list. The allocated list of tQSL_Certs are freed and the pointer array is freed. Once this function is called, the list or the cert should not be used again in any way.

DLLEXPORT void CALLCONVENTION tqsl_freeDeletedCertificateList ( char **  list,
int  nloc 
)

Free the list of restorable Callsign Certificates.

DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getCertificateEncoded ( tQSL_Cert  cert,
char *  buf,
int  bufsiz 
)

Get the encoded certificate for inclusion in a GABBI file.

DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getCertificateKeyOnly ( tQSL_Cert  cert,
int *  keyonly 
)

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

DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getCertificateSerial ( tQSL_Cert  cert,
long *  serial 
)

Get the issuer's serial number of the certificate.

DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialExt ( tQSL_Cert  cert,
char *  serial,
int  serialsiz 
)

Get the issuer's serial number of the certificate as a hexadecimal string. Needed for certs with long serial numbers (typically root certs).

DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialLength ( tQSL_Cert  cert)

Get the length of the issuer's serial number of the certificate as it will be returned by tqsl_getCertificateSerialExt.

DLLEXPORT int CALLCONVENTION tqsl_getCertificateStatus ( long  serial)

Determine the status of a callsign certificate

  • serial - the serial number of the certificate tqsl_selectCertificates()
  • status - an integer to receive the certificate status

Returns one of the following values:

  • TQSL_CERT_STATUS_UNK - An error occurred and the status is unknown
  • TQSL_CERT_STATUS_SUP - The certificate has been superceded
  • TQSL_CERT_STATUS_EXP - The certificate has expired
  • TQSL_CERT_STATUS_OK - The certificate is valid
  • TQSL_CERT_STATUS_INV - The serial number supplied is invalid
DLLEXPORT int CALLCONVENTION tqsl_getDeletedCallsignCertificates ( char ***  calls,
int *  ncall,
const char *  filter 
)

Get the list of restorable station locations.

DLLEXPORT int CALLCONVENTION tqsl_getKeyEncoded ( tQSL_Cert  cert,
char *  buf,
int  bufsiz 
)

Get the encoded private key for inclusion in a backup file.

DLLEXPORT int CALLCONVENTION tqsl_getNumProviders ( int *  n)

Get the number of certificate providers known to tqsllib.

DLLEXPORT int CALLCONVENTION tqsl_getProvider ( int  idx,
TQSL_PROVIDER provider 
)

Get the information for a certificate provider.

DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_getSerialFromTQSLFile ( const char *  file,
long *  serial 
)

Get the serial for the first user cert from a .tq6 file used to support asking the user to save their cert after import

  • file is the path to the file
  • serial is where the serial number is returned

Returns 0 on success, nonzero on failure.

DLLEXPORT int CALLCONVENTION tqsl_importKeyPairEncoded ( const char *  callsign,
const char *  type,
const char *  keybuf,
const char *  certbuf 
)

Import a base64 encoded certificate and private key from a backup file.

DLLEXPORT int CALLCONVENTION tqsl_importPKCS12Base64 ( const char *  base64,
const char *  p12password,
const char *  password,
int(*)(char *buf, int bufsiz, void *userdata)  pwcb,
int(*)(int type, const char *message, void *userdata)  cb,
void *  user 
)

Load certificates and a private key from a Base64 encoded PKCS12 string.

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

Load certificates and a private key from a PKCS12 file.

DLLEXPORT int CALLCONVENTION tqsl_importTQSLFile ( const char *  file,
int(*)(int type, const char *message, void *userdata)  cb,
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 CALLCONVENTION tqsl_isCertificateExpired ( tQSL_Cert  cert,
int *  status 
)

Find out if the "certificate" is expired

DLLEXPORT int CALLCONVENTION tqsl_isCertificateSuperceded ( tQSL_Cert  cert,
int *  status 
)

Find out if the "certificate" is superceded

DLLEXPORT int CALLCONVENTION tqsl_restoreCallsignCertificate ( const char *  callsign)

Restore a deleted callsign certificate by callsign.

DLLEXPORT int CALLCONVENTION tqsl_selectCACertificates ( tQSL_Cert **  certlist,
int *  ncerts,
const char *  type 
)

Get a list of authority certificates

Selects a set of certificates from the root or authorities certificate stores The function produces a list of tQSL_Cert objects.

Each of the tQSL_Cert objects in the list should be freed by calling tqsl_freeCertificate(). tqsl_freeCertificateList() is a better function to use for that as it also frees the allocated array that holds the certificate pointers.

DLLEXPORT int CALLCONVENTION 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(). tqsl_freeCertificateList() is a better function to use for that as it also frees the allocated array that holds the certificate pointers.

DLLEXPORT int CALLCONVENTION tqsl_setCertificateStatus ( long  serial,
const char *  status 
)

Store the status of a callsign certificate

  • serial - serial number of the certificate
  • status - the status value to store.