]>
Commit | Line | Data |
---|---|---|
0f113f3e | 1 | /* |
21dcbebc | 2 | * Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. |
8f4fac7f | 3 | * |
21dcbebc RS |
4 | * Licensed under the OpenSSL license (the "License"). You may not use |
5 | * this file except in compliance with the License. You can obtain a copy | |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8f4fac7f GT |
8 | */ |
9 | ||
10 | #ifndef HEADER_DSO_H | |
0f113f3e | 11 | # define HEADER_DSO_H |
8f4fac7f | 12 | |
0f113f3e | 13 | # include <openssl/crypto.h> |
8f4fac7f GT |
14 | |
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | ||
b9e63915 | 19 | /* These values are used as commands to DSO_ctrl() */ |
0f113f3e MC |
20 | # define DSO_CTRL_GET_FLAGS 1 |
21 | # define DSO_CTRL_SET_FLAGS 2 | |
22 | # define DSO_CTRL_OR_FLAGS 3 | |
b9e63915 | 23 | |
0f113f3e MC |
24 | /* |
25 | * By default, DSO_load() will translate the provided filename into a form | |
3d8b2ec4 RS |
26 | * typical for the platform using the dso_name_converter function of the |
27 | * method. Eg. win32 will transform "blah" into "blah.dll", and dlfcn will | |
28 | * transform it into "libblah.so". This callback could even utilise the | |
29 | * DSO_METHOD's converter too if it only wants to override behaviour for | |
30 | * one or two possible DSO methods. However, the following flag can be | |
31 | * set in a DSO to prevent *any* native name-translation at all - eg. if | |
32 | * the caller has prompted the user for a path to a driver library so the | |
0f113f3e | 33 | * filename should be interpreted as-is. |
a4129c6e | 34 | */ |
0f113f3e MC |
35 | # define DSO_FLAG_NO_NAME_TRANSLATION 0x01 |
36 | /* | |
37 | * An extra flag to give if only the extension should be added as | |
38 | * translation. This is obviously only of importance on Unix and other | |
39 | * operating systems where the translation also may prefix the name with | |
40 | * something, like 'lib', and ignored everywhere else. This flag is also | |
41 | * ignored if DSO_FLAG_NO_NAME_TRANSLATION is used at the same time. | |
42 | */ | |
43 | # define DSO_FLAG_NAME_TRANSLATION_EXT_ONLY 0x02 | |
a4129c6e | 44 | |
b39eda7e MC |
45 | /* |
46 | * Don't unload the DSO when we call DSO_free() | |
47 | */ | |
48 | # define DSO_FLAG_NO_UNLOAD_ON_FREE 0x04 | |
49 | ||
0f113f3e MC |
50 | /* |
51 | * This flag loads the library with public symbols. Meaning: The exported | |
52 | * symbols of this library are public to all libraries loaded after this | |
53 | * library. At the moment only implemented in unix. | |
54 | */ | |
55 | # define DSO_FLAG_GLOBAL_SYMBOLS 0x20 | |
a4129c6e | 56 | |
0f113f3e | 57 | typedef void (*DSO_FUNC_TYPE) (void); |
e9a68cfb | 58 | |
8f4fac7f | 59 | typedef struct dso_st DSO; |
73decf59 | 60 | typedef struct dso_meth_st DSO_METHOD; |
8f4fac7f | 61 | |
0f113f3e MC |
62 | /* |
63 | * The function prototype used for method functions (or caller-provided | |
64 | * callbacks) that transform filenames. They are passed a DSO structure | |
65 | * pointer (or NULL if they are to be used independently of a DSO object) and | |
66 | * a filename to transform. They should either return NULL (if there is an | |
67 | * error condition) or a newly allocated string containing the transformed | |
68 | * form that the caller will need to free with OPENSSL_free() when done. | |
69 | */ | |
70 | typedef char *(*DSO_NAME_CONVERTER_FUNC)(DSO *, const char *); | |
71 | /* | |
72 | * The function prototype used for method functions (or caller-provided | |
73 | * callbacks) that merge two file specifications. They are passed a DSO | |
74 | * structure pointer (or NULL if they are to be used independently of a DSO | |
75 | * object) and two file specifications to merge. They should either return | |
76 | * NULL (if there is an error condition) or a newly allocated string | |
77 | * containing the result of merging that the caller will need to free with | |
78 | * OPENSSL_free() when done. Here, merging means that bits and pieces are | |
79 | * taken from each of the file specifications and added together in whatever | |
80 | * fashion that is sensible for the DSO method in question. The only rule | |
81 | * that really applies is that if the two specification contain pieces of the | |
82 | * same type, the copy from the first string takes priority. One could see | |
83 | * it as the first specification is the one given by the user and the second | |
84 | * being a bunch of defaults to add on if they're missing in the first. | |
85 | */ | |
86 | typedef char *(*DSO_MERGER_FUNC)(DSO *, const char *, const char *); | |
87 | ||
0f113f3e | 88 | DSO *DSO_new(void); |
0f113f3e MC |
89 | int DSO_free(DSO *dso); |
90 | int DSO_flags(DSO *dso); | |
91 | int DSO_up_ref(DSO *dso); | |
92 | long DSO_ctrl(DSO *dso, int cmd, long larg, void *parg); | |
93 | ||
0f113f3e MC |
94 | /* |
95 | * These functions can be used to get/set the platform-independent filename | |
96 | * used for a DSO. NB: set will fail if the DSO is already loaded. | |
97 | */ | |
51c8dc37 | 98 | const char *DSO_get_filename(DSO *dso); |
0f113f3e MC |
99 | int DSO_set_filename(DSO *dso, const char *filename); |
100 | /* | |
101 | * This function will invoke the DSO's name_converter callback to translate a | |
51c8dc37 GT |
102 | * filename, or if the callback isn't set it will instead use the DSO_METHOD's |
103 | * converter. If "filename" is NULL, the "filename" in the DSO itself will be | |
104 | * used. If the DSO_FLAG_NO_NAME_TRANSLATION flag is set, then the filename is | |
105 | * simply duplicated. NB: This function is usually called from within a | |
0f113f3e MC |
106 | * DSO_METHOD during the processing of a DSO_load() call, and is exposed so |
107 | * that caller-created DSO_METHODs can do the same thing. A non-NULL return | |
108 | * value will need to be OPENSSL_free()'d. | |
109 | */ | |
110 | char *DSO_convert_filename(DSO *dso, const char *filename); | |
111 | /* | |
112 | * This function will invoke the DSO's merger callback to merge two file | |
cbecb3ac RL |
113 | * specifications, or if the callback isn't set it will instead use the |
114 | * DSO_METHOD's merger. A non-NULL return value will need to be | |
0f113f3e MC |
115 | * OPENSSL_free()'d. |
116 | */ | |
117 | char *DSO_merge(DSO *dso, const char *filespec1, const char *filespec2); | |
8f4fac7f | 118 | |
0f113f3e MC |
119 | /* |
120 | * The all-singing all-dancing load function, you normally pass NULL for the | |
3d8b2ec4 | 121 | * first and third parameters. Use DSO_up_ref and DSO_free for subsequent |
0f113f3e MC |
122 | * reference count handling. Any flags passed in will be set in the |
123 | * constructed DSO after its init() function but before the load operation. | |
124 | * If 'dso' is non-NULL, 'flags' is ignored. | |
125 | */ | |
b9e63915 | 126 | DSO *DSO_load(DSO *dso, const char *filename, DSO_METHOD *meth, int flags); |
8f4fac7f | 127 | |
e9a68cfb GT |
128 | /* This function binds to a function inside a shared library. */ |
129 | DSO_FUNC_TYPE DSO_bind_func(DSO *dso, const char *symname); | |
8f4fac7f | 130 | |
0f113f3e MC |
131 | /* |
132 | * This method is the default, but will beg, borrow, or steal whatever method | |
133 | * should be the default on any particular platform (including | |
134 | * DSO_METH_null() if necessary). | |
135 | */ | |
8f4fac7f GT |
136 | DSO_METHOD *DSO_METHOD_openssl(void); |
137 | ||
cb6ea61c MC |
138 | /* |
139 | * This function writes null-terminated pathname of DSO module containing | |
140 | * 'addr' into 'sz' large caller-provided 'path' and returns the number of | |
141 | * characters [including trailing zero] written to it. If 'sz' is 0 or | |
142 | * negative, 'path' is ignored and required amount of charachers [including | |
143 | * trailing zero] to accommodate pathname is returned. If 'addr' is NULL, then | |
144 | * pathname of cryptolib itself is returned. Negative or zero return value | |
145 | * denotes error. | |
146 | */ | |
147 | int DSO_pathbyaddr(void *addr, char *path, int sz); | |
148 | ||
b39eda7e MC |
149 | /* |
150 | * Like DSO_pathbyaddr() but instead returns a handle to the DSO for the symbol | |
151 | * or NULL on error. | |
152 | */ | |
153 | DSO *DSO_dsobyaddr(void *addr, int flags); | |
154 | ||
0f113f3e MC |
155 | /* |
156 | * This function should be used with caution! It looks up symbols in *all* | |
157 | * loaded modules and if module gets unloaded by somebody else attempt to | |
158 | * dereference the pointer is doomed to have fatal consequences. Primary | |
159 | * usage for this function is to probe *core* system functionality, e.g. | |
160 | * check if getnameinfo(3) is available at run-time without bothering about | |
161 | * OS-specific details such as libc.so.versioning or where does it actually | |
162 | * reside: in libc itself or libsocket. | |
7ed87653 | 163 | */ |
c6cb42e4 AP |
164 | void *DSO_global_lookup(const char *name); |
165 | ||
8f4fac7f | 166 | /* BEGIN ERROR CODES */ |
0f113f3e MC |
167 | /* |
168 | * The following lines are auto generated by the script mkerr.pl. Any changes | |
8f4fac7f GT |
169 | * made after this point may be overwritten when the script is next run. |
170 | */ | |
0cd0a820 | 171 | |
69588edb | 172 | int ERR_load_DSO_strings(void); |
8f4fac7f GT |
173 | |
174 | /* Error codes for the DSO functions. */ | |
175 | ||
176 | /* Function codes. */ | |
0f113f3e | 177 | # define DSO_F_DLFCN_BIND_FUNC 100 |
0f113f3e MC |
178 | # define DSO_F_DLFCN_LOAD 102 |
179 | # define DSO_F_DLFCN_MERGER 130 | |
180 | # define DSO_F_DLFCN_NAME_CONVERTER 123 | |
181 | # define DSO_F_DLFCN_UNLOAD 103 | |
182 | # define DSO_F_DL_BIND_FUNC 104 | |
0f113f3e MC |
183 | # define DSO_F_DL_LOAD 106 |
184 | # define DSO_F_DL_MERGER 131 | |
185 | # define DSO_F_DL_NAME_CONVERTER 124 | |
186 | # define DSO_F_DL_UNLOAD 107 | |
187 | # define DSO_F_DSO_BIND_FUNC 108 | |
0f113f3e MC |
188 | # define DSO_F_DSO_CONVERT_FILENAME 126 |
189 | # define DSO_F_DSO_CTRL 110 | |
190 | # define DSO_F_DSO_FREE 111 | |
191 | # define DSO_F_DSO_GET_FILENAME 127 | |
0f113f3e MC |
192 | # define DSO_F_DSO_GLOBAL_LOOKUP 139 |
193 | # define DSO_F_DSO_LOAD 112 | |
194 | # define DSO_F_DSO_MERGE 132 | |
195 | # define DSO_F_DSO_NEW_METHOD 113 | |
cb6ea61c | 196 | # define DSO_F_DSO_PATHBYADDR 105 |
0f113f3e | 197 | # define DSO_F_DSO_SET_FILENAME 129 |
0f113f3e | 198 | # define DSO_F_DSO_UP_REF 114 |
0f113f3e MC |
199 | # define DSO_F_VMS_BIND_SYM 115 |
200 | # define DSO_F_VMS_LOAD 116 | |
201 | # define DSO_F_VMS_MERGER 133 | |
202 | # define DSO_F_VMS_UNLOAD 117 | |
0cd0a820 | 203 | # define DSO_F_WIN32_BIND_FUNC 101 |
0f113f3e | 204 | # define DSO_F_WIN32_GLOBALLOOKUP 142 |
0f113f3e MC |
205 | # define DSO_F_WIN32_JOINER 135 |
206 | # define DSO_F_WIN32_LOAD 120 | |
207 | # define DSO_F_WIN32_MERGER 134 | |
208 | # define DSO_F_WIN32_NAME_CONVERTER 125 | |
cb6ea61c | 209 | # define DSO_F_WIN32_PATHBYADDR 109 |
0f113f3e MC |
210 | # define DSO_F_WIN32_SPLITTER 136 |
211 | # define DSO_F_WIN32_UNLOAD 121 | |
8f4fac7f GT |
212 | |
213 | /* Reason codes. */ | |
0f113f3e MC |
214 | # define DSO_R_CTRL_FAILED 100 |
215 | # define DSO_R_DSO_ALREADY_LOADED 110 | |
216 | # define DSO_R_EMPTY_FILE_STRUCTURE 113 | |
217 | # define DSO_R_FAILURE 114 | |
218 | # define DSO_R_FILENAME_TOO_BIG 101 | |
219 | # define DSO_R_FINISH_FAILED 102 | |
220 | # define DSO_R_INCORRECT_FILE_SYNTAX 115 | |
221 | # define DSO_R_LOAD_FAILED 103 | |
222 | # define DSO_R_NAME_TRANSLATION_FAILED 109 | |
223 | # define DSO_R_NO_FILENAME 111 | |
0f113f3e MC |
224 | # define DSO_R_NULL_HANDLE 104 |
225 | # define DSO_R_SET_FILENAME_FAILED 112 | |
226 | # define DSO_R_STACK_ERROR 105 | |
227 | # define DSO_R_SYM_FAILURE 106 | |
228 | # define DSO_R_UNLOAD_FAILED 107 | |
229 | # define DSO_R_UNSUPPORTED 108 | |
8f4fac7f | 230 | |
0cd0a820 | 231 | # ifdef __cplusplus |
8f4fac7f | 232 | } |
0cd0a820 | 233 | # endif |
8f4fac7f | 234 | #endif |