Release 1.25.0 -- Buddy Idle Time, RTF
[siplcs.git] / src / core / sip-sec.h
blob00237a9a06f32ec3c3c6c6c8d8aea76ad169a067
1 /**
2 * @file sip-sec.h
4 * pidgin-sipe
6 * Copyright (C) 2010-2015 SIPE Project <http://sipe.sourceforge.net/>
7 * Copyright (C) 2009 pier11 <pier11@operamail.com>
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25 /* Opaque type definition for security context */
26 typedef struct sip_sec_context *SipSecContext;
28 /*** Sipe convenience methods ***/
30 /**
31 * Initializes Sipe security context.
32 * Obtains cashed initial credentials (TGT for Kerberos) or requests new ones if required.
33 * In former case domain/username/password information is unnecessary.
35 * @param type (in) authentication type
36 * @param sso (in) @c TRUE if Single Sign-On should be used
37 * @param http (in) @c TRUE if HTTP, @c FALSE for SIP
38 * @param username (in) user name (can be NULL) (ignored for SSO)
39 * @param password (in) password (can be NULL) (ignored for SSO)
41 * @return context security context to store and pass between security method invocations
43 SipSecContext
44 sip_sec_create_context(guint type,
45 gboolean sso,
46 gboolean http,
47 const gchar *username,
48 const gchar *password);
50 /**
51 * Obtains Service ticket (for Kerberos), base64 encodes it and provide as output.
53 * @param context (in) security context to pass between security method invocations
54 * @param target (in) security target. Service principal name on case of Kerberos.
55 * @param input_toked_base64 (in) base64 encoded input security token. This is Type2 NTLM message or NULL.
56 * @param output_toked_base64 (out) base64 encoded output token to send to server.
57 * @param expires (out) security context expiration time in seconds.
59 * @return @c TRUE if successful
62 gboolean
63 sip_sec_init_context_step(SipSecContext context,
64 const gchar *target,
65 const gchar *input_toked_base64,
66 gchar **output_toked_base64,
67 guint *expires);
69 /**
70 * Check if the authentication of a security context is completed and it is
71 * ready to be used for message signing and signature verification
73 * @param context (in) security context. May be @c NULL.
75 * @return @c TRUE if authentication is completed
77 gboolean sip_sec_context_is_ready(SipSecContext context);
79 /**
80 * Return authentication name of a security context
82 * @param context (in) security context. May be @c NULL.
84 * @return string or @c NULL
86 const gchar *sip_sec_context_name(SipSecContext context);
88 /**
89 * Return type of a security context
91 * @param context (in) security context. May be @c NULL.
93 * @return context type or @c SIPE_SIPE_AUTHENTICATION_TYPE_UNSET
95 guint sip_sec_context_type(SipSecContext context);
97 /**
98 * A convenience method for sipe.
99 * Destroys security context.
101 * @param context (in,out) security context to destroy
103 void sip_sec_destroy_context(SipSecContext context);
106 * A convenience method for sipe.
107 * Signs incoming message.
109 * @param context (in) security context
110 * @param message (in) a message to sign.
112 * @return signature for the message. Converted to Hex null terminated string;
114 gchar *sip_sec_make_signature(SipSecContext context,
115 const gchar *message);
118 * A convenience method for sipe.
119 * Verifies signature for the message.
121 * @param context (in) security context
122 * @param message (in) which signature to verify. Null terminated string.
123 * @param signature_hex (in) signature to test in Hex representation. Null terminated string. Example: "602306092A864886F71201020201011100FFFFFFFF1A306ACB7BE311827BBF7208D80D15E3"
125 * @return FALSE on error
127 gboolean sip_sec_verify_signature(SipSecContext context,
128 const gchar *message,
129 const gchar *signature_hex);
132 * Check if authentication scheme requires a password
134 * @param type authentication type
135 * @param sso TRUE if user selected Single-Sign On
137 * @return @c TRUE if password is required
139 gboolean sip_sec_requires_password(guint authentication,
140 gboolean sso);
143 * Initialize & destroy functions for sip-sec.
144 * Should be called on loading and unloading of the core.
146 void sip_sec_init(void);
147 void sip_sec_destroy(void);