]>
Commit | Line | Data |
---|---|---|
2186cd8e UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
38e33cef | 5 | RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures |
2186cd8e UM |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/rsa.h> | |
10 | ||
fd38fecc DSH |
11 | int RSA_get_ex_new_index(long argl, void *argp, |
12 | CRYPTO_EX_new *new_func, | |
13 | CRYPTO_EX_dup *dup_func, | |
14 | CRYPTO_EX_free *free_func); | |
15 | ||
38e33cef | 16 | int RSA_set_ex_data(RSA *r, int idx, void *arg); |
fd38fecc DSH |
17 | |
18 | void *RSA_get_ex_data(RSA *r, int idx); | |
19 | ||
da736b31 NL |
20 | typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, |
21 | int idx, long argl, void *argp); | |
22 | typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, | |
23 | int idx, long argl, void *argp); | |
24 | typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, | |
25 | int idx, long argl, void *argp); | |
2186cd8e | 26 | |
2186cd8e UM |
27 | =head1 DESCRIPTION |
28 | ||
fd38fecc DSH |
29 | Several OpenSSL structures can have application specific data attached to them. |
30 | This has several potential uses, it can be used to cache data associated with | |
31 | a structure (for example the hash of some part of the structure) or some | |
32 | additional data (for example a handle to the data in an external library). | |
33 | ||
34 | Since the application data can be anything at all it is passed and retrieved | |
35 | as a B<void *> type. | |
36 | ||
37 | The B<RSA_get_ex_new_index()> function is initially called to "register" some | |
38 | new application specific data. It takes three optional function pointers which | |
39 | are called when the parent structure (in this case an RSA structure) is | |
40 | initially created, when it is copied and when it is freed up. If any or all of | |
41 | these function pointer arguments are not used they should be set to NULL. The | |
e93f9a32 | 42 | precise manner in which these function pointers are called is described in more |
fd38fecc DSH |
43 | detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer |
44 | parameters which will be passed to the supplied functions but which otherwise | |
45 | have no special meaning. It returns an B<index> which should be stored | |
46 | (typically in a static variable) and passed used in the B<idx> parameter in | |
47 | the remaining functions. Each successful call to B<RSA_get_ex_new_index()> | |
48 | will return an index greater than any previously returned, this is important | |
49 | because the optional functions are called in order of increasing index value. | |
50 | ||
51 | B<RSA_set_ex_data()> is used to set application specific data, the data is | |
52 | supplied in the B<arg> parameter and its precise meaning is up to the | |
53 | application. | |
54 | ||
55 | B<RSA_get_ex_data()> is used to retrieve application specific data. The data | |
56 | is returned to the application, this will be the same value as supplied to | |
57 | a previous B<RSA_set_ex_data()> call. | |
58 | ||
59 | B<new_func()> is called when a structure is initially allocated (for example | |
60 | with B<RSA_new()>. The parent structure members will not have any meaningful | |
61 | values at this point. This function will typically be used to allocate any | |
62 | application specific structure. | |
63 | ||
64 | B<free_func()> is called when a structure is being freed up. The dynamic parent | |
65 | structure members should not be accessed because they will be freed up when | |
66 | this function is called. | |
67 | ||
68 | B<new_func()> and B<free_func()> take the same parameters. B<parent> is a | |
69 | pointer to the parent RSA structure. B<ptr> is a the application specific data | |
70 | (this wont be of much use in B<new_func()>. B<ad> is a pointer to the | |
71 | B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions | |
15701211 | 72 | B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate |
fd38fecc DSH |
73 | it. The B<idx> parameter is the index: this will be the same value returned by |
74 | B<RSA_get_ex_new_index()> when the functions were initially registered. Finally | |
75 | the B<argl> and B<argp> parameters are the values originally passed to the same | |
76 | corresponding parameters when B<RSA_get_ex_new_index()> was called. | |
77 | ||
78 | B<dup_func()> is called when a structure is being copied. Pointers to the | |
79 | destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and | |
80 | B<from> parameters respectively. The B<from_d> parameter is passed a pointer to | |
81 | the source application data when the function is called, when the function returns | |
82 | the value is copied to the destination: the application can thus modify the data | |
83 | pointed to by B<from_d> and have different values in the source and destination. | |
84 | The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> | |
85 | and B<free_func()>. | |
2186cd8e UM |
86 | |
87 | =head1 RETURN VALUES | |
88 | ||
fd38fecc DSH |
89 | B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid |
90 | index value). | |
91 | ||
92 | B<RSA_set_ex_data()> returns 1 on success or 0 on failure. | |
93 | ||
94 | B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also | |
95 | be valid application data but currently it can only fail if given an invalid B<idx> | |
96 | parameter. | |
97 | ||
98 | B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. | |
99 | ||
9b86974e | 100 | On failure an error code can be obtained from L<ERR_get_error(3)>. |
fd38fecc DSH |
101 | |
102 | =head1 BUGS | |
103 | ||
104 | B<dup_func()> is currently never called. | |
105 | ||
106 | The return value of B<new_func()> is ignored. | |
107 | ||
108 | The B<new_func()> function isn't very useful because no meaningful values are | |
109 | present in the parent RSA structure when it is called. | |
2186cd8e UM |
110 | |
111 | =head1 SEE ALSO | |
112 | ||
9b86974e | 113 | L<rsa(3)>, L<CRYPTO_set_ex_data(3)> |
2186cd8e UM |
114 | |
115 | =head1 HISTORY | |
116 | ||
38e33cef | 117 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are |
e93f9a32 | 118 | available since SSLeay 0.9.0. |
2186cd8e UM |
119 | |
120 | =cut |