Previous: Setting attributes, Up: Certificate Handling

3.4 How to associate other data with a certificate.

Certificate objects play a central role in many applications and often it is desirable to associate other data with the certificate to avoid wrapping the certificate object into an own object. `KSBA' provides a mechanism for this by means of two functions:

— Function: gpg_error_t ksba_cert_set_user_data (ksba_cert_t cert, const char *key, const void *data, size_t datalen)

Stores arbitrary data along with a certificate. The data is expected in the buffer data of length datalen. It will be stored under the string key. If data is already stored under this key it will be replaced by the new data. Using NULL for data will effectively delete the data.

On error (i.e. out of memory) an already existing data object stored under key may get deleted.

Caution: This function is definitely not thread safe because we don't employ any locking mechanisms.

— Function: gpg_error_t ksba_cert_get_user_data (ksba_cert_t cert, const char *key, void *buffer, size_t bufferlen, size_t *datalen)

Return user data for certificate cert stored under the string key. The caller needs to provide a suitable large buffer and the usable length of this buffer in bufferlen. If datalen is not NULL, the length of the data stored in buffer will be stored there.

If buffer is given as NULL, bufferlen will be ignored and the required length of the buffer will be returned at datalen.

On success 0 is returned. If no data is stored under the given key, GPG_ERR_NOT_FOUND is returned. If the provided buffer is too short and buffer is not NULL, GPG_ERR_BUFFER_TOO_SHORT will be returned.