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
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
47 MoonshotErrorCode code;
51 void moonshot_error_free (MoonshotError *error);
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
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
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
68 * @error: Return location for a #MoonshotError.
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.
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.
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().
85 * Return value: %TRUE if an identity was successfully selected, %FALSE on
88 int moonshot_get_identity (const char *nai,
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);
100 * moonshot_get_default_identity:
101 * @nai_out: A pointer to a string which receives the name and issuer of the
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
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
111 * @error: Return location for a #MoonshotError.
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().
117 * Return value: %TRUE if an identity was available, otherwise %FALSE.
119 int moonshot_default_get_identity (char **nai_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);