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