1 /* libmoonshot - Moonshot client library
2 * Copyright (c) 2011, JANET(UK)
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
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.
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.
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
32 * Author: Sam Thursfield <samthursfield@codethink.co.uk>
35 #ifndef __LIBMOONSHOT_H
36 #define __LIBMOONSHOT_H
40 * @pointer: pointer to be freed
42 * All the strings returned by the get_identity() functions must be
43 * freed using this function when they are no longer needed.
45 * @pointer may be %NULL, in which case no action is taken.
47 void moonshot_free (void *data);
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
58 int code; /* A MoonshotErrorCode */
63 * moonshot_error_free:
64 * @error: A #MoonshotError
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.
69 void moonshot_error_free (MoonshotError *error);
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
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
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
86 * @error: Return location for a #MoonshotError.
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.
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.
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().
103 * Return value: %TRUE if an identity was successfully selected, %FALSE on
106 int moonshot_get_identity (const char *nai,
107 const char *password,
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);
118 * moonshot_get_default_identity:
119 * @nai_out: A pointer to a string which receives the name and issuer of the
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
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
129 * @error: Return location for a #MoonshotError.
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().
135 * Return value: %TRUE if an identity was available, otherwise %FALSE.
137 int moonshot_get_default_identity (char **nai_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);
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.
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.
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
171 * Return value: %TRUE if the ID card was successfully added, %FALSE otherwise
173 int moonshot_install_id_card (const char *display_name,
174 const char *user_name,
175 const char *password,
177 char *rules_patterns[],
178 int rules_patterns_length,
179 char *rules_always_confirm[],
180 int rules_always_confirm_length,
185 const char *subject_alt,
186 const char *server_cert,
187 int force_flat_file_store,
188 MoonshotError **error);