gpg: More check for symmetric key encryption.
[gnupg.git] / common / exechelp.h
1 /* exechelp.h - Definitions for the fork and exec helpers
2  * Copyright (C) 2004, 2009, 2010 Free Software Foundation, Inc.
3  * Copyright (C) 2004, 2006-2012, 2014-2017 g10 Code GmbH
4  *
5  * This file is part of GnuPG.
6  *
7  * This file is free software; you can redistribute it and/or modify
8  * it under the terms of either
9  *
10  *   - the GNU Lesser General Public License as published by the Free
11  *     Software Foundation; either version 3 of the License, or (at
12  *     your option) any later version.
13  *
14  * or
15  *
16  *   - the GNU General Public License as published by the Free
17  *     Software Foundation; either version 2 of the License, or (at
18  *     your option) any later version.
19  *
20  * or both in parallel, as here.
21  *
22  * This file is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25  * GNU General Public License for more details.
26  *
27  * You should have received a copy of the GNU General Public License
28  * along with this program; if not, see <https://www.gnu.org/licenses/>.
29  * SPDX-License-Identifier: (LGPL-3.0+ OR GPL-2.0+)
30  */
31
32 #ifndef GNUPG_COMMON_EXECHELP_H
33 #define GNUPG_COMMON_EXECHELP_H
34
35
36 /* Return the maximum number of currently allowed file descriptors.
37    Only useful on POSIX systems.  */
38 int get_max_fds (void);
39
40
41 /* Close all file descriptors starting with descriptor FIRST.  If
42    EXCEPT is not NULL, it is expected to be a list of file descriptors
43    which are not to close.  This list shall be sorted in ascending
44    order with its end marked by -1.  */
45 void close_all_fds (int first, int *except);
46
47
48 /* Returns an array with all currently open file descriptors.  The end
49    of the array is marked by -1.  The caller needs to release this
50    array using the *standard free* and not with xfree.  This allow the
51    use of this function right at startup even before libgcrypt has
52    been initialized.  Returns NULL on error and sets ERRNO accordingly.  */
53 int *get_all_open_fds (void);
54
55
56 /* Portable function to create a pipe.  Under Windows the write end is
57    inheritable.  If R_FP is not NULL, an estream is created for the
58    write end and stored at R_FP.  */
59 gpg_error_t gnupg_create_inbound_pipe (int filedes[2],
60                                        estream_t *r_fp, int nonblock);
61
62 /* Portable function to create a pipe.  Under Windows the read end is
63    inheritable.  If R_FP is not NULL, an estream is created for the
64    write end and stored at R_FP.  */
65 gpg_error_t gnupg_create_outbound_pipe (int filedes[2],
66                                         estream_t *r_fp, int nonblock);
67
68 /* Portable function to create a pipe.  Under Windows both ends are
69    inheritable.  */
70 gpg_error_t gnupg_create_pipe (int filedes[2]);
71
72
73 #define GNUPG_SPAWN_NONBLOCK   16
74 #define GNUPG_SPAWN_RUN_ASFW   64
75 #define GNUPG_SPAWN_DETACHED  128
76
77
78 /* Fork and exec the program PGMNAME.
79
80    If R_INFP is NULL connect stdin of the new process to /dev/null; if
81    it is not NULL store the address of a pointer to a new estream
82    there. If R_OUTFP is NULL connect stdout of the new process to
83    /dev/null; if it is not NULL store the address of a pointer to a
84    new estream there.  If R_ERRFP is NULL connect stderr of the new
85    process to /dev/null; if it is not NULL store the address of a
86    pointer to a new estream there.  On success the pid of the new
87    process is stored at PID.  On error -1 is stored at PID and if
88    R_OUTFP or R_ERRFP are not NULL, NULL is stored there.
89
90    The arguments for the process are expected in the NULL terminated
91    array ARGV.  The program name itself should not be included there.
92    If PREEXEC is not NULL, the given function will be called right
93    before the exec.
94
95    IF EXCEPT is not NULL, it is expected to be an ordered list of file
96    descriptors, terminated by an entry with the value (-1).  These
97    file descriptors won't be closed before spawning a new program.
98
99    Returns 0 on success or an error code.  Calling gnupg_wait_process
100    and gnupg_release_process is required if the function succeeded.
101
102    FLAGS is a bit vector:
103
104    GNUPG_SPAWN_NONBLOCK
105           If set the two output streams are created in non-blocking
106           mode and the input stream is switched to non-blocking mode.
107           This is merely a convenience feature because the caller
108           could do the same with gpgrt_set_nonblock.  Does not yet
109           work for Windows.
110
111    GNUPG_SPAWN_DETACHED
112           If set the process will be started as a background process.
113           This flag is only useful under W32 (but not W32CE) systems,
114           so that no new console is created and pops up a console
115           window when starting the server.  Does not work on W32CE.
116
117    GNUPG_SPAWN_RUN_ASFW
118           On W32 (but not on W32CE) run AllowSetForegroundWindow for
119           the child.  Note that due to unknown problems this actually
120           allows SetForegroundWindow for all children of this process.
121
122  */
123 gpg_error_t
124 gnupg_spawn_process (const char *pgmname, const char *argv[],
125                      int *execpt, void (*preexec)(void), unsigned int flags,
126                      estream_t *r_infp,
127                      estream_t *r_outfp,
128                      estream_t *r_errfp,
129                      pid_t *pid);
130
131
132 /* Simplified version of gnupg_spawn_process.  This function forks and
133    then execs PGMNAME, while connecting INFD to stdin, OUTFD to stdout
134    and ERRFD to stderr (any of them may be -1 to connect them to
135    /dev/null).  The arguments for the process are expected in the NULL
136    terminated array ARGV.  The program name itself should not be
137    included there.  Calling gnupg_wait_process and
138    gnupg_release_process is required.  Returns 0 on success or an
139    error code. */
140 gpg_error_t gnupg_spawn_process_fd (const char *pgmname,
141                                     const char *argv[],
142                                     int infd, int outfd, int errfd,
143                                     pid_t *pid);
144
145
146 /* If HANG is true, waits for the process identified by PID to exit;
147    if HANG is false, checks whether the process has terminated.
148    PGMNAME should be the same as supplied to the spawn function and is
149    only used for diagnostics.  Return values:
150
151    0
152        The process exited successful.  0 is stored at R_EXITCODE.
153
154    GPG_ERR_GENERAL
155        The process exited without success.  The exit code of process
156        is then stored at R_EXITCODE.  An exit code of -1 indicates
157        that the process terminated abnormally (e.g. due to a signal).
158
159    GPG_ERR_TIMEOUT
160        The process is still running (returned only if HANG is false).
161
162    GPG_ERR_INV_VALUE
163        An invalid PID has been specified.
164
165    Other error codes may be returned as well.  Unless otherwise noted,
166    -1 will be stored at R_EXITCODE.  R_EXITCODE may be passed as NULL
167    if the exit code is not required (in that case an error message will
168    be printed).  Note that under Windows PID is not the process id but
169    the handle of the process.  */
170 gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int hang,
171                                 int *r_exitcode);
172
173 /* Like gnupg_wait_process, but for COUNT processes.  */
174 gpg_error_t gnupg_wait_processes (const char **pgmnames, pid_t *pids,
175                                   size_t count, int hang, int *r_exitcodes);
176
177
178 /* Kill a process; that is send an appropriate signal to the process.
179    gnupg_wait_process must be called to actually remove the process
180    from the system.  An invalid PID is ignored.  */
181 void gnupg_kill_process (pid_t pid);
182
183 /* Release the process identified by PID.  This function is actually
184    only required for Windows but it does not harm to always call it.
185    It is a nop if PID is invalid.  */
186 void gnupg_release_process (pid_t pid);
187
188
189 /* Spawn a new process and immediately detach from it.  The name of
190    the program to exec is PGMNAME and its arguments are in ARGV (the
191    programname is automatically passed as first argument).
192    Environment strings in ENVP are set.  An error is returned if
193    pgmname is not executable; to make this work it is necessary to
194    provide an absolute file name.  */
195 gpg_error_t gnupg_spawn_process_detached (const char *pgmname,
196                                           const char *argv[],
197                                           const char *envp[] );
198
199
200
201 #endif /*GNUPG_COMMON_EXECHELP_H*/