libmoonshot/libmoonshot.h

   1 /* libmoonshot - Moonshot client library
   2  * Copyright (c) 2011, JANET(UK)
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * 3. Neither the name of JANET(UK) nor the names of its contributors
  17  *    may be used to endorse or promote products derived from this software
  18  *    without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  *
  32  * Author: Sam Thursfield <samthursfield@codethink.co.uk>
  33  */
  34
  35 #ifndef __LIBMOONSHOT_H
  36 #define __LIBMOONSHOT_H
  37
  38 /**
  39  * moonshot_free:
  40  * @pointer: pointer to be freed
  41  *
  42  * All the strings returned by the get_identity() functions must be
  43  * freed using this function when they are no longer needed.
  44  *
  45  * @pointer may be %NULL, in which case no action is taken.
  46  */
  47 void moonshot_free (void *data);
  48
  49 typedef enum {
  50     MOONSHOT_ERROR_UNABLE_TO_START_SERVICE,
  51     MOONSHOT_ERROR_NO_IDENTITY_SELECTED,
  52     MOONSHOT_ERROR_INSTALLATION_ERROR,
  53     MOONSHOT_ERROR_OS_ERROR,
  54     MOONSHOT_ERROR_IPC_ERROR
  55 } MoonshotErrorCode;
  56
  57 typedef struct {
  58     int   code;    /* A MoonshotErrorCode */
  59     char *message;
  60 } MoonshotError;
  61
  62 /**
  63  * moonshot_error_free:
  64  * @error: A #MoonshotError
  65  *
  66  * Releases the memory used by @error. This function must be called if
  67  * a function has returned an error, once it has been reported.
  68  */
  69 void moonshot_error_free (MoonshotError *error);
  70
  71 /**
  72  * moonshot_get_identity:
  73  * @nai: Name and issuer constraint for the required identity, or %NULL.
  74  * @password: Password for the identity, or %NULL.
  75  * @service: Service constraint for the required identity, or %NULL.
  76  * @nai_out: A pointer to a string which receives the name and issuer of the
  77  *           selected identity.
  78  * @password_out: A pointer to a string which receives the password.
  79  * @server_certificate_hash_out: Receives a hash of the identity server's
  80  *                               certificate, or %NULL.
  81  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
  82  *                      %NULL.
  83  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
  84  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
  85  *                                   %NULL.
  86  * @error: Return location for a #MoonshotError.
  87  *
  88  * This function calls the Moonshot server to request an ID card. The server
  89  * will be activated if it is not already running. The user interface will be
  90  * displayed if there is more than one matching identity and the user will be
  91  * asked to select one.
  92  *
  93  * There are two types of trust anchor that may be returned. If
  94  * @server_certificate_hash is non-empty, the remaining parameters will be
  95  * empty. Otherwise, the @ca_certificate parameter and the subject name
  96  * constraints will be returned.
  97  *
  98  * Error reporting is handled by a simple mechanism similar to #GError. If
  99  * an error occurs, as well as returning %FALSE a #MoonshotError object will
 100  * be stored at *@error, with a code and message string. This must be freed
 101  * using moonshot_error_free().
 102  *
 103  * Return value: %TRUE if an identity was successfully selected, %FALSE on
 104  *               failure.
 105  */
 106 int moonshot_get_identity (const char     *nai,
 107                            const char     *password,
 108                            const char     *service,
 109                            char          **nai_out,
 110                            char          **password_out,
 111                            char          **server_certificate_hash_out,
 112                            char          **ca_certificate_out,
 113                            char          **subject_name_constraint_out,
 114                            char          **subject_alt_name_constraint_out,
 115                            MoonshotError **error);
 116
 117 /**
 118  * moonshot_get_default_identity:
 119  * @nai_out: A pointer to a string which receives the name and issuer of the
 120  *           identity.
 121  * @password_out: A pointer to a string which receives the password.
 122  * @server_certificate_hash_out: Receives a hash of the identity server's
 123  *                               certificate, or %NULL.
 124  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
 125  *                      %NULL.
 126  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
 127  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
 128  *                                   %NULL.
 129  * @error: Return location for a #MoonshotError.
 130  *
 131  * This function calls the Moonshot server to request the default identity
 132  * (the one most recently used). Its semantics are otherwise the same as
 133  * moonshot_get_identity().
 134  *
 135  * Return value: %TRUE if an identity was available, otherwise %FALSE.
 136  */
 137 int moonshot_get_default_identity (char          **nai_out,
 138                                    char          **password_out,
 139                                    char          **server_certificate_hash_out,
 140                                    char          **ca_certificate_out,
 141                                    char          **subject_name_constraint_out,
 142                                    char          **subject_alt_name_constraint_out,
 143                                    MoonshotError **error);
 144
 145
 146 /**
 147  * moonshot_install_id_card:
 148  * @display_name: Display name of card
 149  * @user_name: Username for identity, or %NULL
 150  * @password: Password for identity, or %NULL
 151  * @realm: Realm for identity, or %NULL
 152  * @rules_patterns: Array of patterns for the service matching rules
 153  * @rules_patterns_length: Length of @rules_patterns and @rules_always_confirm arrays
 154  * @rules_always_confirm: Array of 'always confirm' flags corresponding to patterns
 155  * @rules_always_confirm_length: Length of @rules_patterns and @rules_always_confirm arrays
 156  * @services: Array of strings listing the services this identity provides
 157  * @services_length: Length of @services array
 158  * @ca_cert: The CA certificate, or %NULL
 159  * @subject: Subject name constraint for @ca_cert, or %NULL
 160  * @subject_alt: Subject alternative name constraint for @ca_cert, or %NULL
 161  * @server_cert: Hash of the server certificate; required if @ca_cert is %NULL
 162  * @error: Return location for a #MoonshotError.
 163  *
 164  * Calls the Moonshot server to add a new identity. The user will be prompted
 165  * if they would like to add the ID card.
 166  *
 167  * The values for @rules_patterns_length and @rules_always_confirm_length should
 168  * always be the same. They are present as separate parameters as a concession to
 169  * the Vala bindings.
 170  *
 171  * Return value: %TRUE if the ID card was successfully added, %FALSE otherwise
 172  */
 173 int moonshot_install_id_card (const char     *display_name,
 174                               const char     *user_name,
 175                               const char     *password,
 176                               const char     *realm,
 177                               char           *rules_patterns[],
 178                               int             rules_patterns_length,
 179                               char           *rules_always_confirm[],
 180                               int             rules_always_confirm_length,
 181                               char           *services[],
 182                               int             services_length,
 183                               const char     *ca_cert,
 184                               const char     *subject,
 185                               const char     *subject_alt,
 186                               const char     *server_cert,
 187                               int             force_flat_file_store,
 188                               MoonshotError **error);
 189
 190
 191
 192 /**
 193  * moonshot_confirm_ca_certificate
 194  * @
 195  * Return value: %TRUE if the certificate is approved; %FALSE otherwise
 196  */
 197
 198 int moonshot_confirm_ca_certificate (const char           *identity_name,
 199                                      const char           *realm,
 200                                      const unsigned char  *sha256,
 201                                      int                   sha256_length,
 202                                      MoonshotError       **error);
 203
 204
 205 #endif