TrustedQSL Library API: Certificate Handling API

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 identity of the organization that issued the certificate (the "issuer").
- The name and call sign of the amateur radio operator (ARO).
- The DXCC entity number for which this certificate is valid.
- The range of QSO dates for which this certificate can be used.
- The resources needed to digitally sign and verify QSO records.

The certificate management process consists of:

- Applying for a certificate. Certificate requests are produced via the tqsl_createCertRequest() function, which produces a certificate-request file to send to the issuer.
- Importing the certificate file received from the issuer into the local "certificate store," a directory managed by the tQSL library, via tqsl_importTQSLFile().
- Selecting an appropriate certificate to use to sign a QSO record via tqsl_selectCertificates().

## Function Documentation

## ◆ tqsl_createCertRequest()

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.

## ◆ tqsl_deleteCertificate()

DLLEXPORT int CALLCONVENTION tqsl_deleteCertificate | ( | tQSL_Cert | cert | ) |

Delete a certificate and private key

## ◆ tqsl_exportPKCS12Base64()

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.

## ◆ tqsl_exportPKCS12File()

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.

## ◆ tqsl_freeCertificate()

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.

## ◆ tqsl_freeCertificateList()

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.

## ◆ tqsl_freeDeletedCertificateList()

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

Free the list of restorable Callsign Certificates.

## ◆ tqsl_getCertificateAROName()

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.

## ◆ tqsl_getCertificateCallSign()

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.

## ◆ tqsl_getCertificateDXCCEntity()

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.

## ◆ tqsl_getCertificateEmailAddress()

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.

## ◆ tqsl_getCertificateEncoded()

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

Get the encoded certificate for inclusion in a GABBI file.

## ◆ tqsl_getCertificateIssuer()

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.

## ◆ tqsl_getCertificateIssuerOrganization()

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.

## ◆ tqsl_getCertificateIssuerOrganizationalUnit()

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.

## ◆ tqsl_getCertificateKeyOnly()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateKeyOnly | ( | tQSL_Cert | cert,
|  | int * | keyonly
| ) |  |

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

## ◆ tqsl_getCertificateNotAfterDate()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotAfterDate | ( | tQSL_Cert | cert,
|  | tQSL_Date * | date
| ) |  |

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

- `cert` - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
- `date` - Pointer to a tQSL_Date struct to hold the returned date.

Returns 0 on success, nonzero on failure.

## ◆ tqsl_getCertificateNotBeforeDate()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotBeforeDate | ( | tQSL_Cert | cert,
|  | tQSL_Date * | date
| ) |  |

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

- `cert` - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
- `date` - Pointer to a tQSL_Date struct to hold the returned date.

Returns 0 on success, nonzero on failure.

## ◆ tqsl_getCertificatePrivateKeyType()

DLLEXPORT int CALLCONVENTION tqsl_getCertificatePrivateKeyType | ( | tQSL_Cert | cert | ) |

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

- `cert` - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()

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

## ◆ tqsl_getCertificateQSONotAfterDate()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotAfterDate | ( | tQSL_Cert | cert,
|  | tQSL_Date * | date
| ) |  |

Get the QSO not-after date from a tQSL_Cert.

- `cert` - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
- `date` - Pointer to a tQSL_Date struct to hold the returned date.

Returns 0 on success, nonzero on failure.

## ◆ tqsl_getCertificateQSONotBeforeDate()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotBeforeDate | ( | tQSL_Cert | cert,
|  | tQSL_Date * | date
| ) |  |

Get the QSO not-before date from a tQSL_Cert.

- `cert` - a tQSL_Cert object, normally one returned from tqsl_selectCertificates()
- `date` - Pointer to a tQSL_Date struct to hold the returned date.

Returns 0 on success, nonzero on failure.

## ◆ tqsl_getCertificateRequestAddress1()

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.

## ◆ tqsl_getCertificateRequestAddress2()

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.

## ◆ tqsl_getCertificateRequestCity()

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.

## ◆ tqsl_getCertificateRequestCountry()

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.

## ◆ tqsl_getCertificateRequestPostalCode()

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.

## ◆ tqsl_getCertificateRequestState()

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.

## ◆ tqsl_getCertificateSerial()

DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerial | ( | tQSL_Cert | cert,
|  | long * | serial
| ) |  |

Get the issuer's serial number of the certificate.

## ◆ tqsl_getCertificateSerialExt()

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

## ◆ tqsl_getCertificateSerialLength()

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.

## ◆ tqsl_getCertificateStatus()

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

## ◆ tqsl_getDeletedCallsignCertificates()

DLLEXPORT int CALLCONVENTION tqsl_getDeletedCallsignCertificates | ( | char *** | calls,
|  | int * | ncall,
|  | const char * | filter
| ) |  |

Get the list of restorable station locations.

## ◆ tqsl_getKeyEncoded()

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

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

## ◆ tqsl_getNumProviders()

DLLEXPORT int CALLCONVENTION tqsl_getNumProviders | ( | int * | n | ) |

Get the number of certificate providers known to tqsllib.

## ◆ tqsl_getProvider()

DLLEXPORT int CALLCONVENTION tqsl_getProvider | ( | int | idx,
|  | TQSL_PROVIDER * | provider
| ) |  |

Get the information for a certificate provider.

- `idx` is the index, 0 <= idx < tqsl_getNumProviders()

## ◆ tqsl_getSelectedCertificate()

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)

## ◆ tqsl_getSerialFromTQSLFile()

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.

## ◆ tqsl_importKeyPairEncoded()

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.

## ◆ tqsl_importPKCS12Base64()

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.

## ◆ tqsl_importPKCS12File()

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.

## ◆ tqsl_importTQSLFile()

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`

## ◆ tqsl_isCertificateExpired()

DLLEXPORT int CALLCONVENTION tqsl_isCertificateExpired | ( | tQSL_Cert | cert,
|  | int * | status
| ) |  |

Find out if the "certificate" is expired

## ◆ tqsl_isCertificateSuperceded()

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

Find out if the "certificate" is superceded

## ◆ tqsl_restoreCallsignCertificate()

DLLEXPORT int CALLCONVENTION tqsl_restoreCallsignCertificate | ( | const char * | callsign | ) |

Restore a deleted callsign certificate by callsign.

## ◆ tqsl_selectCACertificates()

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.

## ◆ tqsl_selectCertificates()

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.

## ◆ tqsl_setCertificateStatus()

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.