1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* 3 * Copyright (C) 2003-2004 Imendio AB 4 * 5 * This program is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public License as 7 * published by the Free Software Foundation; either version 2 of the 8 * License, or (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with this program; if not, see <https://www.gnu.org/licenses> 17 */ 18 19 /** 20 * SECTION:lm-ssl 21 * @Title: LmSSL 22 * @Short_description: SSL struct for SSL support in Loudmouth 23 * 24 * Use this together with an #LmConnection to get the connection to use SSL. Example of how to use the #LmSSL API. 25 * 26 * <informalexample><programlisting><![CDATA[ 27 * LmConnection *connection; 28 * LmSSL *ssl; 29 * 30 * connection = lm_connection_new ("myserver"); 31 * ssl = lm_ssl_new (NULL, my_ssl_func, NULL, NULL); 32 * lm_connection_set_ssl (connection, ssl); 33 * ... 34 * ]]></programlisting></informalexample> 35 */ 36 37 #ifndef __LM_SSL_H__ 38 #define __LM_SSL_H__ 39 40 #include <glib.h> 41 42 #if !defined (LM_INSIDE_LOUDMOUTH_H) && !defined (LM_COMPILATION) 43 #error "Only <loudmouth/loudmouth.h> can be included directly, this file may disappear or change contents." 44 #endif 45 46 #define LM_FINGERPRINT_PREFIX "SHA256:" 47 #define LM_FINGERPRINT_LENGTH 72 48 49 G_BEGIN_DECLS 50 51 /** 52 * LmSSL: 53 * 54 * This should not be accessed directly. Use the accessor functions as described below. 55 */ 56 typedef struct _LmSSL LmSSL; 57 58 /** 59 * LmCertificateStatus: 60 * @LM_CERT_INVALID: The certificate is invalid. 61 * @LM_CERT_ISSUER_NOT_FOUND: The issuer of the certificate is not found. 62 * @LM_CERT_REVOKED: The certificate has been revoked. 63 * 64 * Provides information of the status of a certain certificate. 65 */ 66 typedef enum { 67 LM_CERT_INVALID, 68 LM_CERT_ISSUER_NOT_FOUND, 69 LM_CERT_REVOKED 70 } LmCertificateStatus; 71 72 /** 73 * LmSSLStatus: 74 * @LM_SSL_STATUS_NO_CERT_FOUND: The server doesn't provide a certificate. 75 * @LM_SSL_STATUS_UNTRUSTED_CERT: The certification can not be trusted. 76 * @LM_SSL_STATUS_CERT_EXPIRED: The certificate has expired. 77 * @LM_SSL_STATUS_CERT_NOT_ACTIVATED: The certificate has not been activated. 78 * @LM_SSL_STATUS_CERT_HOSTNAME_MISMATCH: The server hostname doesn't match the one in the certificate. 79 * @LM_SSL_STATUS_CERT_FINGERPRINT_MISMATCH: The fingerprint doesn't match your expected. 80 * @LM_SSL_STATUS_GENERIC_ERROR: Some other error. 81 * 82 * Provides information about something gone wrong when trying to setup the SSL connection. 83 */ 84 typedef enum { 85 LM_SSL_STATUS_NO_CERT_FOUND, 86 LM_SSL_STATUS_UNTRUSTED_CERT, 87 LM_SSL_STATUS_CERT_EXPIRED, 88 LM_SSL_STATUS_CERT_NOT_ACTIVATED, 89 LM_SSL_STATUS_CERT_HOSTNAME_MISMATCH, 90 LM_SSL_STATUS_CERT_FINGERPRINT_MISMATCH, 91 LM_SSL_STATUS_GENERIC_ERROR 92 } LmSSLStatus; 93 94 /** 95 * LmSSLResponse: 96 * @LM_SSL_RESPONSE_CONTINUE: Continue to connect. 97 * @LM_SSL_RESPONSE_STOP: Stop the connection. 98 * 99 * Used to inform #LmConnection if you want to stop due to an error reported or if you want to continue to connect. 100 */ 101 typedef enum { 102 LM_SSL_RESPONSE_CONTINUE, 103 LM_SSL_RESPONSE_STOP 104 } LmSSLResponse; 105 106 /** 107 * LmSSLFunction: 108 * @ssl: An #LmSSL. 109 * @status: The status informing what went wrong. 110 * @user_data: User data provided in the callback. 111 * 112 * This function is called if something goes wrong during the connecting phase. 113 * 114 * Returns: User should return #LM_SSL_RESPONSE_CONTINUE if connection should proceed and otherwise #LM_SSL_RESPONSE_STOP. 115 */ 116 typedef LmSSLResponse (* LmSSLFunction) (LmSSL *ssl, 117 LmSSLStatus status, 118 gpointer user_data); 119 120 LmSSL * lm_ssl_new (const gchar *expected_fingerprint, 121 LmSSLFunction ssl_function, 122 gpointer user_data, 123 GDestroyNotify notify); 124 125 gboolean lm_ssl_is_supported (void); 126 127 void lm_ssl_set_cipher_list (LmSSL *ssl, 128 const gchar *cipher_list); 129 130 void lm_ssl_set_ca (LmSSL *ssl, 131 const gchar *ca_path); 132 133 const gchar * lm_ssl_get_fingerprint (LmSSL *ssl); 134 135 void lm_ssl_use_starttls (LmSSL *ssl, 136 gboolean use_starttls, 137 gboolean require); 138 139 gboolean lm_ssl_get_use_starttls (LmSSL *ssl); 140 141 gboolean lm_ssl_get_require_starttls (LmSSL *ssl); 142 143 LmSSL * lm_ssl_ref (LmSSL *ssl); 144 void lm_ssl_unref (LmSSL *ssl); 145 146 G_END_DECLS 147 148 #endif /* __LM_SSL_H__ */ 149