/**
- * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
} CertSvcVisibility;
/**
- * This function will return certificate for the unique name identifier passed (gname).
+ * Get certificate with gname provided.
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to the store (WIFI_STORE, VPN_STORE, EMAIL_STORE, SSL_STORE).
- * @oaran[in] gname Refers to the unique name identifier associated for the certificate.
- * @param[out] certificate Certificate for the gname passed.
- * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @oaran[in] gname Single certificate identifier
+ * @param[out] certificate Must be freed by certsvc_certificate_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_certificate_free()
+ * @see #CertStoreType
+ * @see #CertSvcCertificate
*/
int certsvc_get_certificate(CertSvcInstance instance,
CertStoreType storeType,
CertSvcCertificate *certificate);
/**
- * Read certificate from file. Certificate must be in PEM/CER/DER format.
+ * Load certificate to @a CertSvcCertificate from file.
+ * Certificate must be in PEM/CER/DER format.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] location Path of file to load
+ * @param[out] certificate Certificate id assigned to loaded certificate
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] location Path to file with certificate file.
- * @param[out] certificate Certificate id assigned to loaded certificate.
- * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_certificate_free()
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_new_from_file(CertSvcInstance instance,
const char *location,
CertSvcCertificate *certificate);
/**
- * Read certificate stored in memory.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] memory Pointer to memory with certificate data.
- * @param[in] len Size of certificate.
- * @param[in] form Certificate format.
- * @param[out] certificate Certificate id assigned to loaded certificate.
- * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL
+ * Load certificate to @a CertSvcCertificate from memory.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] memory Pointer to memory with certificate data
+ * @param[in] len Size of certificate in @a memory
+ * @param[in] form Certificate format in @a memory
+ * @param[out] certificate Must be freed by certsvc_certificate_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_certificate_free()
+ * @see #CertSvcCertificate
+ * @see #CertSvcCertificateForm
*/
int certsvc_certificate_new_from_memory(CertSvcInstance instance,
const unsigned char *memory,
/**
* Free structures connected with certificate.
*
- * @param[in] certificate Certificate id.
+ * @param[in] certificate Certificate to free
*/
void certsvc_certificate_free(CertSvcCertificate certificate);
/**
- * Save certificate to file. It saves certificate in DER format.
+ * Save certificate to file in @a location in DER format.
+ *
+ * @param[in] certificate Certificate
+ * @param[in] location Location
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*
- * @param[in] certificate Certificate id.
- * @param[in] location Path to file.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_save_file(CertSvcCertificate certificate, const char *location);
*
* You can search by fields: CERTSVC_SUBJECT, CERTSVC_ISSUER, CERTSVC_SUBJECT_COMMON_NAME
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] field Certificate filed name.
- * @param[in] value Value to search for.
- * @param[out] handler Handler to search result.
- * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] instance CertSvcInstance object
+ * @param[in] field Certificate field to find with
+ * @param[in] value Value to search for
+ * @param[out] handler Handler to search result. Must be freed by
+ * certsvc_certificate_list_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_certificate_list_free()
+ * @see certsvc_certificate_list_get_one()
+ * @see certsvc_certificate_list_get_length()
+ * @see #CertSvcCertificateField
+ * @see #CertSvcCertificateList
*/
int certsvc_certificate_search(CertSvcInstance instance,
CertSvcCertificateField field,
CertSvcCertificateList *handler);
/**
- * This function will return certificate id founded by certsvc_certificate_search.
- * You can call this function multiple times to get all results.
+ * Get certificate from list founded by certsvc_certificate_search().
+ * Can be called multiple times to get all results.
+ * Returned certificate can be freed. certsvc_certificate_list_free() doesn't
+ * free certificates in the list.
+ *
+ * @param[in] hadler Hander to search results.
+ * @param[in] position List index start from 0
+ * @param[out] certificate Certficate i
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*
- * @param[in] hadler Hander to search results.
- * @param[in] position
- * @param[out] certificate Certficate id.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * @see certsvc_certificate_search()
+ * @see certsvc_certificate_free()
+ * @see #CertSvcCertificate
+ * @see #CertSvcCertificateList
*/
int certsvc_certificate_list_get_one(CertSvcCertificateList handler,
size_t position,
/**
* Return number of elements on the list.
*
- * @param[in] handler Handler to certifiacte list.
- * @param[out] length Size of list.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * @param[in] handler Handler to certifiacte list
+ * @param[out] length Size of list
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_certificate_search()
+ * @see #CertSvcCertificateList
*/
int certsvc_certificate_list_get_length(CertSvcCertificateList handler,
size_t *size);
/**
- * This function will free list. It will not free certificates on the list.
- * You may free each certificate with certsvc_certificate_free.
+ * Free @a CertSvcCertificateList. It will not free certificates on the list.
+ * You may free each certificate with certsvc_certificate_free().
*
- * @param[in] handler Handler to search result.
+ * @param[in] handler Handler to search result
+ *
+ * @see certsvc_certificate_search()
+ * @see certsvc_certificate_list_get_one()
+ * @see certsvc_certificate_free()
+ * @see #CertSvcCertificateList
*/
void certsvc_certificate_list_free(CertSvcCertificateList handler);
/**
* Compare parent certificate subject with child issuer field.
*
- * @param[in] child
- * @param[in] parent
- * @param[out] status CERTSVC_TRUE if "signer" was used to sign "child" certificate in other cases it will return CERTSVC_FALSE.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * @param[in] child Child certificate. Issuer field will be used
+ * @param[in] parent Parent certificate. Subject field will be used
+ * @param[out] status #CERTSVC_TRUE if @a child is signed by @a parent,
+ * else #CERTSVC_FALSE
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_is_signed_by(CertSvcCertificate child,
CertSvcCertificate parent,
int *status);
/**
- * Extract specific data from certificate. Data in buffer could be free
- * by certsvc_free_string function or by
- * certsvc_instance_free or vcore_instance_reset.
- *
- * @param[in] certificate Certificate id.
- * @param[in] field Type of data to extract.
- * @param[out] buffer Extracted data.
- * return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL
+ * Extract data field from certificate. Data in buffer could be free by
+ * certsvc_string_free() function or by certsvc_instance_free or vcore_instance_reset.
+ *
+ * @param[in] certificate Certificate
+ * @param[in] field Certificate field to get
+ * @param[out] buffer output string. Must be freed by certsvc_string_free()
+ * or certsvc_instance_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_free()
+ * @see certsvc_string_free()
+ * @see #CertSvcCertificate
+ * @see #CertSvcCertificateField
*/
int certsvc_certificate_get_string_field(CertSvcCertificate certificate,
CertSvcCertificateField field,
CertSvcString *buffer);
/**
- * Extract NOT AFTER data from certificate.
+ * Extract NOT AFTER field from certificate.
+ *
+ * @param[in] certificate Certificate
+ * @param[out] result not after time_t
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*
- * @param[in] certificate Certificate id.
- * @param[out] result date
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_get_not_after(CertSvcCertificate certificate, time_t *result);
/**
- * Extract NOT AFTER data from certificate.
+ * Extract NOT BEFORE field from certificate.
*
- * @param[in] certificate Certificate id.
- * @param[out] result date
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] certificate Certificate
+ * @param[out] result not before time_t
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_certificate_get_not_before(CertSvcCertificate certificate, time_t *result);
/**
- * Check certificate. This fuction compares SUBJECT and ISSUER fields.
+ * Check whether the certificate is root ca by checking self-signedness.
* TODO: This fuction should also check ROOTCA field in certificate.
*
- * @param[in] certificate Certificate id.
- * @param[out] status CERTSVC_TRUE or CERTSVC_FALSE
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * @param[in] certificate Certificate
+ * @param[out] status #CERTSVC_TRUE or #CERTSVC_FALSE
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_is_root_ca(CertSvcCertificate certificate, int *status);
/**
* Sort certificates chain. This fuction modifies certificate_array.
*
- * If function success:
- * * certificate array will contain end entity certificate as first element
- * * last element on the certificate_array will contain Root CA certificate or
- * CA certificate (if Root CA is not present).
+ * @param[in/out] unsortedChain unsorted chain in form of @a CertSvcCertificate array
+ * which will be sorted from end entity certificate on
+ * the first position and (root) CA certificate on the
+ * last position
+ * @param[in] size Size of @a unsortedChain
*
- * @param[in/out] certificate_array
- * @param[in] size Size of certificate_array
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT, CERTSVC_BAD_ALLOC
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see #CertSvcCertificate
*/
int certsvc_certificate_chain_sort(CertSvcCertificate *unsortedChain, size_t size);
/**
* Base64 string will be connected with same instance as message.
- * You can free base64 string with certsvc_string_free (or certsvc_instance_reset).
*
- * @param[in] message Buffer with input data.
- * @param[out] base64 Buffer with output data.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] message Buffer with input data
+ * @param[out] base64 Buffer with output data which must be freed by
+ * certsvc_string_free() or certsvc_instance_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_free()
+ * @see certsvc_string_free()
*/
int certsvc_base64_encode(CertSvcString message, CertSvcString *base64);
/**
* Message string will be connected with same certsvc instance as base64.
- * You can free base64 string with certsvc_string_free (or certsvc_instance_reset).
*
- * @param[in] base64 Buffer with input data.
- * @param[out] message Buffer with output data.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] base64 Buffer with input data
+ * @param[out] message Buffer with output data which must be freed by
+ * certsvc_string_free() or certsvc_instance_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_free()
+ * @see certsvc_string_free()
*/
int certsvc_base64_decode(CertSvcString base64, CertSvcString *message);
/**
- * Use certificate to verify message.
- *
- * @param[in] certificate
- * @param[in] message
- * @param[in] algorithm May be set to NULL.
- * @param[out] status Will be set only if function return CERTSVC_SUCCESS.
- * It could be set to: CERTSVC_SUCCESS, CERTSVC_INVALID_SIGNATURE
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_ALGORITHM
+ * Verify signature with given arguments.
+ *
+ * @param[in] certificate Certificate
+ * @param[in] message Message
+ * @param[in] signature Signature to verify
+ * @param[in] algorithm May be set to NULL
+ * @param[out] status #CERTSVC_SUCCESS if success, else #CERTSVC_INVALID_SIGNATURE
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
*/
int certsvc_message_verify(
CertSvcCertificate certificate,
int *status);
/**
- * This function will create full chain and verify in.
+ * Verify certificate. Root CA certificate should be stored in @a trusted.
*
- * First argument of function will be treatet as endentity certificate.
+ * @param[in] certificate Certificate
+ * @param[in] trusted Array with trusted certificates
+ * @param[in] trustedSize Array size of @a trusted
+ * @param[in] untrusted Array with untrusted certificates
+ * @param[in] untrustedSize Array size of @a untrusted
+ * @param[out] status #CERTSVC_SUCCESS if success, else #CERTSVC_FAIL
*
- * This function will success if root CA certificate is stored in
- * trusted array.
- *
- * @param[in] certificate Certificate to verify.
- * @param[in] trusted Array with trusted certificates.
- * @param[in] trustedSize Number of trusted certificates in array.
- * @param[in] untrusted Array with untrusted certificates.
- * @param[in] untrustedSize Number of untrusted certificate in array.
- * @param[out] status Will be set only if function return CERTSVC_SUCCESS.
- * It could be set to: CERTSVC_SUCCESS, CERTSVC_FAIL
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_certificate_verify(
CertSvcCertificate certificate,
int *status);
/**
- * This function will create full chain and verify in.
- * And this function checks the CA Flag strictly.
- *
- * First argument of function will be treatet as endentity certificate.
- *
- * This function will success if root CA certificate is stored in
- * trusted array.
- *
- * @param[in] certificate Certificate to verify.
- * @param[in] trusted Array with trusted certificates.
- * @param[in] trustedSize Number of trusted certificates in array.
- * @param[in] untrusted Array with untrusted certificates.
- * @param[in] untrustedSize Number of untrusted certificate in array.
- * @param[out] status Will be set only if function return CERTSVC_SUCCESS.
- * It could be set to: CERTSVC_SUCCESS, CERTSVC_FAIL
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * Verify certificate with strict check of CA flag. Root CA certificate should
+ * be stored in @a trusted.
+ *
+ * @param[in] certificate Certificate
+ * @param[in] trusted Array with trusted certificates
+ * @param[in] trustedSize Array size of @a trusted
+ * @param[in] untrusted Array with untrusted certificates
+ * @param[in] untrustedSize Array size of @a untrusted
+ * @param[out] status #CERTSVC_SUCCESS if success, else #CERTSVC_FAIL
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_certificate_verify_with_caflag(
- CertSvcCertificate certificate,
- const CertSvcCertificate *trusted,
- size_t trustedSize,
- const CertSvcCertificate *untrusted,
- size_t untrustedSize,
- int *status);
+ CertSvcCertificate certificate,
+ const CertSvcCertificate *trusted,
+ size_t trustedSize,
+ const CertSvcCertificate *untrusted,
+ size_t untrustedSize,
+ int *status);
/**
- * This function returns visibility of input certificate.
+ * Get visibility from Tizen app signing root certificate.
+ *
+ * @param[in] certificate Tizen app signing root certificate to get visibility
+ * @param[out] visibility Visibilitay level of @a certificate
*
- * @param[in] The root certificate to check visibility.
- * @param[out] Visibility level
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*
+ * @see #CertSvcVisibility
*/
int certsvc_certificate_get_visibility(CertSvcCertificate certificate, CertSvcVisibility *visibility);
/**
- * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* Allocate internal data of CertSvc library and put it in the CertSvcInstance structure.
* Initialize Openssl interanal structures.
*
- * @param[out] instance Pointer to CertSvcInstance.
- * @return CERTSVC_SUCCESS or CERTSVC_FAIL.
+ * @param[out] instance Pointer to CertSvcInstance
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_instance_new(CertSvcInstance *instance);
/**
- * This function will free all allocated data. All certificate identificator will
- * be released and all strings allocated by certsvc_certificate_get_string field will be
- * released also.
+ * Free all allocated data. All certificate identificator will be released and all
+ * strings allocated by certsvc_certificate_get_string_field() will be released also.
*
- * This fucntion does not release CertSvcInstnace!
+ * This fucntion does not release CertSvcInstnace itself!
*
- * Plese note: It is safe to use this function after use certsvc_string_free.
+ * Plese note: It is safe to use this function after use certsvc_string_free().
*
- * @param[in] instance CertSvcInstance object.
+ * @param[in] instance CertSvcInstance object
*/
void certsvc_instance_reset(CertSvcInstance instance);
/**
- * This function will free all allocated data. All certificate identificator will
- * be released and all strings allocated by certsvc_certificate_get_string field will be
- * released also.
+ * Free all allocated data. All certificate identificator will be released and all strings
+ * allocated by certsvc_certificate_get_string_field() will be released also.
*
* This fucntion also release CertSvcInstnace!
*
- * Please note: It is safe use this function after use certsvc_string_free.
+ * Please note: It is safe use this function after use certsvc_string_free().
*
* @param[in] instance CertSvcInstance object
*/
/**
- * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
/**
* Check whenever PKCS#12 container is password protected.
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] path Path to container file.
- * @param[out] has_password CERTSVC_TRUE (if container is password protected) or CERTSVC_FALSE.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT
+ * @param[in] instance CertSvcInstance object
+ * @param[in] filepath File path to check
+ * @param[out] has_password #1 if password protectedm, else #0
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
*/
int certsvc_pkcs12_has_password(CertSvcInstance instance,
CertSvcString filepath,
/**
* Couter-routine for certsvc_pkcs12_private_key_dup.
*
- * @param[in] pointer Memory claimed by private key.
+ * @param[in] buffer Memory claimed by private key
*/
void certsvc_pkcs12_private_key_free(char *buffer);
/**
- * This function will load to memory private file content. This functin will
- * not parse it in any way.
- * This memory must be freed by certsvc_private_key_free.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] gname Container bundle identifier.
- * @param[out] certBuffer Poiner to newly-allocated memory with private key data.
- * @param[out] certsize Size of the newly-allocated buffer. Zero means there is no key.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT
+ * Load to memory of private key in cert-svc store with @a gname.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] gname Single certificate identifier. It has to be end user's
+ * to extract private key
+ * @param[out] buffer Private key buffer which must be freed after use
+ * @param[out] size Size of the returned buffer. Zero when no key is found
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_private_key_dup_from_store(CertSvcInstance instance,
CertStoreType storeType,
CertSvcString gname,
- char **certBuffer,
- size_t *certsize);
+ char **buffer,
+ size_t *size);
/**
- * This function will set the status for the specified certificate in a particular
- * store to enabled / disabled.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] is_root_app Set to ENABLED/DISABLED. Should be ENABLED if master application is changing the status, else DISABLED for other applications.
- * @param[in] gname Referred as group name, is the key for accessing the certificate.
- * @param[in] status Allows to set the status of the certificate to enabled / disabled.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Set the status for the specified certificate in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] is_root_app Should be #ENABLED if master application is changing the status,
+ * else #DISABLED for other applications
+ * @param[in] gname Single certificate identifier
+ * @param[in] status Status of the certificate to set. [#ENABLED | #DISABLED]
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
+ * @see #CertStatus
*/
int certsvc_pkcs12_set_certificate_status_to_store(CertSvcInstance instance,
- CertStoreType storeType,
- int is_root_app,
- CertSvcString gname,
- CertStatus status);
+ CertStoreType storeType,
+ int is_root_app,
+ CertSvcString gname,
+ CertStatus status);
/**
- * This function will get the status for the specified certificate in a particular
- * store.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] gname Referred as group name, is the key for accessing the certificate.
- * @param[out] status refers to weather the certificate is enabled/disabled.
- * @return Disable=0, Enable=1, Fail=-1
+ * Get the status for the specified certificate in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in[ gname Single certificate identifier
+ * @param[out] status Status of the certificate. Enabled:1, Disabled:0, Fail:-1
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStroeType
*/
int certsvc_pkcs12_get_certificate_status_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcString gname,
- CertStatus *status);
+ CertStoreType storeType,
+ CertSvcString gname,
+ CertStatus *status);
/**
- * This function will get the Alias name, Path to certificate, Certificate status of all
- * the certificates present in the specified certificate store.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[out] certList Linked-list having all the information about each certificate present in a store.
- * @param[out] length Provides the length of the linked list.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Get the certificates in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] is_root_app Should be #ENABLED if master application is changing the
+ * status, else #DISABLED for other applications
+ * @param[out] certList cert list in store returned in linked list. Free by
+ * certsvc_pkcs12_free_certificate_list_loaded_from_store()
+ * after use
+ * @param[out] length length of output @a certList
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see #CertStoreType
+ * @see #CertSvcStoreCertList
*/
int certsvc_pkcs12_get_certificate_list_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- int is_root_app,
- CertSvcStoreCertList** certList,
- size_t *length);
+ CertStoreType storeType,
+ int is_root_app,
+ CertSvcStoreCertList** certList,
+ size_t *length);
/**
- * This function will get the Alias name, Path to certificate, Certificate status of all
- * the end user certificates present in the specified certificate store.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[out] certList Linked-list having all the information about each certificate present in a store.
- * @param[out] length Provides the length of the linked list.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Get the end user certificates in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[out] certList cert list in store returned in linked list. Free by
+ * certsvc_pkcs12_free_certificate_list_loaded_from_store() after use
+ * @param[out] length length of output @a certList
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see #CertStoreType
+ * @see #CertSvcStoreCertList
*/
int certsvc_pkcs12_get_end_user_certificate_list_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcStoreCertList** certList,
- size_t* length);
+ CertStoreType storeType,
+ CertSvcStoreCertList** certList,
+ size_t* length);
/**
- * This function will get the Alias name, Path to certificate, Certificate status of all
- * the root/trusted certificates present in the specified certificate store.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[out] certList Linked-list having all the information about each certificate present in a store.
- * @param[out] length Provides the length of the linked list.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Get the root/trusted certificates in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[out] certList cert list in store returned in linked list. Free by
+ * certsvc_pkcs12_free_certificate_list_loaded_from_store() after use
+ * @param[out] length length of output @a certList
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_pkcs12_free_certificate_list_loaded_from_store()
+ * @see #CertStoreType
+ * @see #CertSvcStoreCertList
*/
int certsvc_pkcs12_get_root_certificate_list_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcStoreCertList** certList,
- size_t* length);
+ CertStoreType storeType,
+ CertSvcStoreCertList** certList,
+ size_t* length);
/**
- * This function will free all the linked list of data structure holding the information about
- * all the certificates present in a store which was previously by calling the
- * certsvc_get_certificate_list_from_store() function.
+ * Free all @a CertSvcStoreCertList in linked list of data structure.
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] certList The structure which need to be freed.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * @param[in] instance CertSvcInstance object
+ * @param[in] certList The structure which need to be freed
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_pkcs12_get_certificate_list_from_store()
+ * @see certsvc_pkcs12_get_end_user_certificate_list_from_store()
+ * @see certsvc_pkcs12_get_root_certificate_list_from_store()
+ * @see #CertSvcStoreCertList
*/
int certsvc_pkcs12_free_certificate_list_loaded_from_store(CertSvcInstance instance,
- CertSvcStoreCertList** certList);
+ CertSvcStoreCertList** certList);
/**
- * This function will provide the certificate back for the gname provided.
+ * Get the certificate with the gname provided from cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] gname Single certificate identifier
+ * @param[out] certificate output in @a CertSvcCertificate format
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in[ gname Referred as group name, is the key for accessing the certificate.
- * @param[out] certificate Certificate holding the information.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_BAD_ALLOC
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_certificate_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_get_certificate_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- const char *gname,
- CertSvcCertificate *certificate);
+ CertStoreType storeType,
+ const char *gname,
+ CertSvcCertificate *certificate);
/**
- * This function will give back the the encoded certificate buffer for the matching
- * alias present in the specified store.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] gname Referred as group name, is the key for accessing the certificate.
- * @param[out] certBuffer Buffer containing the encoded certificate.
- * @param[out] certSize Size of the buffer.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Get the encoded certificate buffer with the gname provided from cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] gname Single certificate identifier
+ * @param[out] buffer The base64 encoded certificate which must be freed after
+ * use
+ * @param[out] size Size of the buffer
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_get_certificate_info_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcString gname,
- char** certBuffer,
- size_t* certSize);
+ CertStoreType storeType,
+ CertSvcString gname,
+ char** buffer,
+ size_t* size);
/**
- * This function will import a .pfx/.p12 file to specified store (WIFI, VPN, EMAIL).
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] path Path of the certificate which needs to be imported.
- * @param[in] password Password to open the pfx/p12 file.
- * @param[in] alias Logical name for certificate bundle identification (can't be empty).
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * Import PKCS#12 bundle(with .pfx or .p12) or certificate(base64 form with .crt
+ * or .pem suffix) from file to specified store. If password isn't needed, create
+ * CertSvcString @a password with null input on certsvc_string_new(). Refer
+ * certsvc_string_new() API description
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] path Path of the certificate which needs to be imported
+ * @param[in] password Password if the file to import is password-protected which can be
+ * empty CertSvcString in case of not-password-protected
+ * @param[in] alias Primary key for certificate bundle identification (can't be empty)
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_import_from_file_to_store(CertSvcInstance instance,
CertStoreType storeType,
CertSvcString alias);
/**
- * This function will delete the certificate from the path specified present in the specified store.
+ * Delete the certificate with gname provided from cert-svc store.
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] gname Referred as group name, is the key for accessing the certificate.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] gname Single certificate identifier
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_delete_certificate_from_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcString gname);
+ CertStoreType storeType,
+ CertSvcString gname);
/**
- * Query PKCS#12 storage to find out whenever new alias proposal is unique.
+ * Check the uniqueness of the alias in cert-svc store.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] alias Certificates bundle identifier used when importing
+ * @param[out] is_unique #CERTSVC_TRUE if the alias is unique, else #CERTSVC_FALSE
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] proposal Desired alias name.
- * @param[out] is_unique CERTSVC_TRUE (if there isn't such alias already) or CERTSVC_FALSE.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_check_alias_exists_in_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcString alias,
- int *is_unique);
+ CertStoreType storeType,
+ CertSvcString alias,
+ int *is_unique);
/**
- * Get a list of certificates from PKCS#12 bundle. You may free this list by:
- * certsvc_certificate_list_free. You may free certificates from list with:
- * certsvc_certificate_free.
- *
- * @param[in] instance CertSvcInstance object.
- * @param[in] pfxIdString Identification of pfx/pkcs file.
- * @param[out] certificateList List of certificates.
- * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL, CERTSVC_IO_ERROR
+ * Get list of certificates from PKCS#12 bundle or single certificate which
+ * is saved in cert-svc store with the alias.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] alias Certificates bundle identifier used when importing
+ * @param[out] certificateList List of certificates. Free by
+ * certsvc_certificate_list_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see certsvc_certificate_free()
+ * @see certsvc_certificate_list_free()
+ * @see #CertStoreType
+ * @see #CertSvcStoreCertList
*/
int certsvc_pkcs12_load_certificate_list_from_store(CertSvcInstance instance,
CertStoreType storeType,
- CertSvcString pfxIdString,
+ CertSvcString alias,
CertSvcCertificateList *certificateList);
/**
- * Gets the alias name for the gname passed.
+ * Get the alias name with the gname provided.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] gname Single certificate identifier which is associated with alias
+ * @param[out] alias Certificates bundle identifier used when importing which must
+ * be freed after use
*
- * @param[in] instance CertSvcInstance object.
- * @param[in] gname Certificate identification of pfx/pkcs file.
- * @param[out] alias Alias name for the given gname.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
+ * @see #CertStoreType
*/
int certsvc_pkcs12_get_alias_name_for_certificate_in_store(CertSvcInstance instance,
- CertStoreType storeType,
- CertSvcString gname,
- char **alias);
+ CertStoreType storeType,
+ CertSvcString gname,
+ char **alias);
#ifdef __cplusplus
}
/**
- * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* limitations under the License.
*/
/*
- * @file vcore_api_extension.h
+ * @file cprimitives.h
* @author Bartlomiej Grzelewski (b.grzelewski@samsung.com)
* @version 1.0
- * @brief This is C api for ValidationCore.
+ * @brief cert-svc capi primitives
*/
#ifndef _CERTSVC_C_API_EXTENDED_H_
#define _CERTSVC_C_API_EXTENDED_H_
#endif
/**
- * This will return pointer to X509 base openssl struct. This struct must be release by function
- * certsvc_certificate_free_x509.
+ * Duplicate @a CertSvcCertificate structure to openssl X509 structure.
+ * openssl X509 structure should be freed by certsvc_certificate_free_x509().
+ * @a CertSvcInstance isn't free duplicated openssl X509 structure.
*
- * vcore_instance_free or vcore_instance_reset will not free memory allocated by this function!
+ * @param[in] certificate Certificate
+ * @param[out] x509 Duplicated @a certificate
*
- * @param[in] certificate Pointer to certificate.
- * @param[out] cert Duplicate of certificate.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT, CERTSVC_FAIL
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_certificate_free_x509()
*/
-int certsvc_certificate_dup_x509(CertSvcCertificate certificate, X509** cert);
+int certsvc_certificate_dup_x509(CertSvcCertificate certificate, X509** x509);
/**
- * Release X509 struct allocated by certsvc_certificate_new_x509_copy function.
+ * Free openssl x509 structure duplicated by certsvc_certificate_dup_x509().
+ *
+ * @param[in] x509 openssl X509 structure to free
*
- * @param[in] x509_copy Pointer to openssl struct.
+ * @see certsvc_certificate_dup_x509()
*/
-void certsvc_certificate_free_x509(X509 *x509_copy);
+void certsvc_certificate_free_x509(X509 *x509);
/**
* Duplicate pubkey in DER form from CertSvcCertificate.
* Remarks: Free returned pubkey after use by free()
*
- * @param[in] certificate Pointer to certificate.
- * @param[out] pubkey Duplicated certificate in DER form
- * @param[out] len Duplicated certificate length
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT, CERTSVC_FAIL
+ * @param[in] certificate Pointer to certificate.
+ * @param[out] pubkey Duplicated certificate in DER form which must be
+ * freed after use
+ * @param[out] len Duplicated certificate length
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_certificate_dup_pubkey_der(CertSvcCertificate certificate, unsigned char **pubkey, size_t *len);
/**
- * This will return pointer to EVP_PKEY base openssl struct. This struct must
- * be release with function certsvc_pkcs12_free_evp_pkey
+ * Get private key from cert-svc store in openssl EVP_PKEY structure.
+ * openssl EVP_PKEY structure should be freed by certsvc_pkcs12_free_evp_pkey().
+ * @a CertSvcInstance isn't free duplicated openssl EVP_PKEY structure.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] storeType cert-svc store type to query
+ * @param[in] gname Single certificate identifier which is associated with
+ * private key
+ * @param[out] pkey private key from storage which must be freed after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*
- * @param[in] instance
- * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
- * @param[in] gname Pkcs12 identificator.
- * @param[out] pkey Duplicate of private key.
- * @return CERTSVC_SUCCESS, CERT_FAIL
+ * @see certsvc_pkcs12_free_evp_pkey()
*/
-
int certsvc_pkcs12_dup_evp_pkey_from_store(CertSvcInstance instance,
CertStoreType storeType,
CertSvcString gname,
EVP_PKEY** pkey);
+/**
+ * Free openssl EVP_PKEY structure duplicated by certsvc_pkcs12_dup_ev_pkey()
+ * or certsvc_pkcs12_dup_evp_pkey_from_store().
+ *
+ * @param[in] x509 openssl EVP_PKEY structure to free
+ *
+ * @see certsvc_pkcs12_dup_evp_pkey()
+ * @see certsvc_pkcs12_dup_evp_pkey_from_store()
+ */
void certsvc_pkcs12_free_evp_pkey(EVP_PKEY* pkey);
#ifdef __cplusplus
/**
- * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
} CertSvcString;
/**
- * This function will duplicate input data. Data in ouput string will be managed by certsvc.
+ * Create CertSvcString with input cstring and size. Newly allocated memory
+ * is in same lifecycle with @a instance param unless freed by certsvc_string_free().
+ * If empty string is needed, put NULL on @a input param and 0 on @a size param.
*
- * @param[in] instance CertSvcString will be conected with this instance.
- * @param[in] input Input data.
- * @param[in] size Input buffer size.
- * @param[out] output Buffer with output data.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
+ * @param[in] instance CertSvcInstance object
+ * @param[in] input null-terminated string. Put #NULL if empty string needed
+ * @param[in] size size of @a input to make. put #0 if empty string needed.
+ * Can be smaller than length of @a input
+ * @param[out] output Output CertSvcString with newly allocated memory
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_new()
+ * @see certsvc_instance_free()
+ * @see certsvc_string_free()
*/
int certsvc_string_new(
CertSvcInstance instance,
CertSvcString *output);
/**
- * This function wont duplicate input data. Output param will contain pointer to input
- * so input could not be free as long as ouput param is used.
- *
- * @param[in] instance CertSvcString will be conected with this instance.
- * @param[in] input Input data.
- * @param[in] size Input buffer size.
- * @param[out] output Buffer with output data.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * Create CertSvcString with @a input null-terminated string. @a output CertSvcString will
+ * contain pointer to @a input so input could not be freed as long as ouput param is used.
+ *
+ * @param[in] instance CertSvcInstance object
+ * @param[in] input null-terminated string. Put #NULL if empty string needed
+ * @param[in] size size of @a input to make. put #0 if empty string needed.
+ * Can be smaller than length of @a input
+ * @param[out] output Output CertSvcString based on @a input
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_string_new()
+ * @see certsvc_string_free()
*/
int certsvc_string_not_managed(
CertSvcInstance instance,
CertSvcString *output);
/**
- * Extract next result from result set. Function certsvc_string_list_free
- * does not free results returned by this function. CertSvcString is valid
- * until certsvc_string_free or vcore_instance_reset or vcore_instance_free
- * is called.
- *
- * @param[in] handler Handler to set of strings.
- * @param[out] buffer The buffer will be pointing to string with distrubution point url or will be set to NULL if error occures.
- * @param[out] size Size of data pointed by buffer or 0 if error occures.
- * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT, CERTSVC_BAD_ALLOC
+ * Get CertSvcString from CertSvcStringList with newly allocated memory.
+ * Output CertSvcString can be freed by certsvc_string_free() or reset/free instance
+ * of CertSvcInstance which is used to get the CertSvcStringList.
+ *
+ * @param[in] handler Handler to string list
+ * @param[in] position Index of CertSvcString to get in CertSvcStringList
+ * @param[out] buffer Output CertSvcString must be freed by
+ * certsvc_string_free() after use
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
+ *
+ * @see certsvc_instance_free()
+ * @see certsvc_string_free()
*/
int certsvc_string_list_get_one(CertSvcStringList hander,
size_t position,
CertSvcString *buffer);
/**
- * Extract CertSvcStringList size.
+ * Get list size of CertSvcStringList.
*
- * @param[in] handler Handler to string list.
- * @param[out] size Number of elements on the list.
- * @return CERTSVC_SUCCESS, CERTSVC_WRONG_ARGUMENT
+ * @param[in] handler Handler to string list
+ * @param[out] size Number of elements on the list
+ *
+ * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
*/
int certsvc_string_list_get_length(CertSvcStringList hander, size_t *size);
/**
- * Free data.
+ * Free CertSvcString.
*
- * @param[in] string Data allocated by certsvc_certificate_get_string_field
+ * @param[in] string CertSvcString to free
*/
void certsvc_string_free(CertSvcString string);
/**
- * Free string list.
- *
- * Note: This function does not free strings returned by certsvc_string_list_get_one_result.
+ * Free CertSvcStringList.
*
- * @param[in] handler String set handler.
+ * @param[in] handler Handler to string list
*/
void certsvc_string_list_free(CertSvcStringList handler);
/**
- * Convert CertSvcStringPtr into pure c pointer. Please note that this pointer is valid as long as CertSvcString is valid.
+ * Convert CertSvcString into null-terminated C string. Please note that this pointer
+ * is valid as long as CertSvcString is valid.
*
- * @param[in] string CertSvcStringPtr.
- * @param[out] buffer cstring
- * @param[out] len Length of cstring
+ * @param[in] string CertSvcString
+ * @param[out] buffer null-terminated c string
+ * @param[out] len Length of string
*/
void certsvc_string_to_cstring(CertSvcString string, const char **buffer, size_t *len);
projects / platform / core / security / cert-svc.git / commitdiff