openconnect.h

   1 /*
   2  * OpenConnect (SSL + DTLS) VPN client
   3  *
   4  * Copyright © 2008-2012 Intel Corporation.
   5  * Copyright © 2008 Nick Andrew <nick@nick-andrew.net>
   6  *
   7  * Author: David Woodhouse <dwmw2@infradead.org>
   8  *
   9  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * version 2.1, as published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to:
  20  *
  21  *   Free Software Foundation, Inc.
  22  *   51 Franklin Street, Fifth Floor,
  23  *   Boston, MA 02110-1301 USA
  24  */
  25
  26 #ifndef __OPENCONNECT_H__
  27 #define __OPENCONNECT_H__
  28
  29 #include <stdint.h>
  30 #include <sys/types.h>
  31 #include <unistd.h>
  32
  33 #define OPENCONNECT_API_VERSION_MAJOR 2
  34 #define OPENCONNECT_API_VERSION_MINOR 1
  35
  36 /*
  37  * API version 2.1:
  38  *  - Add openconnect_set_stoken_mode(), openconnect_has_stoken_support()
  39  *
  40  * API version 2.0:
  41  *  - OPENCONNECT_X509 is now an opaque type.
  42  *  - Add openconnect_has_pkcs11_support(), openconnect_has_tss_blob_support()
  43  *  - Rename openconnect_init_openssl() -> openconnect_init_ssl()
  44  *  - Rename openconnect_vpninfo_new_with_cbdata() -> openconnect_vpninfo_new()
  45  *    and kill the old openconnect_vpninfo_new() and its callback types.
  46  *
  47  * API version 1.5:
  48  *  - Add openconnect_get_cert_details(), openconnect_get_cert_DER().
  49  *
  50  * API version 1.4:
  51  *  - Add openconnect_set_cancel_fd()
  52  *
  53  * API version 1.3:
  54  *  - Add openconnect_set_cert_expiry_warning() to change from default 60 days
  55  *
  56  * API version 1.2:
  57  *  - Add openconnect_vpninfo_new_with_cbdata()
  58  *
  59  * API version 1.1:
  60  *  - Add openconnect_vpninfo_free()
  61  *
  62  * API version 1.0:
  63  *  - Initial version
  64  */
  65
  66 /* Before API version 1.4 (OpenConnect 3.19) this macro didn't exist.
  67  * Somewhat ironic, that the API version check itself needs to be
  68  * conditionally used depending on the API version. A very simple way
  69  * for users to handle this with an approximately correct answer is
  70  *   #include <openconnect.h>
  71  *   #ifndef OPENCONNECT_CHECK_VER
  72  *   #define OPENCONNECT_CHECK_VER(x,y) 0
  73  *   #endif
  74  */
  75 #define OPENCONNECT_CHECK_VER(maj,min) \
  76         (OPENCONNECT_API_VERSION_MAJOR > (maj) || \
  77         (OPENCONNECT_API_VERSION_MAJOR == (maj) && \
  78          OPENCONNECT_API_VERSION_MINOR >= (min)))
  79
  80 /****************************************************************************/
  81
  82 /* Authentication form processing */
  83
  84 #define OC_FORM_OPT_TEXT        1
  85 #define OC_FORM_OPT_PASSWORD    2
  86 #define OC_FORM_OPT_SELECT      3
  87 #define OC_FORM_OPT_HIDDEN      4
  88 #define OC_FORM_OPT_STOKEN      5
  89
  90 /* char * fields are static (owned by XML parser) and don't need to be
  91    freed by the form handling code -- except for value, which for TEXT
  92    and PASSWORD options is allocated by process_form() when
  93    interacting with the user and must be freed. */
  94 struct oc_form_opt {
  95         struct oc_form_opt *next;
  96         int type;
  97         char *name;
  98         char *label;
  99         char *value;
 100 };
 101
 102 /* All fields are static, owned by the XML parser */
 103 struct oc_choice {
 104         char *name;
 105         char *label;
 106         char *auth_type;
 107         char *override_name;
 108         char *override_label;
 109 };
 110
 111 struct oc_form_opt_select {
 112         struct oc_form_opt form;
 113         int nr_choices;
 114         struct oc_choice choices[0];
 115 };
 116
 117 /* All char * fields are static, owned by the XML parser */
 118 struct oc_auth_form {
 119         char *banner;
 120         char *message;
 121         char *error;
 122         char *auth_id;
 123         char *method;
 124         char *action;
 125         struct oc_form_opt *opts;
 126 };
 127
 128 /****************************************************************************/
 129
 130 #define PRG_ERR         0
 131 #define PRG_INFO        1
 132 #define PRG_DEBUG       2
 133 #define PRG_TRACE       3
 134
 135 struct openconnect_info;
 136
 137 #define OPENCONNECT_X509 void
 138
 139 /* Unless otherwise specified, all functions which set strings will take
 140    ownership of those strings and the library will free them later in
 141    openconnect_vpninfo_free() */
 142
 143
 144 /* The buffer 'buf' must be at least 41 bytes. It will receive a hex string
 145    with trailing NUL, representing the SHA1 fingerprint of the certificate. */
 146 int openconnect_get_cert_sha1(struct openconnect_info *vpninfo,
 147                               OPENCONNECT_X509 *cert, char *buf);
 148 char *openconnect_get_cert_details(struct openconnect_info *vpninfo,
 149                                    OPENCONNECT_X509 *cert);
 150 /* Returns the length of the created DER output, in a newly-allocated buffer
 151    that will need to be freed by the caller. */
 152 int openconnect_get_cert_DER(struct openconnect_info *vpninfo,
 153                              OPENCONNECT_X509 *cert, unsigned char **buf);
 154 int openconnect_set_http_proxy(struct openconnect_info *vpninfo, char *proxy);
 155 int openconnect_passphrase_from_fsid(struct openconnect_info *vpninfo);
 156 int openconnect_obtain_cookie(struct openconnect_info *vpninfo);
 157 void openconnect_init_ssl(void);
 158
 159 char *openconnect_get_vpn_name (struct openconnect_info *);
 160 char *openconnect_get_hostname (struct openconnect_info *);
 161 void openconnect_set_hostname (struct openconnect_info *, char *);
 162 char *openconnect_get_urlpath (struct openconnect_info *);
 163 void openconnect_set_urlpath (struct openconnect_info *, char *);
 164
 165 /* This function does *not* take ownership of the string; it is parsed
 166    and then discarded. */
 167 int openconnect_set_stoken_mode (struct openconnect_info *,
 168                                  int use_stoken, const char *token_str);
 169
 170 /* This function does *not* take ownership of the string; it's copied
 171    into a static buffer in the vpninfo. The size must be 41 bytes,
 172    since that's the size of a 20-byte SHA1 represented as hex with
 173    a trailing NUL. */
 174 void openconnect_set_xmlsha1 (struct openconnect_info *, const char *, int size);
 175
 176 void openconnect_set_cafile (struct openconnect_info *, char *);
 177 void openconnect_setup_csd (struct openconnect_info *, uid_t, int silent, char *wrapper);
 178 void openconnect_set_client_cert (struct openconnect_info *, char *cert, char *sslkey);
 179
 180 /* This is *not* yours and must not be destroyed with X509_free(). It
 181  * will be valid when a cookie has been obtained successfully, and will
 182  * be valid until the connection is destroyed or another attempt it made
 183  * to use it. */
 184 OPENCONNECT_X509 *openconnect_get_peer_cert (struct openconnect_info *);
 185
 186 int openconnect_get_port (struct openconnect_info *);
 187 char *openconnect_get_cookie (struct openconnect_info *);
 188 void openconnect_clear_cookie (struct openconnect_info *);
 189
 190 void openconnect_reset_ssl (struct openconnect_info *vpninfo);
 191 int openconnect_parse_url (struct openconnect_info *vpninfo, char *url);
 192 void openconnect_set_cert_expiry_warning (struct openconnect_info *vpninfo,
 193                                           int seconds);
 194
 195 /* If this is set, then openconnect_obtain_cookie() will abort and return
 196    failure if the file descriptor is readable. Typically a user may create
 197    a pair of pipes with the pipe(2) system call, hand the readable one to
 198    this function, and then write a byte to the other end if it ever wants
 199    to cancel the connection. This way, a multi-threaded UI (which will be
 200    running openconnect_obtain_cookie() in a separate thread since it blocks)
 201    has the ability to cancel that call, reap its thread and free the
 202    vpninfo structure (or retry). An 'fd' argument of -1 will render the
 203    cancellation mechanism inactive. */
 204 void openconnect_set_cancel_fd (struct openconnect_info *vpninfo, int fd);
 205
 206 const char *openconnect_get_version(void);
 207
 208 /* The first (privdata) argument to each of these functions is either
 209    the privdata argument provided to openconnect_vpninfo_new_with_cbdata(),
 210    or if that argument was NULL then it'll be the vpninfo itself. */
 211
 212 /* When the server's certificate fails validation via the normal means,
 213    this function is called with the offending certificate along with
 214    a textual reason for the failure (which may not be translated, if
 215    it comes directly from OpenSSL, but will be if it is rejected for
 216    "certificate does not match hostname", because that check is done
 217    in OpenConnect and *is* translated). The function shall return zero
 218    if the certificate is (or has in the past been) explicitly accepted
 219    by the user, and non-zero to abort the connection. */
 220 typedef int (*openconnect_validate_peer_cert_vfn) (void *privdata,
 221                                                    OPENCONNECT_X509 *cert,
 222                                                    const char *reason);
 223 /* On a successful connection, the server may provide us with a new XML
 224    configuration file. This contains the list of servers that can be
 225    chosen by the user to connect to, amongst other stuff that we mostly
 226    ignore. By "new", we mean that the SHA1 indicated by the server does
 227    not match the SHA1 set with the openconnect_set_xmlsha1() above. If
 228    they don't match, or openconnect_set_xmlsha1() has not been called,
 229    then the new XML is downloaded and this function is invoked. */
 230 typedef int (*openconnect_write_new_config_vfn) (void *privdata, char *buf,
 231                                                 int buflen);
 232 /* Handle an authentication form, requesting input from the user.
 233  * Return value:
 234  *  < 0, on error
 235  *  = 0, when form was parsed and POST required
 236  *  = 1, when response was cancelled by user
 237  */
 238 typedef int (*openconnect_process_auth_form_vfn) (void *privdata,
 239                                                  struct oc_auth_form *form);
 240 /* Logging output which the user *may* want to see. */
 241 typedef void __attribute__ ((format(printf, 3, 4)))
 242                 (*openconnect_progress_vfn) (void *privdata, int level,
 243                                             const char *fmt, ...);
 244 struct openconnect_info *openconnect_vpninfo_new (char *useragent,
 245                                                   openconnect_validate_peer_cert_vfn,
 246                                                   openconnect_write_new_config_vfn,
 247                                                   openconnect_process_auth_form_vfn,
 248                                                   openconnect_progress_vfn,
 249                                                   void *privdata);
 250 void openconnect_vpninfo_free (struct openconnect_info *vpninfo);
 251
 252 /* SSL certificate capabilities. openconnect_has_pkcs11_support() means that we
 253    can accept PKCS#11 URLs in place of filenames, for the certificate and key. */
 254 int openconnect_has_pkcs11_support(void);
 255
 256 /* The OpenSSL TPM ENGINE stores keys in a PEM file labelled with the string
 257    -----BEGIN TSS KEY BLOB-----. GnuTLS may learn to support this format too,
 258    in the near future. */
 259 int openconnect_has_tss_blob_support(void);
 260
 261 /* Software token capabilities. */
 262 int openconnect_has_stoken_support(void);
 263
 264 #endif /* __OPENCONNECT_H__ */