1/** 2 * @copyright 3 * ==================================================================== 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_cmdline.h 24 * @brief Support functions for command line programs 25 */ 26 27 28 29 30#ifndef SVN_CMDLINE_H 31#define SVN_CMDLINE_H 32 33#include <apr_pools.h> 34#include <apr_getopt.h> 35 36#ifndef DOXYGEN_SHOULD_SKIP_THIS 37#define APR_WANT_STDIO 38#endif 39#include <apr_want.h> 40 41#include "svn_types.h" 42#include "svn_auth.h" 43#include "svn_config.h" 44 45#ifdef __cplusplus 46extern "C" { 47#endif /* __cplusplus */ 48 49 50/** Set up the locale for character conversion, and initialize APR. 51 * If @a error_stream is non-NULL, print error messages to the stream, 52 * using @a progname as the program name. Attempt to set @c stdout to 53 * line-buffered mode, and @a error_stream to unbuffered mode. Return 54 * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE. 55 * 56 * @note This function should be called exactly once at program startup, 57 * before calling any other APR or Subversion functions. 58 */ 59int 60svn_cmdline_init(const char *progname, 61 FILE *error_stream); 62 63 64/** Set @a *dest to an output-encoded C string from UTF-8 C string @a 65 * src; allocate @a *dest in @a pool. 66 */ 67svn_error_t * 68svn_cmdline_cstring_from_utf8(const char **dest, 69 const char *src, 70 apr_pool_t *pool); 71 72/** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an 73 * output-encoded C string. */ 74const char * 75svn_cmdline_cstring_from_utf8_fuzzy(const char *src, 76 apr_pool_t *pool); 77 78/** Set @a *dest to a UTF-8-encoded C string from input-encoded C 79 * string @a src; allocate @a *dest in @a pool. 80 */ 81svn_error_t * 82svn_cmdline_cstring_to_utf8(const char **dest, 83 const char *src, 84 apr_pool_t *pool); 85 86/** Set @a *dest to an output-encoded natively-formatted path string 87 * from canonical path @a src; allocate @a *dest in @a pool. 88 */ 89svn_error_t * 90svn_cmdline_path_local_style_from_utf8(const char **dest, 91 const char *src, 92 apr_pool_t *pool); 93 94/** Write to stdout, using a printf-like format string @a fmt, passed 95 * through apr_pvsprintf(). All string arguments are in UTF-8; the output 96 * is converted to the output encoding. Use @a pool for temporary 97 * allocation. 98 * 99 * @since New in 1.1. 100 */ 101svn_error_t * 102svn_cmdline_printf(apr_pool_t *pool, 103 const char *fmt, 104 ...) 105 __attribute__((format(printf, 2, 3))); 106 107/** Write to the stdio @a stream, using a printf-like format string @a fmt, 108 * passed through apr_pvsprintf(). All string arguments are in UTF-8; 109 * the output is converted to the output encoding. Use @a pool for 110 * temporary allocation. 111 * 112 * @since New in 1.1. 113 */ 114svn_error_t * 115svn_cmdline_fprintf(FILE *stream, 116 apr_pool_t *pool, 117 const char *fmt, 118 ...) 119 __attribute__((format(printf, 3, 4))); 120 121/** Output the @a string to the stdio @a stream, converting from UTF-8 122 * to the output encoding. Use @a pool for temporary allocation. 123 * 124 * @since New in 1.1. 125 */ 126svn_error_t * 127svn_cmdline_fputs(const char *string, 128 FILE *stream, 129 apr_pool_t *pool); 130 131/** Flush output buffers of the stdio @a stream, returning an error if that 132 * fails. This is just a wrapper for the standard fflush() function for 133 * consistent error handling. 134 * 135 * @since New in 1.1. 136 */ 137svn_error_t * 138svn_cmdline_fflush(FILE *stream); 139 140/** Return the name of the output encoding allocated in @a pool, or @c 141 * APR_LOCALE_CHARSET if the output encoding is the same as the locale 142 * encoding. 143 * 144 * @since New in 1.3. 145 */ 146const char * 147svn_cmdline_output_encoding(apr_pool_t *pool); 148 149/** Handle @a error in preparation for immediate exit from a 150 * command-line client. Specifically: 151 * 152 * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear 153 * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE. 154 * 155 * @since New in 1.3. 156 */ 157int 158svn_cmdline_handle_exit_error(svn_error_t *error, 159 apr_pool_t *pool, 160 const char *prefix); 161 162/** A prompt function/baton pair, and the path to the configuration 163 * directory. To be passed as the baton argument to the 164 * @c svn_cmdline_*_prompt functions. 165 * 166 * @since New in 1.6. 167 */ 168typedef struct svn_cmdline_prompt_baton2_t { 169 svn_cancel_func_t cancel_func; 170 void *cancel_baton; 171 const char *config_dir; 172} svn_cmdline_prompt_baton2_t; 173 174/** Like svn_cmdline_prompt_baton2_t, but without the path to the 175 * configuration directory. 176 * 177 * @since New in 1.4. 178 * @deprecated Provided for backward compatibility with the 1.5 API. 179 */ 180typedef struct svn_cmdline_prompt_baton_t { 181 svn_cancel_func_t cancel_func; 182 void *cancel_baton; 183} svn_cmdline_prompt_baton_t; 184 185/** Prompt the user for input, using @a prompt_str for the prompt and 186 * @a baton (which may be @c NULL) for cancellation, and returning the 187 * user's response in @a result, allocated in @a pool. 188 * 189 * @since New in 1.5. 190 */ 191svn_error_t * 192svn_cmdline_prompt_user2(const char **result, 193 const char *prompt_str, 194 svn_cmdline_prompt_baton_t *baton, 195 apr_pool_t *pool); 196 197/** Similar to svn_cmdline_prompt_user2, but without cancellation 198 * support. 199 * 200 * @deprecated Provided for backward compatibility with the 1.4 API. 201 */ 202SVN_DEPRECATED 203svn_error_t * 204svn_cmdline_prompt_user(const char **result, 205 const char *prompt_str, 206 apr_pool_t *pool); 207 208/** An implementation of @c svn_auth_simple_prompt_func_t that prompts 209 * the user for keyboard input on the command line. 210 * 211 * @since New in 1.4. 212 * 213 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 214 */ 215svn_error_t * 216svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p, 217 void *baton, 218 const char *realm, 219 const char *username, 220 svn_boolean_t may_save, 221 apr_pool_t *pool); 222 223 224/** An implementation of @c svn_auth_username_prompt_func_t that prompts 225 * the user for their username via the command line. 226 * 227 * @since New in 1.4. 228 * 229 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 230 */ 231svn_error_t * 232svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p, 233 void *baton, 234 const char *realm, 235 svn_boolean_t may_save, 236 apr_pool_t *pool); 237 238 239/** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that 240 * asks the user if they trust a specific ssl server via the command line. 241 * 242 * @since New in 1.4. 243 * 244 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 245 */ 246svn_error_t * 247svn_cmdline_auth_ssl_server_trust_prompt( 248 svn_auth_cred_ssl_server_trust_t **cred_p, 249 void *baton, 250 const char *realm, 251 apr_uint32_t failures, 252 const svn_auth_ssl_server_cert_info_t *cert_info, 253 svn_boolean_t may_save, 254 apr_pool_t *pool); 255 256 257/** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that 258 * prompts the user for the filename of their SSL client certificate via 259 * the command line. 260 * 261 * Records absolute path of the SSL client certificate file. 262 * 263 * @since New in 1.4. 264 * 265 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 266 */ 267svn_error_t * 268svn_cmdline_auth_ssl_client_cert_prompt( 269 svn_auth_cred_ssl_client_cert_t **cred_p, 270 void *baton, 271 const char *realm, 272 svn_boolean_t may_save, 273 apr_pool_t *pool); 274 275 276/** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that 277 * prompts the user for their SSL certificate password via the command line. 278 * 279 * @since New in 1.4. 280 * 281 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 282 */ 283svn_error_t * 284svn_cmdline_auth_ssl_client_cert_pw_prompt( 285 svn_auth_cred_ssl_client_cert_pw_t **cred_p, 286 void *baton, 287 const char *realm, 288 svn_boolean_t may_save, 289 apr_pool_t *pool); 290 291/** An implementation of @c svn_auth_plaintext_prompt_func_t that 292 * prompts the user whether storing unencrypted passwords to disk is OK. 293 * 294 * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton. 295 * 296 * @since New in 1.6. 297 */ 298svn_error_t * 299svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext, 300 const char *realmstring, 301 void *baton, 302 apr_pool_t *pool); 303 304/** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that 305 * prompts the user whether storing unencrypted passphrase to disk is OK. 306 * 307 * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton. 308 * 309 * @since New in 1.6. 310 */ 311svn_error_t * 312svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext, 313 const char *realmstring, 314 void *baton, 315 apr_pool_t *pool); 316 317 318/** Set @a *ab to an authentication baton allocated from @a pool and 319 * initialized with the standard set of authentication providers used 320 * by the command line client. 321 * 322 * @a non_interactive, @a username, @a password, @a config_dir, 323 * and @a no_auth_cache are the values of the command line options 324 * of the corresponding names. 325 * 326 * If @a non_interactive is @c TRUE, then the following parameters 327 * control whether an invalid SSL certificate will be accepted 328 * regardless of a specific verification failure: 329 * 330 * @a trust_server_cert_unknown_ca: If @c TRUE, accept certificates 331 * from unknown certificate authorities. 332 * 333 * @a trust_server_cert_cn_mismatch: If @c TRUE, accept certificates 334 * even if the Common Name attribute of the certificate differs from 335 * the hostname of the server. 336 * 337 * @a trust_server_cert_expired: If @c TRUE, accept certificates even 338 * if they are expired. 339 * 340 * @a trust_server_cert_not_yet_valid: If @c TRUE, accept certificates 341 * from the future. 342 * 343 * @a trust_server_cert_other_failure: If @c TRUE, accept certificates 344 * even if any other verification failure than the above occured. 345 * 346 * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and 347 * @a cancel_func and @a cancel_baton control the cancellation of the 348 * prompting providers that are initialized. 349 * 350 * Use @a pool for all allocations. 351 * 352 * @since New in 1.9. 353 */ 354svn_error_t * 355svn_cmdline_create_auth_baton2(svn_auth_baton_t **ab, 356 svn_boolean_t non_interactive, 357 const char *username, 358 const char *password, 359 const char *config_dir, 360 svn_boolean_t no_auth_cache, 361 svn_boolean_t trust_server_cert_unknown_ca, 362 svn_boolean_t trust_server_cert_cn_mismatch, 363 svn_boolean_t trust_server_cert_expired, 364 svn_boolean_t trust_server_cert_not_yet_valid, 365 svn_boolean_t trust_server_cert_other_failure, 366 svn_config_t *cfg, 367 svn_cancel_func_t cancel_func, 368 void *cancel_baton, 369 apr_pool_t *pool); 370 371/* Like svn_cmdline_create_auth_baton2, but with only one trust_server_cert 372 * option which corresponds to trust_server_cert_unknown_ca. 373 * 374 * @deprecated Provided for backward compatibility with the 1.8 API. 375 * @since New in 1.6. 376 */ 377SVN_DEPRECATED 378svn_error_t * 379svn_cmdline_create_auth_baton(svn_auth_baton_t **ab, 380 svn_boolean_t non_interactive, 381 const char *username, 382 const char *password, 383 const char *config_dir, 384 svn_boolean_t no_auth_cache, 385 svn_boolean_t trust_server_cert, 386 svn_config_t *cfg, 387 svn_cancel_func_t cancel_func, 388 void *cancel_baton, 389 apr_pool_t *pool); 390 391/** Similar to svn_cmdline_create_auth_baton(), but with 392 * @a trust_server_cert always set to false. 393 * 394 * @since New in 1.4. 395 * @deprecated Provided for backward compatibility with the 1.5 API. 396 * Use svn_cmdline_create_auth_baton() instead. 397 * 398 * @note This deprecation does not follow the usual pattern of putting 399 * a new number on end of the function's name. Instead, the new 400 * function name is distinguished from the old by a grammatical 401 * improvement: the verb "create" instead of the noun "setup". 402 */ 403SVN_DEPRECATED 404svn_error_t * 405svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab, 406 svn_boolean_t non_interactive, 407 const char *username, 408 const char *password, 409 const char *config_dir, 410 svn_boolean_t no_auth_cache, 411 svn_config_t *cfg, 412 svn_cancel_func_t cancel_func, 413 void *cancel_baton, 414 apr_pool_t *pool); 415 416#ifdef __cplusplus 417} 418#endif /* __cplusplus */ 419 420#endif /* SVN_CMDLINE_H */ 421