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 typedef enum {
  39     MOONSHOT_ERROR_UNABLE_TO_START_SERVICE,
  40     MOONSHOT_ERROR_NO_IDENTITY_SELECTED,
  41     MOONSHOT_ERROR_INSTALLATION_ERROR,
  42     MOONSHOT_ERROR_OS_ERROR,
  43     MOONSHOT_ERROR_IPC_ERROR
  44 } MoonshotErrorCode;
  45
  46 typedef struct {
  47     MoonshotErrorCode  code;
  48     char              *message;
  49 } MoonshotError;
  50
  51 void moonshot_error_free (MoonshotError *error);
  52
  53 /**
  54  * moonshot_get_identity:
  55  * @nai: Name and issuer constraint for the required identity, or %NULL.
  56  * @password: Password for the identity, or %NULL.
  57  * @service: Service constraint for the required identity, or %NULL.
  58  * @nai_out: A pointer to a string which receives the name and issuer of the
  59  *           selected identity.
  60  * @password_out: A pointer to a string which receives the password.
  61  * @server_certificate_hash_out: Receives a hash of the identity server's
  62  *                               certificate, or %NULL.
  63  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
  64  *                      %NULL.
  65  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
  66  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
  67  *                                   %NULL.
  68  * @error: Return location for a #MoonshotError.
  69  *
  70  * This function calls the Moonshot server to request an ID card. The server
  71  * will be activated if it is not already running. The user interface will be
  72  * displayed if there is more than one matching identity and the user will be
  73  * asked to select one.
  74  *
  75  * There are two types of trust anchor that may be returned. If
  76  * @server_certificate_hash is non-empty, the remaining parameters will be
  77  * empty. Otherwise, the @ca_certificate parameter and the subject name
  78  * constraints will be returned.
  79  *
  80  * Error reporting is handled by a simple mechanism similar to #GError. If
  81  * an error occurs, as well as returning %FALSE a #MoonshotError object will
  82  * be stored at *@error, with a code and message string. This must be freed
  83  * using moonshot_error_free().
  84  *
  85  * Return value: %TRUE if an identity was successfully selected, %FALSE on
  86  *               failure.
  87  */
  88 int moonshot_get_identity (const char     *nai,
  89                            const char     *password,
  90                            const char     *service,
  91                            char          **nai_out,
  92                            char          **password_out,
  93                            char          **server_certificate_hash_out,
  94                            char          **ca_certificate_out,
  95                            char          **subject_name_constraint_out,
  96                            char          **subject_alt_name_constraint_out,
  97                            MoonshotError **error);
  98
  99 /**
 100  * moonshot_get_default_identity:
 101  * @nai_out: A pointer to a string which receives the name and issuer of the
 102  *           identity.
 103  * @password_out: A pointer to a string which receives the password.
 104  * @server_certificate_hash_out: Receives a hash of the identity server's
 105  *                               certificate, or %NULL.
 106  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
 107  *                      %NULL.
 108  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
 109  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
 110  *                                   %NULL.
 111  * @error: Return location for a #MoonshotError.
 112  *
 113  * This function calls the Moonshot server to request the default identity
 114  * (the one most recently used). Its semantics are otherwise the same as
 115  * moonshot_get_identity().
 116  *
 117  * Return value: %TRUE if an identity was available, otherwise %FALSE.
 118  */
 119 int moonshot_default_get_identity (char          **nai_out,
 120                                    char          **password_out,
 121                                    char          **server_certificate_hash_out,
 122                                    char          **ca_certificate_out,
 123                                    char          **subject_name_constraint_out,
 124                                    char          **subject_alt_name_constraint_out,
 125                                    MoonshotError **error);
 126
 127 #endif