/src/openssl/include/internal/dso.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
3 | | * |
4 | | * Licensed under the Apache License 2.0 (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 |
8 | | */ |
9 | | |
10 | | #ifndef OSSL_INTERNAL_DSO_H |
11 | | # define OSSL_INTERNAL_DSO_H |
12 | | |
13 | | # include <openssl/crypto.h> |
14 | | # include "internal/dsoerr.h" |
15 | | |
16 | | /* These values are used as commands to DSO_ctrl() */ |
17 | 0 | # define DSO_CTRL_GET_FLAGS 1 |
18 | 0 | # define DSO_CTRL_SET_FLAGS 2 |
19 | 0 | # define DSO_CTRL_OR_FLAGS 3 |
20 | | |
21 | | /* |
22 | | * By default, DSO_load() will translate the provided filename into a form |
23 | | * typical for the platform using the dso_name_converter function of the |
24 | | * method. Eg. win32 will transform "blah" into "blah.dll", and dlfcn will |
25 | | * transform it into "libblah.so". This callback could even utilise the |
26 | | * DSO_METHOD's converter too if it only wants to override behaviour for |
27 | | * one or two possible DSO methods. However, the following flag can be |
28 | | * set in a DSO to prevent *any* native name-translation at all - eg. if |
29 | | * the caller has prompted the user for a path to a driver library so the |
30 | | * filename should be interpreted as-is. |
31 | | */ |
32 | 0 | # define DSO_FLAG_NO_NAME_TRANSLATION 0x01 |
33 | | /* |
34 | | * An extra flag to give if only the extension should be added as |
35 | | * translation. This is obviously only of importance on Unix and other |
36 | | * operating systems where the translation also may prefix the name with |
37 | | * something, like 'lib', and ignored everywhere else. This flag is also |
38 | | * ignored if DSO_FLAG_NO_NAME_TRANSLATION is used at the same time. |
39 | | */ |
40 | 0 | # define DSO_FLAG_NAME_TRANSLATION_EXT_ONLY 0x02 |
41 | | |
42 | | /* |
43 | | * Don't unload the DSO when we call DSO_free() |
44 | | */ |
45 | 0 | # define DSO_FLAG_NO_UNLOAD_ON_FREE 0x04 |
46 | | |
47 | | /* |
48 | | * This flag loads the library with public symbols. Meaning: The exported |
49 | | * symbols of this library are public to all libraries loaded after this |
50 | | * library. At the moment only implemented in unix. |
51 | | */ |
52 | 0 | # define DSO_FLAG_GLOBAL_SYMBOLS 0x20 |
53 | | |
54 | | typedef void (*DSO_FUNC_TYPE) (void); |
55 | | |
56 | | typedef struct dso_st DSO; |
57 | | typedef struct dso_meth_st DSO_METHOD; |
58 | | |
59 | | /* |
60 | | * The function prototype used for method functions (or caller-provided |
61 | | * callbacks) that transform filenames. They are passed a DSO structure |
62 | | * pointer (or NULL if they are to be used independently of a DSO object) and |
63 | | * a filename to transform. They should either return NULL (if there is an |
64 | | * error condition) or a newly allocated string containing the transformed |
65 | | * form that the caller will need to free with OPENSSL_free() when done. |
66 | | */ |
67 | | typedef char *(*DSO_NAME_CONVERTER_FUNC)(DSO *, const char *); |
68 | | /* |
69 | | * The function prototype used for method functions (or caller-provided |
70 | | * callbacks) that merge two file specifications. They are passed a DSO |
71 | | * structure pointer (or NULL if they are to be used independently of a DSO |
72 | | * object) and two file specifications to merge. They should either return |
73 | | * NULL (if there is an error condition) or a newly allocated string |
74 | | * containing the result of merging that the caller will need to free with |
75 | | * OPENSSL_free() when done. Here, merging means that bits and pieces are |
76 | | * taken from each of the file specifications and added together in whatever |
77 | | * fashion that is sensible for the DSO method in question. The only rule |
78 | | * that really applies is that if the two specification contain pieces of the |
79 | | * same type, the copy from the first string takes priority. One could see |
80 | | * it as the first specification is the one given by the user and the second |
81 | | * being a bunch of defaults to add on if they're missing in the first. |
82 | | */ |
83 | | typedef char *(*DSO_MERGER_FUNC)(DSO *, const char *, const char *); |
84 | | |
85 | | DSO *DSO_new(void); |
86 | | int DSO_free(DSO *dso); |
87 | | int DSO_flags(DSO *dso); |
88 | | int DSO_up_ref(DSO *dso); |
89 | | long DSO_ctrl(DSO *dso, int cmd, long larg, void *parg); |
90 | | |
91 | | /* |
92 | | * These functions can be used to get/set the platform-independent filename |
93 | | * used for a DSO. NB: set will fail if the DSO is already loaded. |
94 | | */ |
95 | | const char *DSO_get_filename(DSO *dso); |
96 | | int DSO_set_filename(DSO *dso, const char *filename); |
97 | | /* |
98 | | * This function will invoke the DSO's name_converter callback to translate a |
99 | | * filename, or if the callback isn't set it will instead use the DSO_METHOD's |
100 | | * converter. If "filename" is NULL, the "filename" in the DSO itself will be |
101 | | * used. If the DSO_FLAG_NO_NAME_TRANSLATION flag is set, then the filename is |
102 | | * simply duplicated. NB: This function is usually called from within a |
103 | | * DSO_METHOD during the processing of a DSO_load() call, and is exposed so |
104 | | * that caller-created DSO_METHODs can do the same thing. A non-NULL return |
105 | | * value will need to be OPENSSL_free()'d. |
106 | | */ |
107 | | char *DSO_convert_filename(DSO *dso, const char *filename); |
108 | | /* |
109 | | * This function will invoke the DSO's merger callback to merge two file |
110 | | * specifications, or if the callback isn't set it will instead use the |
111 | | * DSO_METHOD's merger. A non-NULL return value will need to be |
112 | | * OPENSSL_free()'d. |
113 | | */ |
114 | | char *DSO_merge(DSO *dso, const char *filespec1, const char *filespec2); |
115 | | |
116 | | /* |
117 | | * The all-singing all-dancing load function, you normally pass NULL for the |
118 | | * first and third parameters. Use DSO_up_ref and DSO_free for subsequent |
119 | | * reference count handling. Any flags passed in will be set in the |
120 | | * constructed DSO after its init() function but before the load operation. |
121 | | * If 'dso' is non-NULL, 'flags' is ignored. |
122 | | */ |
123 | | DSO *DSO_load(DSO *dso, const char *filename, DSO_METHOD *meth, int flags); |
124 | | |
125 | | /* This function binds to a function inside a shared library. */ |
126 | | DSO_FUNC_TYPE DSO_bind_func(DSO *dso, const char *symname); |
127 | | |
128 | | /* |
129 | | * This method is the default, but will beg, borrow, or steal whatever method |
130 | | * should be the default on any particular platform (including |
131 | | * DSO_METH_null() if necessary). |
132 | | */ |
133 | | DSO_METHOD *DSO_METHOD_openssl(void); |
134 | | |
135 | | /* |
136 | | * This function writes null-terminated pathname of DSO module containing |
137 | | * 'addr' into 'sz' large caller-provided 'path' and returns the number of |
138 | | * characters [including trailing zero] written to it. If 'sz' is 0 or |
139 | | * negative, 'path' is ignored and required amount of characters [including |
140 | | * trailing zero] to accommodate pathname is returned. If 'addr' is NULL, then |
141 | | * pathname of cryptolib itself is returned. Negative or zero return value |
142 | | * denotes error. |
143 | | */ |
144 | | int DSO_pathbyaddr(void *addr, char *path, int sz); |
145 | | |
146 | | /* |
147 | | * Like DSO_pathbyaddr() but instead returns a handle to the DSO for the symbol |
148 | | * or NULL on error. |
149 | | */ |
150 | | DSO *DSO_dsobyaddr(void *addr, int flags); |
151 | | |
152 | | /* |
153 | | * This function should be used with caution! It looks up symbols in *all* |
154 | | * loaded modules and if module gets unloaded by somebody else attempt to |
155 | | * dereference the pointer is doomed to have fatal consequences. Primary |
156 | | * usage for this function is to probe *core* system functionality, e.g. |
157 | | * check if getnameinfo(3) is available at run-time without bothering about |
158 | | * OS-specific details such as libc.so.versioning or where does it actually |
159 | | * reside: in libc itself or libsocket. |
160 | | */ |
161 | | void *DSO_global_lookup(const char *name); |
162 | | |
163 | | int ERR_load_DSO_strings(void); |
164 | | |
165 | | #endif |