summaryrefslogtreecommitdiff
path: root/src/lib/ecore_con
diff options
context:
space:
mode:
authorSrivardhan Hebbar <sri.hebbar@samsung.com>2015-02-20 12:22:08 +0100
committerCedric BAIL <cedric@osg.samsung.com>2015-02-20 12:22:12 +0100
commitdeef299476ab8a371763dd4f9072904bb27ddf28 (patch)
treef177f771d64f73e67af228392930f787cc09dede /src/lib/ecore_con
parent175c8cbd63244ba3c50c9f41301e7fedb0427a21 (diff)
ecore_con: move documentation of ssl functions from ecore_con_ssl.c to Ecore_Con.h
Summary: Moved documentation of ssl functions from ecore_con_ssl.c to Ecore_Con.h. Reviewers: cedric Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D1994 Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
Diffstat (limited to 'src/lib/ecore_con')
-rw-r--r--src/lib/ecore_con/Ecore_Con.h125
-rw-r--r--src/lib/ecore_con/ecore_con_ssl.c126
2 files changed, 125 insertions, 126 deletions
diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h
index 9ade8379ca..d000e83a2c 100644
--- a/src/lib/ecore_con/Ecore_Con.h
+++ b/src/lib/ecore_con/Ecore_Con.h
@@ -694,18 +694,143 @@ EAPI int ecore_con_shutdown(void);
694 * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions 694 * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
695 * @ingroup Ecore_Con_Group 695 * @ingroup Ecore_Con_Group
696 * 696 *
697 * Functions that operate on Ecore connection objects pertaining to SSL.
698 *
697 * @{ 699 * @{
698 */ 700 */
701
702/**
703 * Returns if SSL support is available
704 * @return 1 if SSL is available and provided by gnutls,
705 * 2 if SSL is available and provided by openssl,
706 * 0 if it is not available.
707 */
699EAPI int ecore_con_ssl_available_get(void); 708EAPI int ecore_con_ssl_available_get(void);
709
710/**
711 * @brief Add an ssl certificate for use in ecore_con functions.
712 *
713 * Use this function to add a SSL PEM certificate.
714 * Simply specify the cert here to use it in the server object for connecting or listening.
715 * If there is an error loading the certificate, an error will automatically be logged.
716 * @param svr The server object
717 * @param cert The path to the certificate.
718 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
719 */
700EAPI Eina_Bool ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert); 720EAPI Eina_Bool ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert);
721
722/**
723 * @brief Add an ssl private key for use in ecore_con functions.
724 *
725 * Use this function to add a SSL PEM private key
726 * Simply specify the key file here to use it in the server object for connecting or listening.
727 * If there is an error loading the key, an error will automatically be logged.
728 * @param svr The server object
729 * @param key_file The path to the key file.
730 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
731 */
701EAPI Eina_Bool ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file); 732EAPI Eina_Bool ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file);
733
734/**
735 * @brief Add an ssl CRL for use in ecore_con functions.
736 *
737 * Use this function to add a SSL PEM CRL file
738 * Simply specify the CRL file here to use it in the server object for connecting or listening.
739 * If there is an error loading the CRL, an error will automatically be logged.
740 * @param svr The server object
741 * @param crl_file The path to the CRL file.
742 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
743 */
702EAPI Eina_Bool ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file); 744EAPI Eina_Bool ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file);
745
746/**
747 * @brief Add an ssl CA file for use in ecore_con functions.
748 *
749 * Use this function to add a SSL PEM CA file.
750 * Simply specify the file here to use it in the server object for connecting or listening.
751 * If there is an error loading the CAs, an error will automatically be logged.
752 * @param svr The server object
753 * @param ca_file The path to the CA file.
754 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
755 * @note since 1.2, this function can load directores
756 */
703EAPI Eina_Bool ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file); 757EAPI Eina_Bool ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file);
758
759/**
760 * @brief Enable certificate verification on a server object
761 *
762 * Call this function on a server object before main loop has started
763 * to enable verification of certificates against loaded certificates.
764 * @param svr The server object
765 */
704EAPI void ecore_con_ssl_server_verify(Ecore_Con_Server *svr); 766EAPI void ecore_con_ssl_server_verify(Ecore_Con_Server *svr);
767
768/**
769 * @brief Enable hostname-based certificate verification on a server object
770 *
771 * Call this function on a server object before main loop has started
772 * to enable verification of certificates using ONLY their hostnames.
773 * @param svr The server object
774 * @note This function has no effect when used on a listening server created by
775 * ecore_con_server_add
776 * @since 1.1
777 */
705EAPI void ecore_con_ssl_server_verify_basic(Ecore_Con_Server *svr); 778EAPI void ecore_con_ssl_server_verify_basic(Ecore_Con_Server *svr);
779
780/**
781 * @brief Set the hostname to verify against in certificate verification
782 *
783 * Sometimes the certificate hostname will not match the hostname that you are
784 * connecting to, and will instead match a different name. An example of this is
785 * that if you connect to talk.google.com to use Google Talk, you receive Google's
786 * certificate for gmail.com. This certificate should be trusted, and so you must call
787 * this function with "gmail.com" as @p name.
788 * See RFC2818 for more details.
789 * @param svr The server object
790 * @param name The hostname to verify against
791 * @since 1.2
792 */
706EAPI void ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *svr, const char *name); 793EAPI void ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *svr, const char *name);
794
795/**
796 * @brief Get the hostname to verify against in certificate verification
797 *
798 * This function returns the name which will be used to validate the SSL certificate
799 * common name (CN) or alt name (subjectAltName). It will default to the @p name
800 * param in ecore_con_server_connect(), but can be changed with ecore_con_ssl_server_verify_name_set().
801 * @param svr The server object
802 * @return The hostname which will be used
803 * @since 1.2
804 */
707EAPI const char *ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *svr); 805EAPI const char *ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *svr);
806
807/**
808 * @brief Upgrade a connection to a specified level of encryption
809 *
810 * Use this function to begin an SSL handshake on a connection (STARTTLS or similar).
811 * Once the upgrade has been completed, an ECORE_CON_EVENT_SERVER_UPGRADE event will be emitted.
812 * The connection should be treated as disconnected until the next event.
813 * @param svr The server object
814 * @param ssl_type The SSL connection type (ONLY).
815 * @return @c EINA_FALSE if the connection cannot be upgraded, otherwise @c EINA_TRUE.
816 * @note This function is NEVER to be used on a server object created with ecore_con_server_add
817 * @warning Setting a wrong value for @p compl_type WILL mess up your program.
818 * @since 1.1
819 */
708EAPI Eina_Bool ecore_con_ssl_server_upgrade(Ecore_Con_Server *svr, Ecore_Con_Type compl_type); 820EAPI Eina_Bool ecore_con_ssl_server_upgrade(Ecore_Con_Server *svr, Ecore_Con_Type compl_type);
821
822/**
823 * @brief Upgrade a connection to a specified level of encryption
824 *
825 * Use this function to begin an SSL handshake on a connection (STARTTLS or similar).
826 * Once the upgrade has been completed, an ECORE_CON_EVENT_CLIENT_UPGRADE event will be emitted.
827 * The connection should be treated as disconnected until the next event.
828 * @param cl The client object
829 * @param ssl_type The SSL connection type (ONLY).
830 * @return @c EINA_FALSE if the connection cannot be upgraded, otherwise @c EINA_TRUE.
831 * @warning Setting a wrong value for @p compl_type WILL mess up your program.
832 * @since 1.1
833 */
709EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_Con_Type compl_type); 834EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_Con_Type compl_type);
710 835
711/** 836/**
diff --git a/src/lib/ecore_con/ecore_con_ssl.c b/src/lib/ecore_con/ecore_con_ssl.c
index 04833f7117..c2b3d5794f 100644
--- a/src/lib/ecore_con/ecore_con_ssl.c
+++ b/src/lib/ecore_con/ecore_con_ssl.c
@@ -566,33 +566,12 @@ ecore_con_ssl_client_write(Ecore_Con_Client *cl,
566 return SSL_SUFFIX(_ecore_con_ssl_client_write) (cl, buf, size); 566 return SSL_SUFFIX(_ecore_con_ssl_client_write) (cl, buf, size);
567} 567}
568 568
569/**
570 * Returns if SSL support is available
571 * @return 1 if SSL is available and provided by gnutls, 2 if provided by openssl,
572 * 0 if it is not available.
573 * @ingroup Ecore_Con_Client_Group
574 */
575EAPI int 569EAPI int
576ecore_con_ssl_available_get(void) 570ecore_con_ssl_available_get(void)
577{ 571{
578 return _ECORE_CON_SSL_AVAILABLE; 572 return _ECORE_CON_SSL_AVAILABLE;
579} 573}
580 574
581/**
582 * @addtogroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
583 *
584 * Functions that operate on Ecore connection objects pertaining to SSL.
585 *
586 * @{
587 */
588
589/**
590 * @brief Enable certificate verification on a server object
591 *
592 * Call this function on a server object before main loop has started
593 * to enable verification of certificates against loaded certificates.
594 * @param svr The server object
595 */
596EAPI void 575EAPI void
597ecore_con_ssl_server_verify(Ecore_Con_Server *obj) 576ecore_con_ssl_server_verify(Ecore_Con_Server *obj)
598{ 577{
@@ -602,16 +581,6 @@ ecore_con_ssl_server_verify(Ecore_Con_Server *obj)
602 svr->verify = EINA_TRUE; 581 svr->verify = EINA_TRUE;
603} 582}
604 583
605/**
606 * @brief Enable hostname-based certificate verification on a server object
607 *
608 * Call this function on a server object before main loop has started
609 * to enable verification of certificates using ONLY their hostnames.
610 * @param svr The server object
611 * @note This function has no effect when used on a listening server created by
612 * ecore_con_server_add
613 * @since 1.1
614 */
615EAPI void 584EAPI void
616ecore_con_ssl_server_verify_basic(Ecore_Con_Server *obj) 585ecore_con_ssl_server_verify_basic(Ecore_Con_Server *obj)
617{ 586{
@@ -621,19 +590,6 @@ ecore_con_ssl_server_verify_basic(Ecore_Con_Server *obj)
621 svr->verify_basic = EINA_TRUE; 590 svr->verify_basic = EINA_TRUE;
622} 591}
623 592
624/**
625 * @brief Set the hostname to verify against in certificate verification
626 *
627 * Sometimes the certificate hostname will not match the hostname that you are
628 * connecting to, and will instead match a different name. An example of this is
629 * that if you connect to talk.google.com to use Google Talk, you receive Google's
630 * certificate for gmail.com. This certificate should be trusted, and so you must call
631 * this function with "gmail.com" as @p name.
632 * See RFC2818 for more details.
633 * @param svr The server object
634 * @param name The hostname to verify against
635 * @since 1.2
636 */
637EAPI void 593EAPI void
638ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *obj, const char *name) 594ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *obj, const char *name)
639{ 595{
@@ -643,16 +599,6 @@ ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *obj, const char *name)
643 eina_stringshare_replace(&svr->verify_name, name); 599 eina_stringshare_replace(&svr->verify_name, name);
644} 600}
645 601
646/**
647 * @brief Get the hostname to verify against in certificate verification
648 *
649 * This function returns the name which will be used to validate the SSL certificate
650 * common name (CN) or alt name (subjectAltName). It will default to the @p name
651 * param in ecore_con_server_connect(), but can be changed with ecore_con_ssl_server_verify_name_set().
652 * @param svr The server object
653 * @return The hostname which will be used
654 * @since 1.2
655 */
656EAPI const char * 602EAPI const char *
657ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *obj) 603ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *obj)
658{ 604{
@@ -662,17 +608,6 @@ ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *obj)
662 return svr->verify_name ? : svr->name; 608 return svr->verify_name ? : svr->name;
663} 609}
664 610
665/**
666 * @brief Add an ssl certificate for use in ecore_con functions.
667 *
668 * Use this function to add a SSL PEM certificate.
669 * Simply specify the cert here to use it in the server object for connecting or listening.
670 * If there is an error loading the certificate, an error will automatically be logged.
671 * @param svr The server object
672 * @param cert The path to the certificate.
673 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
674 */
675
676EAPI Eina_Bool 611EAPI Eina_Bool
677ecore_con_ssl_server_cert_add(Ecore_Con_Server *obj, 612ecore_con_ssl_server_cert_add(Ecore_Con_Server *obj,
678 const char *cert) 613 const char *cert)
@@ -691,18 +626,6 @@ ecore_con_ssl_server_cert_add(Ecore_Con_Server *obj,
691 return SSL_SUFFIX(_ecore_con_ssl_server_cert_add) (obj, cert); 626 return SSL_SUFFIX(_ecore_con_ssl_server_cert_add) (obj, cert);
692} 627}
693 628
694/**
695 * @brief Add an ssl CA file for use in ecore_con functions.
696 *
697 * Use this function to add a SSL PEM CA file.
698 * Simply specify the file here to use it in the server object for connecting or listening.
699 * If there is an error loading the CAs, an error will automatically be logged.
700 * @param svr The server object
701 * @param ca_file The path to the CA file.
702 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
703 * @note since 1.2, this function can load directores
704 */
705
706EAPI Eina_Bool 629EAPI Eina_Bool
707ecore_con_ssl_server_cafile_add(Ecore_Con_Server *obj, 630ecore_con_ssl_server_cafile_add(Ecore_Con_Server *obj,
708 const char *ca_file) 631 const char *ca_file)
@@ -721,17 +644,6 @@ ecore_con_ssl_server_cafile_add(Ecore_Con_Server *obj,
721 return SSL_SUFFIX(_ecore_con_ssl_server_cafile_add) (obj, ca_file); 644 return SSL_SUFFIX(_ecore_con_ssl_server_cafile_add) (obj, ca_file);
722} 645}
723 646
724/**
725 * @brief Add an ssl private key for use in ecore_con functions.
726 *
727 * Use this function to add a SSL PEM private key
728 * Simply specify the key file here to use it in the server object for connecting or listening.
729 * If there is an error loading the key, an error will automatically be logged.
730 * @param svr The server object
731 * @param key_file The path to the key file.
732 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
733 */
734
735EAPI Eina_Bool 647EAPI Eina_Bool
736ecore_con_ssl_server_privkey_add(Ecore_Con_Server *obj, 648ecore_con_ssl_server_privkey_add(Ecore_Con_Server *obj,
737 const char *key_file) 649 const char *key_file)
@@ -750,17 +662,6 @@ ecore_con_ssl_server_privkey_add(Ecore_Con_Server *obj,
750 return SSL_SUFFIX(_ecore_con_ssl_server_privkey_add) (obj, key_file); 662 return SSL_SUFFIX(_ecore_con_ssl_server_privkey_add) (obj, key_file);
751} 663}
752 664
753/**
754 * @brief Add an ssl CRL for use in ecore_con functions.
755 *
756 * Use this function to add a SSL PEM CRL file
757 * Simply specify the CRL file here to use it in the server object for connecting or listening.
758 * If there is an error loading the CRL, an error will automatically be logged.
759 * @param svr The server object
760 * @param crl_file The path to the CRL file.
761 * @return @c EINA_FALSE if the file cannot be loaded, otherwise @c EINA_TRUE.
762 */
763
764EAPI Eina_Bool 665EAPI Eina_Bool
765ecore_con_ssl_server_crl_add(Ecore_Con_Server *obj, 666ecore_con_ssl_server_crl_add(Ecore_Con_Server *obj,
766 const char *crl_file) 667 const char *crl_file)
@@ -779,20 +680,6 @@ ecore_con_ssl_server_crl_add(Ecore_Con_Server *obj,
779 return SSL_SUFFIX(_ecore_con_ssl_server_crl_add) (obj, crl_file); 680 return SSL_SUFFIX(_ecore_con_ssl_server_crl_add) (obj, crl_file);
780} 681}
781 682
782/**
783 * @brief Upgrade a connection to a specified level of encryption
784 *
785 * Use this function to begin an SSL handshake on a connection (STARTTLS or similar).
786 * Once the upgrade has been completed, an ECORE_CON_EVENT_SERVER_UPGRADE event will be emitted.
787 * The connection should be treated as disconnected until the next event.
788 * @param svr The server object
789 * @param ssl_type The SSL connection type (ONLY).
790 * @return @c EINA_FALSE if the connection cannot be upgraded, otherwise @c EINA_TRUE.
791 * @note This function is NEVER to be used on a server object created with ecore_con_server_add
792 * @warning Setting a wrong value for @p compl_type WILL mess up your program.
793 * @since 1.1
794 */
795
796EAPI Eina_Bool 683EAPI Eina_Bool
797ecore_con_ssl_server_upgrade(Ecore_Con_Server *obj, Ecore_Con_Type ssl_type) 684ecore_con_ssl_server_upgrade(Ecore_Con_Server *obj, Ecore_Con_Type ssl_type)
798{ 685{
@@ -815,19 +702,6 @@ ecore_con_ssl_server_upgrade(Ecore_Con_Server *obj, Ecore_Con_Type ssl_type)
815 return !SSL_SUFFIX(_ecore_con_ssl_server_init) (obj); 702 return !SSL_SUFFIX(_ecore_con_ssl_server_init) (obj);
816} 703}
817 704
818/**
819 * @brief Upgrade a connection to a specified level of encryption
820 *
821 * Use this function to begin an SSL handshake on a connection (STARTTLS or similar).
822 * Once the upgrade has been completed, an ECORE_CON_EVENT_CLIENT_UPGRADE event will be emitted.
823 * The connection should be treated as disconnected until the next event.
824 * @param cl The client object
825 * @param ssl_type The SSL connection type (ONLY).
826 * @return @c EINA_FALSE if the connection cannot be upgraded, otherwise @c EINA_TRUE.
827 * @warning Setting a wrong value for @p compl_type WILL mess up your program.
828 * @since 1.1
829 */
830
831EAPI Eina_Bool 705EAPI Eina_Bool
832ecore_con_ssl_client_upgrade(Ecore_Con_Client *obj, Ecore_Con_Type ssl_type) 706ecore_con_ssl_client_upgrade(Ecore_Con_Client *obj, Ecore_Con_Type ssl_type)
833{ 707{