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_OS_ERROR,
42 MOONSHOT_ERROR_IPC_ERROR
46 MoonshotErrorCode code;
50 void moonshot_error_free (MoonshotError *error);
53 * moonshot_get_identity:
54 * @nai: Name and issuer constraint for the required identity, or %NULL.
55 * @password: Password for the identity, or %NULL.
56 * @service: Service constraint for the required identity, or %NULL.
57 * @nai_out: A pointer to a string which receives the name and issuer of the
59 * @password_out: A pointer to a string which receives the password.
60 * @server_certificate_hash_out: Receives a hash of the identity server's
61 * certificate, or %NULL.
62 * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
64 * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
65 * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
67 * @error: Return location for a #MoonshotError, or %NULL.
69 * This function calls the Moonshot server to request an ID card. The server
70 * will be activated if it is not already running. The user interface will be
71 * displayed if there is more than one matching identity and the user will be
72 * asked to select one.
74 * There are two types of trust anchor that may be returned. If
75 * @server_certificate_hash is non-empty, the remaining parameters will be
76 * empty. Otherwise, the @ca_certificate parameter and the subject name
77 * constraints will be returned.
79 * Error reporting is handled by a simple mechanism similar to #GError. If
80 * an error occurs, a #MoonshotError object will be stored at *@error, with
81 * a code and message string. This must be freed using moonshot_error_free().
83 * Return value: %TRUE if an identity was successfully selected, %FALSE on
86 int moonshot_get_identity (const char *nai,
91 char **server_certificate_hash_out,
92 char **ca_certificate_out,
93 char **subject_name_constraint_out,
94 char **subject_alt_name_constraint_out,
95 MoonshotError **error);