auth-helper.h 14.7 KB
Newer Older
jehan's avatar
jehan committed
1 2 3 4 5 6
/*
	belle-sip - SIP (RFC3261) library.
    Copyright (C) 2010  Belledonne Communications SARL

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
7
    the Free Software Foundation, either version 2 of the License, or
jehan's avatar
jehan committed
8 9 10 11 12 13 14 15 16 17 18 19 20
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef AUTHENTICATION_HELPER_H_
#define AUTHENTICATION_HELPER_H_
21 22

#include "belle-sip/defs.h"
jehan's avatar
jehan committed
23
#include "belle-sip/belle-sip.h"
24
#include "bctoolbox/crypto.h"
jehan's avatar
jehan committed
25

26 27 28
#define MAX_LENGTH_BYTE 32
#define MAX_RESPONSE_SIZE 65

Guillaume Beraudo's avatar
Guillaume Beraudo committed
29 30
BELLE_SIP_BEGIN_DECLS

jehan's avatar
jehan committed
31 32 33 34 35 36
/**
 * Create an authorization header from an www_authenticate header, all common parameters are copyed.
 * copy params: scheme, realm, nonce, algorithm, opaque
 * @param authentication source to be used as input
 * @return belle_sip_header_authorization_t*
 */
37
BELLESIP_EXPORT belle_sip_header_authorization_t* belle_sip_auth_helper_create_authorization(const belle_sip_header_www_authenticate_t* authentication);
jehan's avatar
jehan committed
38

jehan's avatar
jehan committed
39 40 41 42 43 44 45
/**
 * Create an www_authenticate header from an authorization header, all common parameters are copyed.
 * copy params: scheme, realm, nonce, algorithm, opaque
 * @param authorization source to be used as input
 * @return belle_sip_header_www_authenticate_t*
 */
BELLESIP_EXPORT belle_sip_header_www_authenticate_t* belle_sip_auth_helper_create_www_authenticate(const belle_sip_header_authorization_t* authorization);
jehan's avatar
jehan committed
46 47 48 49 50 51 52 53 54
/**
 * Create an http authorization header from an www_authenticate header, all common parameters are copyed.
 * copy params: scheme, realm, nonce, algorithm, opaque
 * @param authentication source to be used as input
 * @return belle_http_header_authorization_t*
 */
BELLESIP_EXPORT belle_http_header_authorization_t* belle_http_auth_helper_create_authorization(const belle_sip_header_www_authenticate_t* authentication);


jehan's avatar
jehan committed
55 56 57 58 59 60
/**
 * Create an proxy_authorization header from an www_authenticate header, all common parameters are copyed.
 * copy params: scheme, realm, nonce, algorithm, opaque
 * @param authentication source to be used as input
 * @return belle_sip_header_authorization_t*
 */
61
BELLESIP_EXPORT belle_sip_header_proxy_authorization_t* belle_sip_auth_helper_create_proxy_authorization(const belle_sip_header_proxy_authenticate_t* proxy_authentication);
jehan's avatar
jehan committed
62

63 64 65 66 67 68
/**
 * return size which depends on algorithm
 * @return 0 if failed
 */
BELLESIP_EXPORT int belle_sip_auth_define_size(const char* algo);

jehan's avatar
jehan committed
69 70
/**
 * compute and set response value according to parameters
jehan's avatar
jehan committed
71
 * HA1=MD5(username:realm:passwd)
jehan's avatar
jehan committed
72 73 74
 * fills cnonce if needed (qop=auth);
 * fills qop
 *
jehan's avatar
jehan committed
75 76
 * @return 0 if succeed
 */
77
BELLESIP_EXPORT int belle_sip_auth_helper_fill_authorization(belle_sip_header_authorization_t* authorization
jehan's avatar
jehan committed
78
												,const char* method
jehan's avatar
jehan committed
79
												,const char* ha1);
80

jehan's avatar
jehan committed
81 82 83 84
/**
 * compute and set response value according to parameters
 * @return 0 if succeed
 */
85
BELLESIP_EXPORT int belle_sip_auth_helper_fill_proxy_authorization(belle_sip_header_proxy_authorization_t* proxy_authorization
jehan's avatar
jehan committed
86
												,const char* method
jehan's avatar
jehan committed
87
												,const char* ha1);
jehan's avatar
jehan committed
88

jehan's avatar
jehan committed
89 90 91 92 93
/*
 * compute HA1 (NULL terminated)
 * HA1=MD5(userid:realm:passwd)
 * return 0 in case of success
 * */
94
BELLESIP_EXPORT int belle_sip_auth_helper_compute_ha1(const char* userid,const char* realm,const char* password, char ha1[33]);
95 96 97 98 99
/*
 * compute HA1 (NULL terminated)
 * HA1=MD5(userid:realm:passwd) or SHA-256(userid:realm:passwd)
 * return 0 in case of success
 * */
100
BELLESIP_EXPORT int belle_sip_auth_helper_compute_ha1_for_algorithm(const char* userid,const char* realm,const char* password, char *ha1, size_t size, const char* algo);
jehan's avatar
jehan committed
101 102 103 104 105
/*
 * compute HA2 (NULL terminated)
 * HA2=MD5(method:uri)
 * return 0 in case of success
 * */
106
BELLESIP_EXPORT int belle_sip_auth_helper_compute_ha2(const char* method,const char* uri, char ha2[33]);
jehan's avatar
jehan committed
107

108 109 110 111 112 113
/*
 * compute HA2 (NULL terminated)
 * HA2=MD5(method:uri) or SHA-256(method:uri)
 * return 0 in case of success
 * */
BELLESIP_EXPORT int belle_sip_auth_helper_compute_ha2_for_algorithm(const char* method,const char* uri, char *ha2, size_t size, const char* algo);
jehan's avatar
jehan committed
114 115 116 117 118
/*
 * compute response(NULL terminated)
 * res=MD5(ha1:nonce:ha2)
 * return 0 in case of success
 * */
119
BELLESIP_EXPORT int belle_sip_auth_helper_compute_response(const char* ha1,const char* nonce, const char* ha2, char response[33]);
jehan's avatar
jehan committed
120

121 122 123 124 125 126
/*
 * compute response(NULL terminated)
 * res=MD5(ha1:nonce:ha2) or SHA-256(ha1:nonce:ha2)
 * return 0 in case of success
 * */
BELLESIP_EXPORT int belle_sip_auth_helper_compute_response_for_algorithm(const char* ha1,const char* nonce, const char* ha2, char *response, size_t size, const char* algo);
jehan's avatar
jehan committed
127 128 129 130 131
/*
 * compute response(NULL terminated)
 * res=MD5(HA1:nonce:nonce_count:cnonce:qop:HA2)
 * return 0 in case of success
 * */
132
BELLESIP_EXPORT int belle_sip_auth_helper_compute_response_qop_auth(	const char* ha1
jehan's avatar
jehan committed
133 134 135 136 137 138 139
													, const char* nonce
													, unsigned int nonce_count
													, const char* cnonce
													, const char* qop
													, const char* ha2
													, char response[33]);

140 141 142 143 144 145 146 147 148 149 150 151 152
/*
 * compute response(NULL terminated)
 * res=MD5(HA1:nonce:nonce_count:cnonce:qop:HA2) or SHA-256(HA1:nonce:nonce_count:cnonce:qop:HA2)
 * return 0 in case of success
 * */
BELLESIP_EXPORT int belle_sip_auth_helper_compute_response_qop_auth_for_algorithm(const char* ha1
                                                                  , const char* nonce
                                                                  , unsigned int nonce_count
                                                                  , const char* cnonce
                                                                  , const char* qop
                                                                  , const char* ha2
                                                                  , char *response
                                                                  , size_t size, const char* algo);
jehan's avatar
jehan committed
153
/*TLS client certificate auth*/
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168

/**
 * Set TLS certificate verification callback
 *
 * @param callback function pointer for callback, or NULL to unset
 *
 * Callback signature is:
 * int (*verify_cb_error_cb_t)(unsigned char* der, int length, int depth, int* flags);
 * der - raw certificate data, in DER format
 * length - length of certificate DER data
 * depth - position of certificate in cert chain, ending at 0 = root or top
 * flags - verification state for CURRENT certificate only
 */
BELLESIP_EXPORT int belle_sip_tls_set_verify_error_cb(void *callback);

jehan's avatar
jehan committed
169 170
/**
 * Format of certificate buffer
171
 **/
jehan's avatar
jehan committed
172 173 174
typedef enum  belle_sip_certificate_raw_format {
	BELLE_SIP_CERTIFICATE_RAW_FORMAT_PEM, /** PEM format*/
	BELLE_SIP_CERTIFICATE_RAW_FORMAT_DER /** ASN.1 raw format*/
175 176 177
}belle_sip_certificate_raw_format_t;

/**
jehan's avatar
jehan committed
178 179 180 181
 * Parse a buffer containing either a certificate chain order in PEM format or a single DER cert
 * @param buff raw buffer
 * @param size buffer size
 * @param format either PEM or DER
182
 * @return  belle_sip_certificates_chain_t or NULL if cannot be decoded
jehan's avatar
jehan committed
183 184
 */
BELLESIP_EXPORT belle_sip_certificates_chain_t* belle_sip_certificates_chain_parse(const char* buff, size_t size,belle_sip_certificate_raw_format_t format);
185

jehan's avatar
jehan committed
186
/**
187
 * Parse a buffer containing either a private or public rsa key in PEM format
jehan's avatar
jehan committed
188 189 190
 * @param buff raw buffer
 * @param size buffer size
 * @param passwd password (optionnal)
191
 * @return list of belle_sip_signing_key_t or NULL if cannot be decoded
jehan's avatar
jehan committed
192 193 194
 */
BELLESIP_EXPORT belle_sip_signing_key_t* belle_sip_signing_key_parse(const char* buff, size_t size,const char* passwd);

195 196 197 198 199 200 201 202
/**
 * Parse a pather containing either a certificate chain order in PEM format or a single DER cert
 * @param path file
 * @param format either PEM or DER
 * @return  belle_sip_certificates_chain_t or NUL if cannot be decoded
 */
BELLESIP_EXPORT belle_sip_certificates_chain_t* belle_sip_certificates_chain_parse_file(const char* path, belle_sip_certificate_raw_format_t format);

203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
/**
 * Parse a directory for *.pem file containing a certificate and private key in PEM format or a single DER cert with subject CNAME as given
 *
 * @param[in]	path			directory to parse
 * @param[in]	subject			subject CNAME to look for
 * @param[out]	certificate		result certificate, NULL if not found. Is allocated by this function, caller must do a belle_sip_object_unref on it after use
 * @param[out]	pkey			result private key, NULL if not found. Is allocated by this function, caller must do a belle_sip_object_unref on it after use
 * @param[in]	format			either PEM or DER
 * @return  0 if we found a certificate and key matching given subject common name
 */
BELLESIP_EXPORT int belle_sip_get_certificate_and_pkey_in_dir(const char *path, const char *subject, belle_sip_certificates_chain_t **certificate, belle_sip_signing_key_t **pkey, belle_sip_certificate_raw_format_t format);

/**
 * Generate a self signed certificate and key and save them in a file if a path is given, file will be <subject>.pem
 *
 * @param[in]	path		If not NULL a file will be written in the given directory. filename is <subject>.pem
 * @param[in]	subject		used in the CN= field of issuer and subject name
 * @param[out]	certificate	the generated certificate. Must be destroyed using belle_sip_certificates_chain_destroy
 * @param[out]	key			the generated key. Must be destroyed using belle_sip_signing_key_destroy
 * @return 0 on success
 */
BELLESIP_EXPORT int belle_sip_generate_self_signed_certificate(const char* path, const char *subject, belle_sip_certificates_chain_t **certificate, belle_sip_signing_key_t **pkey);

/**
 * Convert a certificate into a its PEM format string
 *
 * @param[in]	cert	The certificate to be converted into PEM format string
 * @return	the PEM representation of certificate. Buffer is allocated by this function and must be freed by caller
 */
232
BELLESIP_EXPORT char *belle_sip_certificates_chain_get_pem(belle_sip_certificates_chain_t *cert);
233 234 235 236 237 238 239

/**
 * Convert a key into a its PEM format string
 *
 * @param[in]	key		The key to be converted into PEM format string
 * @return	the PEM representation of key. Buffer is allocated by this function and must be freed by caller
 */
240
BELLESIP_EXPORT char *belle_sip_signing_key_get_pem(belle_sip_signing_key_t *key);
241 242 243 244 245 246 247 248

/**
 * Generate a certificate fingerprint as described in RFC4572
 * Note: only SHA1 signing algo is supported for now
 *
 * @param[in]	certificate		The certificate used to generate the fingerprint
 * @return		The generated fingerprint formatted according to RFC4572 section 5. Is a null terminated string, must be freed by caller
 */
249
BELLESIP_EXPORT char *belle_sip_certificates_chain_get_fingerprint(belle_sip_certificates_chain_t *certificate);
250

251 252 253 254 255 256 257 258
/**
 * Parse a pather containing either a private or public rsa key
 * @param path file
 * @param passwd password (optionnal)
 * @return list of belle_sip_signing_key_t or NUL iff cannot be decoded
 */
BELLESIP_EXPORT belle_sip_signing_key_t* belle_sip_signing_key_parse_file(const char* path, const char* passwd);

259
#define BELLE_TLS_VERIFY_NONE		(0)
260 261
#define BELLE_TLS_VERIFY_CN_MISMATCH (1)
#define BELLE_TLS_VERIFY_ANY_REASON (0xff)
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
/* Set of functions deprecated on 2016/02/02 use the belle_tls_crypto_config_XXX ones */
BELLESIP_DEPRECATED BELLESIP_EXPORT belle_tls_verify_policy_t *belle_tls_verify_policy_new(void);
BELLESIP_DEPRECATED BELLESIP_EXPORT int belle_tls_verify_policy_set_root_ca(belle_tls_verify_policy_t *obj, const char *path);
BELLESIP_DEPRECATED BELLESIP_EXPORT void belle_tls_verify_policy_set_exceptions(belle_tls_verify_policy_t *obj, int flags);
BELLESIP_DEPRECATED BELLESIP_EXPORT unsigned int belle_tls_verify_policy_get_exceptions(const belle_tls_verify_policy_t *obj);


/**
 * Create a new crypto configuration object
 * The crypto configuration may be passed to a http provider or a listening point using the appropriate methods
 * It can be used to provide :
 * - a path to the trusted root certificates
 * - a way to override certificate verification exceptions
 * - a ssl configuration structure provided directly to the underlying crypto library (mbedtls 2 or above),
 * @return an empty belle_tls_crypto_config object, trusted certificate path is initialised to the default system path without any warranty
 */
BELLESIP_EXPORT belle_tls_crypto_config_t *belle_tls_crypto_config_new(void);

/**
 * Set the path to the trusted certificate chain
 * @param[in/out]	obj		The crypto configuration object to set
 * @param[in]		path	The path to the trusted certificate chain file(NULL terminated string)
 *
 * @return 0 on success
 */
BELLESIP_EXPORT int belle_tls_crypto_config_set_root_ca(belle_tls_crypto_config_t *obj, const char *path);

289 290 291 292 293 294 295 296 297
/**
 * Set the content of the trusted certificate chain
 * @param[in/out]	obj		The crypto configuration object to set
 * @param[in]		data	The content to the trusted certificate chain data(NULL terminated string)
 *
 * @return 0 on success
 */
BELLESIP_EXPORT int belle_tls_crypto_config_set_root_ca_data(belle_tls_crypto_config_t *obj, const char *data);

298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
/**
 * Set the exception flags to manage exception overriding during peer certificate verification
 * @param[in/out]	obj		The crypto configuration object to set
 * @param[in]		flags	Flags value to set:
 * 							BELLE_TLS_VERIFY_NONE to raise and error on any exception
 * 							BELLE_TLS_VERIFY_CN_MISMATCH to ignore Common Name mismatch
 * 							BELLE_TLS_VERIFY_ANY_REASON to ignore any exception
 *
 * @return 0 on success
 */
BELLESIP_EXPORT void belle_tls_crypto_config_set_verify_exceptions(belle_tls_crypto_config_t *obj, int flags);

/**
 * Get the exception flags used to manage exception overriding during peer certificate verification
 * @param[in]i		obj		The crypto configuration object to set
 * @return			Possible flags value :
 * 							BELLE_TLS_VERIFY_NONE to raise and error on any exception
 * 							BELLE_TLS_VERIFY_CN_MISMATCH to ignore Common Name mismatch
 * 							BELLE_TLS_VERIFY_ANY_REASON to ignore any exception
 *
 */
BELLESIP_EXPORT unsigned int belle_tls_crypto_config_get_verify_exceptions(const belle_tls_crypto_config_t *obj);

/**
 * Set the pointer to an externally provided ssl configuration for the crypto library
 * @param[in/out]	obj			The crypto configuration object to set
 * @param[in]		ssl_config	A pointer to an opaque structure which will be provided directly to the crypto library used in bctoolbox. Use with extra care.
 * 								This ssl_config structure is responsability of the caller and will not be freed at the connection's end.
 */
BELLESIP_EXPORT void belle_tls_crypto_config_set_ssl_config(belle_tls_crypto_config_t *obj, void *ssl_config);
328

Guillaume Beraudo's avatar
Guillaume Beraudo committed
329
BELLE_SIP_END_DECLS
jehan's avatar
jehan committed
330

jehan's avatar
jehan committed
331
#endif /* AUTHENTICATION_HELPER_H_ */