— Function: const unsigned char * ksba_cert_get_image (ksba_cert_t cert, size_t *r_length)

This function returns a pointer to the DER encoded buffer with the raw certificate. The length of that buffer gets stored at r_length. This function is useful to export or store the raw certificate.

The function returns NULL on error or a pointer to a buffer with the raw certificate data. That pointer is only valid as long as the certificate object cert is valid and has not been reinitialized.

— Function: gpg_error_t ksba_cert_hash (ksba_cert_t cert, int what, void (*hasher)(void *, const void *, size_t length), void *hasher_arg)

This function feeds the data which is expected to be hashed into the supplied function hasher, where the first argument passed is hasher_arg, the second the pointer to the data to be hashed and the third the length of this data.

The function returns 0 on success or an error code when something goes wrong. The hasher function is not expected to return an error; instead the caller should setup that function in a way to convey encountered errors by means of the hasher_arg. Note that a hash function is in general not expected to yield errors anyway.

— Function: const char * ksba_cert_get_digest_algo (ksba_cert_t cert)

Figure out the the digest algorithm used for the signature and return its OID in dotted decimal format. This function is most likely used to setup the hash context before calling ksba_cert_hash.

The function returns NULL for an error; on success a constant string with the OID is returned. This string is valid as long the certificate object is valid.

— Function: ksba_sexp_t ksba_cert_get_serial (ksba_cert_t cert)

The function returns the serial number of the certificate cert. The serial number is an integer returned as an canonical encoded S-expression with just one element. The caller must free the returned value. The value NULL is returned in case of error.

— Function: char * ksba_cert_get_issuer (ksba_cert_t cert, int idx)

With idx given as 0, this function returns the Distinguished Name (DN) of the certificate issuer; this usually is the name of a certification authority (CA). The format of the returned string is in accordance with RFC-2253. NULL is returned if the DN is not available; This is a severe error and actually should have been caught by the certificate reading function.

With idx greater than zero, the function may be used to enumerate alternate issuer names. The function returns NULL when there are no more alternate names. Only alternate names recognized by libksba are returned, others are simply skipped. The format of the returned name is either a RFC-2253 formated string which can be detected by checking whether the first character is a letter or digit. RFC-822 conformant email addresses are returned enclosed in angle brackets; the opening angle bracket should be used to detect this. Other formats are returned as an S-Expression in canonical format, so a opening parenthesis should be used to detect this encoding. The name may include binary null characters, thus strlen may return a length shorter than actually used. The real length is implicitly given by the structure of the S-expression, an extra null is appended for safety reasons.

The caller must free the returned string using ksba_free or whatever function has been registered as a replacement.

— Function: char * ksba_cert_get_subject (ksba_cert_t cert, int idx)

With idx given as 0, this function returns the Distinguished Name (DN) of the certificate's subject. The format of the returned string is in accordance with RFC-2253. NULL is returned if the DN is not available.

With idx greater than zero, the function may be used to enumerate alternate subject names. The function returns NULL when there are no more alternate names. Only alternate names recognized by libksba are returned, others are simply skipped. The format of the returned name is either a RFC-2253 formated string which can be detected by checking whether the first character is a letter or digit. RFC-2822 conform email addresses are returned enclosed in angle brackets; the opening angle bracket should be used to detect this. Other formats are returned as an S-Expression in canonical format, so a opening parenthesis should be used to detect this encoding, the name may include binary null characters, thus strlen may return a length shorter than actually used. The real length is implicitly given by the structure of the S-expression, an extra null is appended for safety reasons.

The caller must free the returned string using ksba_free or whatever function has been registered as a replacement.

— Data type: ksba_isotime_t

Due to problems with the C data type time_t, which will overflow on most 32 bit machines in the year 2038, it was not advisable to use this type for referencing times stored in certificates. Instead, you should use the ksba_isotime_t type, which can represent any time since the year 0.

It is implemented as a buffer of 16 bytes and may be handled like a standard string. It should be initialized to zero (i.e. the first byte needs to be 0x00) if it does not hold a valid date. Date values themselves are stored in ISO format and assumed to be referenced from UTC. The string with the date value is always guaranteed to be of length 15 and having a format like: ‘"19610711T172059"’. Note that the `T' is required by ISO rules.

A simple assignment of these data types is not a good idea. You may use strcpy or better a specialized function like:

          void
          copy_time (ksba_isotime_t d, const ksba_isotime_t s)
          {
            if (!*s)
              memset (d, 0, 16);
            else
              strcpy (d, s);
          }

For reasons of documentation a special function should also be used to compare such times:

          int
          cmp_time (const ksba_isotime_t a, const ksba_isotime_t b)
          {
            return strcmp (a, b);
          }

— Function: gpg_error_t ksba_cert_get_validity (ksba_cert_t cert, int what, ksba_isotime_t timebuf)

Return the validity dates from the certificate. If no value is available an empty date object (i.e. a strlen will be stored at timebuf, otherwise it will receive the date. On failure an error code is returned.

To return the `notBefore' date, the value 0 must be supplied for what; 1 yields the `notAfter' value.

— Function: ksba_sexp_t ksba_cert_get_public_key (ksba_cert_t cert)

[This needs to get written - for now please see libksba/src/cert.c]

— Function: ksba_sexp_t ksba_cert_get_sig_val (ksba_cert_t cert)

[This needs to get written - for now please see libksba/src/cert.c]

— Function: gpg_error_t ksba_cert_get_extension (ksba_cert_t cert, int idx, char const **r_oid, int *r_crit, size_t *r_deroff, size_t *r_derlen)

[This needs to get written - for now please see libksba/src/cert.c]

— Function: gpg_error_t ksba_cert_is_ca (ksba_cert_t cert, int *r_ca, int *r_pathlen)

Return information on the basicConstraint (2.5.19.19) of CERT. R_CA receives true if this is a CA and only in that case R_PATHLEN is set to the maximum certification path length or -1 if there is no such limitation

— Function: gpg_error_t ksba_cert_get_key_usage (ksba_cert_t cert, unsigned int *r_flags)

Get the key usage flags. The function returns GPG_ERR_NO_DATA if no key usage is specified. The usage flags are as shown in RFC3280, section 4.2.1.3. The key usage flags are represented by a bitmask, and you can test each bit using symbolic constants, which tells you if that usage is set on the certificate. The constants are

KSBA_KEYUSAGE_DIGITAL_SIGNATURE

Usable for digitalSignature.

KSBA_KEYUSAGE_NON_REPUDIATION

Usable for nonRepudiation.

KSBA_KEYUSAGE_KEY_ENCIPHERMENT

Usable for keyEncipherment.

KSBA_KEYUSAGE_DATA_ENCIPHERMENT

Usable for dataEncipherment.

KSBA_KEYUSAGE_KEY_AGREEMENT

Usable for for keyAgreement.

KSBA_KEYUSAGE_KEY_CERT_SIGN

Usable for keyCertSign.

KSBA_KEYUSAGE_CRL_SIGN

Usable for cRLSign.

KSBA_KEYUSAGE_ENCIPHER_ONLY

Usable for encipherOnly.

KSBA_KEYUSAGE_DECIPHER_ONLY

Usable for decipherOnly.

These are the basic constraints on usage of a certificate. If you need to get additional constraints, see ksba_cert_get_ext_key_usages.

— Function: gpg_error_t ksba_cert_get_ext_key_usages (ksba_cert_t cert, char **result)

Return a string containing the extended usages for the certificate, delimited by linefeeds.

— Function: gpg_error_t ksba_cert_get_cert_policies (ksba_cert_t cert, char **r_policies)

Return a string with the certificatePolicies delimited by linefeeds. The return values may be extended to carry more information per line, so the caller should only use the first white-space delimited token per line. The function returns GPG_ERR_NO_DATA when this extension is not used. Caller must free the returned value.

— Function: gpg_error_t ksba_cert_get_crl_dist_point (ksba_cert_t cert, int idx, ksba_name_t *r_distpoint, ksba_name_t *r_issuer, unsigned int *r_reason)

Return the CRLDistPoints given in the certificate extension of certificate cert. idx should be iterated starting from 0 until the function returns GPG_ERR_EOF. r_distpoint returns a ksba_name_t object with the distribution point name(s); the return value may be NULL to indicate that this name is not available. r_issuer returns the CRL issuer; if the returned value is NULL the caller should assume that the CRL issuer is the same as the certificate issuer. r_reason returns the reason for the CRL. This is a bit encoded value with no bit set if no reason has been specified in the certificate.

The caller may pass NULL to any of the pointer arguments if he is not interested in this value. The return values for r_distpoint and r_issuer must be released by the caller using ksba_name_release.

— Function: gpg_error_t ksba_cert_get_subj_key_id (ksba_cert_t cert, int *r_crit, ksba_sexp_t *r_keyid)

Return the subjectKeyIdentifier extension as a simple allocated S-expression at the address of r_keyid. 0 is returned on success, GPG_ERR_NO_DATA if no such extension is available or any other error code. If r_crit is not passed as NULL, the critical flag of this is extension is stored at this address.

— Function: gpg_error_t ksba_cert_get_auth_key_id (ksba_cert_t cert, ksba_sexp_t *r_keyid, ksba_name_t *r_name, ksba_sexp_t *r_serial)

Return the authorityKeyIdentifier in r_name and r_serial or in r_keyid. GPG_ERR_NO_DATA is returned if no authorityKeyIdentifier has been found. This error code is also returned if r_keyid has been given as NULL and only an authorityKeyIdentifier with the keyIdentifier method is available.

— Function: gpg_error_t ksba_cert_get_authority_info_access (ksba_cert_t cert, int idx, char **r_method, ksba_name_t *r_location)

Return the authorityInfoAccess attributes. idx should be iterated starting from 0 until this function returns GPG_ERR_EOF. r_method returns an allocated string with the OID of one item and r_location returns the GeneralName for that OID. The returned values for r_method and r_location must be released by the caller unless the function returned an error; the function will however make sure that r_method and r_location will point to NULL if the function returns an error.

See RFC-2459, section 4.2.2.1 for the definition of this attribute.

— Function: gpg_error_t ksba_cert_get_subject_info_access (ksba_cert_t cert, int idx, char **r_method, ksba_name_t *r_location)

Return the subjectInfoAccess attributes. idx should be iterated starting from 0 until this function returns GPG_ERR_EOF. r_method returns an allocated string with the OID of one item and r_location returns the GeneralName for that OID. The returned values for r_method and r_location must be released by the caller unless the function returned an error; the function will however make sure that r_method and r_location will point to NULL if the function returns an error.

See RFC-2459, section 4.2.2.2 for the definition of this attribute.