From b20d998dd571731b357a8d56758e295db9d35557 Mon Sep 17 00:00:00 2001 From: Kyungwook Tak Date: Thu, 7 Jan 2016 12:10:56 +0900 Subject: [PATCH] Refine capi descriptions Change-Id: I80db96c244f41ccb2ccaf005ad0b83c3df25ae97 Signed-off-by: Kyungwook Tak --- vcore/cert-svc/ccert.h | 327 +++++++++++++++++++++-------------- vcore/cert-svc/cinstance.h | 25 ++- vcore/cert-svc/cpkcs12.h | 402 +++++++++++++++++++++++++++---------------- vcore/cert-svc/cprimitives.h | 69 +++++--- vcore/cert-svc/cstring.h | 93 ++++++---- 5 files changed, 566 insertions(+), 350 deletions(-) diff --git a/vcore/cert-svc/ccert.h b/vcore/cert-svc/ccert.h index 7d09b81..494e344 100644 --- a/vcore/cert-svc/ccert.h +++ b/vcore/cert-svc/ccert.h @@ -1,5 +1,5 @@ /** - * 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. @@ -117,13 +117,20 @@ typedef enum CertSvcVisibility_t { } 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, @@ -131,26 +138,40 @@ int certsvc_get_certificate(CertSvcInstance instance, 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, @@ -161,16 +182,19 @@ int certsvc_certificate_new_from_memory(CertSvcInstance instance, /** * 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); @@ -181,11 +205,21 @@ int certsvc_certificate_save_file(CertSvcCertificate certificate, const char *lo * * 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, @@ -193,13 +227,21 @@ int certsvc_certificate_search(CertSvcInstance instance, 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, @@ -208,18 +250,27 @@ int certsvc_certificate_list_get_one(CertSvcCertificateList handler, /** * 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); @@ -234,100 +285,128 @@ void certsvc_certificate_list_all_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, @@ -337,21 +416,16 @@ int certsvc_message_verify( 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, @@ -362,38 +436,35 @@ int certsvc_certificate_verify( 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); diff --git a/vcore/cert-svc/cinstance.h b/vcore/cert-svc/cinstance.h index 4f1849d..8e72a92 100644 --- a/vcore/cert-svc/cinstance.h +++ b/vcore/cert-svc/cinstance.h @@ -1,5 +1,5 @@ /** - * 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. @@ -36,32 +36,31 @@ typedef struct CertSvcInstance_t { * 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 */ diff --git a/vcore/cert-svc/cpkcs12.h b/vcore/cert-svc/cpkcs12.h index f436077..cc52112 100644 --- a/vcore/cert-svc/cpkcs12.h +++ b/vcore/cert-svc/cpkcs12.h @@ -1,5 +1,5 @@ /** - * 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. @@ -33,10 +33,16 @@ extern "C" { /** * 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, @@ -45,158 +51,230 @@ int certsvc_pkcs12_has_password(CertSvcInstance instance, /** * 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, @@ -205,58 +283,90 @@ int certsvc_pkcs12_import_from_file_to_store(CertSvcInstance instance, 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 } diff --git a/vcore/cert-svc/cprimitives.h b/vcore/cert-svc/cprimitives.h index 37f59d2..66f86cd 100644 --- a/vcore/cert-svc/cprimitives.h +++ b/vcore/cert-svc/cprimitives.h @@ -1,5 +1,5 @@ /** - * 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. @@ -14,10 +14,10 @@ * 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_ @@ -33,51 +33,70 @@ extern "C" { #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 diff --git a/vcore/cert-svc/cstring.h b/vcore/cert-svc/cstring.h index 2e0be59..3c2ef6c 100644 --- a/vcore/cert-svc/cstring.h +++ b/vcore/cert-svc/cstring.h @@ -1,5 +1,5 @@ /** - * 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. @@ -47,13 +47,21 @@ typedef struct CertSvcString_t { } 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, @@ -62,14 +70,19 @@ int certsvc_string_new( 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, @@ -78,51 +91,55 @@ int certsvc_string_not_managed( 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); -- 2.7.4