TrustedQSL Library 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. | |
Certificates are managed by manipulating tQSL_Cert
objects. A tQSL_Cert
contains:
The certificate management process consists of:
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 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.
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.
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.
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). 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.
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.
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_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.
idx
is the index, 0 <= idx < tqsl_getNumProviders() 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 returnedReturns 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_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().
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().