diff options
Diffstat (limited to 'src/lib/libcrypto/man')
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_add.3 | 143 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_ctrl.3 | 428 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_get_default_RSA.3 | 133 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_init.3 | 122 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_register_RSA.3 | 115 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_register_all_RSA.3 | 73 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_set_default.3 | 156 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/ENGINE_unregister_RSA.3 | 96 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/Makefile | 10 | ||||
| -rw-r--r-- | src/lib/libcrypto/man/engine.3 | 557 |
10 files changed, 1303 insertions, 530 deletions
diff --git a/src/lib/libcrypto/man/ENGINE_add.3 b/src/lib/libcrypto/man/ENGINE_add.3 new file mode 100644 index 0000000000..faecb8a2ab --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_add.3 | |||
| @@ -0,0 +1,143 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_add.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: OpenSSL 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 3 | .\" | ||
| 4 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 5 | .\" | ||
| 6 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 7 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 8 | .\" copyright notice and this permission notice appear in all copies. | ||
| 9 | .\" | ||
| 10 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 11 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 12 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 13 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 14 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 15 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 16 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 17 | .\" | ||
| 18 | .Dd $Mdocdate: April 15 2018 $ | ||
| 19 | .Dt ENGINE_ADD 3 | ||
| 20 | .Os | ||
| 21 | .Sh NAME | ||
| 22 | .Nm ENGINE_add , | ||
| 23 | .Nm ENGINE_remove , | ||
| 24 | .Nm ENGINE_get_first , | ||
| 25 | .Nm ENGINE_get_last , | ||
| 26 | .Nm ENGINE_get_next , | ||
| 27 | .Nm ENGINE_get_prev , | ||
| 28 | .Nm ENGINE_by_id | ||
| 29 | .Nd maintain a global list of ENGINE objects | ||
| 30 | .Sh SYNOPSIS | ||
| 31 | .In openssl/engine.h | ||
| 32 | .Ft int | ||
| 33 | .Fo ENGINE_add | ||
| 34 | .Fa "ENGINE *e" | ||
| 35 | .Fc | ||
| 36 | .Ft int | ||
| 37 | .Fo ENGINE_remove | ||
| 38 | .Fa "ENGINE *e" | ||
| 39 | .Fc | ||
| 40 | .Ft ENGINE * | ||
| 41 | .Fn ENGINE_get_first void | ||
| 42 | .Ft ENGINE * | ||
| 43 | .Fn ENGINE_get_last void | ||
| 44 | .Ft ENGINE * | ||
| 45 | .Fo ENGINE_get_next | ||
| 46 | .Fa "ENGINE *e" | ||
| 47 | .Fc | ||
| 48 | .Ft ENGINE * | ||
| 49 | .Fo ENGINE_get_prev | ||
| 50 | .Fa "ENGINE *e" | ||
| 51 | .Fc | ||
| 52 | .Ft ENGINE * | ||
| 53 | .Fo ENGINE_by_id | ||
| 54 | .Fa "const char *id" | ||
| 55 | .Fc | ||
| 56 | .Sh DESCRIPTION | ||
| 57 | The crypto library maintains a global list of | ||
| 58 | .Vt ENGINE | ||
| 59 | objects. | ||
| 60 | .Pp | ||
| 61 | .Fn ENGINE_add | ||
| 62 | appends | ||
| 63 | .Fa e | ||
| 64 | to the end of the list | ||
| 65 | and increments its structural reference count by 1. | ||
| 66 | The name and identifier of | ||
| 67 | .Fa e | ||
| 68 | have to be set with | ||
| 69 | .Xr ENGINE_set_name 3 | ||
| 70 | and | ||
| 71 | .Xr ENGINE_set_id 3 | ||
| 72 | before calling this function. | ||
| 73 | .Fn ENGINE_add | ||
| 74 | fails if the list already contains an | ||
| 75 | .Vt ENGINE | ||
| 76 | with the same identifier. | ||
| 77 | .Pp | ||
| 78 | .Fn ENGINE_remove | ||
| 79 | removes | ||
| 80 | .Fa e | ||
| 81 | from the list. | ||
| 82 | If successful, it calls | ||
| 83 | .Xr ENGINE_free 3 | ||
| 84 | on | ||
| 85 | .Fa e . | ||
| 86 | .Pp | ||
| 87 | .Fn ENGINE_get_first | ||
| 88 | and | ||
| 89 | .Fn ENGINE_get_last | ||
| 90 | provide access to the first and last | ||
| 91 | .Vt ENGINE | ||
| 92 | object on the list, respectively. | ||
| 93 | Unless the list is empty, they increment the structural reference | ||
| 94 | count of the retrieved object by 1. | ||
| 95 | .Pp | ||
| 96 | .Fn ENGINE_get_next | ||
| 97 | and | ||
| 98 | .Fn ENGINE_get_prev | ||
| 99 | support iteration of the list. | ||
| 100 | They always call | ||
| 101 | .Xr ENGINE_free 3 | ||
| 102 | on | ||
| 103 | .Fa e . | ||
| 104 | Unless the end of the list is reached, they increment the structural | ||
| 105 | reference count of the retrieved object by 1. | ||
| 106 | .Pp | ||
| 107 | .Fn ENGINE_by_id | ||
| 108 | searches the list for an | ||
| 109 | .Vt ENGINE | ||
| 110 | object with a matching | ||
| 111 | .Fa id . | ||
| 112 | If found, it increments the structural reference count of the | ||
| 113 | retrieved object by 1. | ||
| 114 | .Sh RETURN VALUES | ||
| 115 | .Fn ENGINE_add | ||
| 116 | and | ||
| 117 | .Fn ENGINE_remove | ||
| 118 | return 1 on success or 0 on error. | ||
| 119 | .Pp | ||
| 120 | .Fn ENGINE_get_first | ||
| 121 | and | ||
| 122 | .Fn ENGINE_get_last | ||
| 123 | return an | ||
| 124 | .Vt ENGINE | ||
| 125 | object or | ||
| 126 | .Dv NULL | ||
| 127 | if the list is empty. | ||
| 128 | .Pp | ||
| 129 | .Fn ENGINE_get_next | ||
| 130 | and | ||
| 131 | .Fn ENGINE_get_prev | ||
| 132 | return an | ||
| 133 | .Vt ENGINE | ||
| 134 | object or | ||
| 135 | .Dv NULL | ||
| 136 | when the end of the list is reached. | ||
| 137 | .Pp | ||
| 138 | .Fn ENGINE_by_id | ||
| 139 | returns an | ||
| 140 | .Vt ENGINE | ||
| 141 | object or | ||
| 142 | .Dv NULL | ||
| 143 | if no matching object is found. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_ctrl.3 b/src/lib/libcrypto/man/ENGINE_ctrl.3 new file mode 100644 index 0000000000..1672f2976e --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_ctrl.3 | |||
| @@ -0,0 +1,428 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_ctrl.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE_CTRL 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_ctrl , | ||
| 24 | .Nm ENGINE_cmd_is_executable , | ||
| 25 | .Nm ENGINE_ctrl_cmd , | ||
| 26 | .Nm ENGINE_ctrl_cmd_string , | ||
| 27 | .Nm ENGINE_set_ctrl_function , | ||
| 28 | .Nm ENGINE_get_ctrl_function , | ||
| 29 | .Nm ENGINE_set_cmd_defns , | ||
| 30 | .Nm ENGINE_get_cmd_defns | ||
| 31 | .Nd control commands for ENGINE objects | ||
| 32 | .Sh SYNOPSIS | ||
| 33 | .In openssl/engine.h | ||
| 34 | .Fo ENGINE_ctrl | ||
| 35 | .Fa "ENGINE *e" | ||
| 36 | .Fa "int cmd" | ||
| 37 | .Fa "long i" | ||
| 38 | .Fa "void *p" | ||
| 39 | .Fa "void (*f)(void)" | ||
| 40 | .Fc | ||
| 41 | .Ft int | ||
| 42 | .Fo ENGINE_cmd_is_executable | ||
| 43 | .Fa "ENGINE *e" | ||
| 44 | .Fa "int cmd" | ||
| 45 | .Fc | ||
| 46 | .Ft int | ||
| 47 | .Fo ENGINE_ctrl_cmd | ||
| 48 | .Fa "ENGINE *e" | ||
| 49 | .Fa "const char *cmd_name" | ||
| 50 | .Fa "long i" | ||
| 51 | .Fa "void *p" | ||
| 52 | .Fa "void (*f)(void)" | ||
| 53 | .Fa "int cmd_optional" | ||
| 54 | .Fc | ||
| 55 | .Ft int | ||
| 56 | .Fo ENGINE_ctrl_cmd_string | ||
| 57 | .Fa "ENGINE *e" | ||
| 58 | .Fa "const char *cmd_name" | ||
| 59 | .Fa "const char *arg" | ||
| 60 | .Fa "int cmd_optional" | ||
| 61 | .Fc | ||
| 62 | .Ft typedef int | ||
| 63 | .Fo (*ENGINE_CTRL_FUNC_PTR) | ||
| 64 | .Fa "ENGINE *e" | ||
| 65 | .Fa "int cmd" | ||
| 66 | .Fa "long i" | ||
| 67 | .Fa "void *p" | ||
| 68 | .Fa "void (*f)(void)" | ||
| 69 | .Fc | ||
| 70 | .Ft int | ||
| 71 | .Fo ENGINE_set_ctrl_function | ||
| 72 | .Fa "ENGINE *e" | ||
| 73 | .Fa "ENGINE_CTRL_FUNC_PTR ctrl_f" | ||
| 74 | .Fc | ||
| 75 | .Ft ENGINE_CTRL_FUNC_PTR | ||
| 76 | .Fo ENGINE_get_ctrl_function | ||
| 77 | .Fa "const ENGINE *e" | ||
| 78 | .Fc | ||
| 79 | .Ft int | ||
| 80 | .Fo ENGINE_set_cmd_defns | ||
| 81 | .Fa "ENGINE *e" | ||
| 82 | .Fa "const ENGINE_CMD_DEFN *defns" | ||
| 83 | .Fc | ||
| 84 | .Ft const ENGINE_CMD_DEFN * | ||
| 85 | .Fo ENGINE_get_cmd_defns | ||
| 86 | .Fa "const ENGINE *e" | ||
| 87 | .Fc | ||
| 88 | .Sh DESCRIPTION | ||
| 89 | .Fn ENGINE_ctrl | ||
| 90 | calls the built-in or user-defined | ||
| 91 | .Fa cmd | ||
| 92 | for the engine | ||
| 93 | .Fa e , | ||
| 94 | passing the arguments | ||
| 95 | .Fa i | ||
| 96 | and | ||
| 97 | .Fa p . | ||
| 98 | .Pp | ||
| 99 | Most built-in commands operate on user-defined commands installed with | ||
| 100 | .Fn ENGINE_set_cmd_defns , | ||
| 101 | either using the | ||
| 102 | .Fa p | ||
| 103 | argument to indicate the user-defined command with the command name | ||
| 104 | .Fa cmd_name | ||
| 105 | or using the | ||
| 106 | .Fa i | ||
| 107 | argument to indicate the user-defined command with the command number | ||
| 108 | .Fa cmd_num . | ||
| 109 | The | ||
| 110 | .Fa cmd | ||
| 111 | arguments to call the built-in commands are as follows: | ||
| 112 | .Bl -tag -width Ds | ||
| 113 | .It Dv ENGINE_CTRL_GET_CMD_FLAGS | ||
| 114 | Return the | ||
| 115 | .Fa cmd_flags | ||
| 116 | of the user-defined command with the number | ||
| 117 | .Fa i , | ||
| 118 | or a number less than or equal to 0 if an error occurs or | ||
| 119 | the command number does not exist. | ||
| 120 | A return value of 0 indicates failure if | ||
| 121 | .Fa e | ||
| 122 | is | ||
| 123 | .Dv NULL | ||
| 124 | or has a reference count of 0, or success if | ||
| 125 | .Fa e | ||
| 126 | is valid. | ||
| 127 | .It Dv ENGINE_CTRL_GET_CMD_FROM_NAME | ||
| 128 | Return the positive command number | ||
| 129 | of the user-defined command with the name | ||
| 130 | .Fa p , | ||
| 131 | or a number less than or equal to 0 if an error occurs or no | ||
| 132 | matching name is found. | ||
| 133 | .It Dv ENGINE_CTRL_GET_DESC_FROM_CMD | ||
| 134 | Copy the description of the user-defined command with the number | ||
| 135 | .Fa i | ||
| 136 | into the buffer | ||
| 137 | .Fa p | ||
| 138 | and NUL-terminate it. | ||
| 139 | It is the reponsability of the caller to make sure that the buffer | ||
| 140 | .Fa p | ||
| 141 | is large enough, either by calling | ||
| 142 | .Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD | ||
| 143 | first or using knowledge about the array passed to | ||
| 144 | .Fn ENGINE_set_cmd_defns . | ||
| 145 | The return value is the number of bytes written | ||
| 146 | .Em including | ||
| 147 | the terminating NUL byte, or a number less than or equal to 0 | ||
| 148 | if an error occurs. | ||
| 149 | .It Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD | ||
| 150 | Return the length in bytes | ||
| 151 | .Em excluding | ||
| 152 | the terminating NUL byte | ||
| 153 | of the description of the user-defined command with the number | ||
| 154 | .Fa i , | ||
| 155 | or a number less than or equal to 0 if an error occurs. | ||
| 156 | A return value of 0 indicates failure if | ||
| 157 | .Fa e | ||
| 158 | is | ||
| 159 | .Dv NULL | ||
| 160 | or has a reference count of 0, or success if | ||
| 161 | .Fa e | ||
| 162 | is valid. | ||
| 163 | .It Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE | ||
| 164 | Return the positive command number | ||
| 165 | of the first user-defined command installed with | ||
| 166 | .Fn ENGINE_set_cmd_defns | ||
| 167 | or a number less than or equal to 0 if an error occurs or no | ||
| 168 | user-defined command has been installed. | ||
| 169 | .It Dv ENGINE_CTRL_GET_NAME_FROM_CMD | ||
| 170 | Copy the name of the user-defined command with the number | ||
| 171 | .Fa i | ||
| 172 | into the buffer | ||
| 173 | .Fa p | ||
| 174 | and NUL-terminate it. | ||
| 175 | It is the reponsability of the caller to make sure that the buffer | ||
| 176 | .Fa p | ||
| 177 | is large enough, either by calling | ||
| 178 | .Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD | ||
| 179 | first or using knowledge about the array passed to | ||
| 180 | .Fn ENGINE_set_cmd_defns . | ||
| 181 | The return value is the number of bytes written | ||
| 182 | .Em including | ||
| 183 | the terminating NUL byte, or a number less than or equal to 0 | ||
| 184 | if an error occurs. | ||
| 185 | .It Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD | ||
| 186 | Return the length in bytes | ||
| 187 | .Em excluding | ||
| 188 | the terminating NULL byte | ||
| 189 | of the name of the user-defined command with the number | ||
| 190 | .Fa i , | ||
| 191 | or a number less than or equal to 0 if an error occurs. | ||
| 192 | A return value of 0 indicates failure if | ||
| 193 | .Fa e | ||
| 194 | is | ||
| 195 | .Dv NULL | ||
| 196 | or has a reference count of 0, or success if | ||
| 197 | .Fa e | ||
| 198 | is valid. | ||
| 199 | .It Dv ENGINE_CTRL_GET_NEXT_CMD_TYPE | ||
| 200 | Return the positive command number of the next user-defined command | ||
| 201 | after the user-defined command with the number | ||
| 202 | .Fa i , | ||
| 203 | or a number less than or equal to 0 if an error occurs or if | ||
| 204 | .Fa i | ||
| 205 | is the last user-defined command. | ||
| 206 | Together with | ||
| 207 | .Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE , | ||
| 208 | this can be used to iterate the user-defined commands installed with | ||
| 209 | .Fn ENGINE_set_cmd_defns . | ||
| 210 | .It Dv ENGINE_CTRL_HAS_CTRL_FUNCTION | ||
| 211 | Return 1 if | ||
| 212 | .Fa e | ||
| 213 | has its own | ||
| 214 | .Fa ctrl_f | ||
| 215 | installed with | ||
| 216 | .Fn ENGINE_set_ctrl_function | ||
| 217 | or 0 otherwise. | ||
| 218 | .El | ||
| 219 | .Pp | ||
| 220 | .Fn ENGINE_ctrl_cmd | ||
| 221 | translates the | ||
| 222 | .Fa cmd_name | ||
| 223 | of a user-defined command to a | ||
| 224 | .Fa cmd | ||
| 225 | number and calls | ||
| 226 | .Fn ENGINE_ctrl | ||
| 227 | on it. | ||
| 228 | If | ||
| 229 | .Fa cmd_optional | ||
| 230 | is non-zero, lack of a | ||
| 231 | .Fa ctrl_f | ||
| 232 | in | ||
| 233 | .Fa e | ||
| 234 | and translation failure with | ||
| 235 | .Dv ENGINE_CTRL_GET_CMD_FROM_NAME | ||
| 236 | are considered success, and the command has no effect. | ||
| 237 | Otherwise, these problems cause | ||
| 238 | .Fn ENGINE_ctrl_cmd | ||
| 239 | to fail. | ||
| 240 | .Pp | ||
| 241 | .Fn ENGINE_ctrl_cmd_string | ||
| 242 | translates the | ||
| 243 | .Fa cmd_name | ||
| 244 | of a user-defined command to a | ||
| 245 | .Fa cmd | ||
| 246 | number. | ||
| 247 | If that command has the | ||
| 248 | .Dv ENGINE_CMD_FLAG_NO_INPUT | ||
| 249 | flag set, | ||
| 250 | .Fa arg | ||
| 251 | must be | ||
| 252 | .Dv NULL | ||
| 253 | and | ||
| 254 | .Fn ENGINE_ctrl | ||
| 255 | is called with | ||
| 256 | .Fa i | ||
| 257 | set to 0 and | ||
| 258 | .Fa p | ||
| 259 | set to | ||
| 260 | .Dv NULL . | ||
| 261 | Otherwise, | ||
| 262 | .Fa arg | ||
| 263 | must not be | ||
| 264 | .Dv NULL . | ||
| 265 | If the command accepts string input, | ||
| 266 | .Fa i | ||
| 267 | is set to 0 and | ||
| 268 | .Fa arg | ||
| 269 | is passed as the | ||
| 270 | .Fa p | ||
| 271 | argument to | ||
| 272 | .Fn ENGINE_ctrl . | ||
| 273 | Otherwise, | ||
| 274 | .Fa arg | ||
| 275 | is converted with | ||
| 276 | .Xr strtol 3 | ||
| 277 | and passed as the | ||
| 278 | .Fa i | ||
| 279 | argument to | ||
| 280 | .Fn ENGINE_ctrl , | ||
| 281 | setting | ||
| 282 | .Fa p | ||
| 283 | to | ||
| 284 | .Dv NULL . | ||
| 285 | .Pp | ||
| 286 | .Fn ENGINE_set_ctrl_function | ||
| 287 | installs | ||
| 288 | .Fa ctrl_f | ||
| 289 | as the engine-specific control function for | ||
| 290 | .Fa e . | ||
| 291 | Future calls to | ||
| 292 | .Fn ENGINE_ctrl | ||
| 293 | will call that function, passing on their arguments unchanged, if the | ||
| 294 | .Fa cmd | ||
| 295 | is not built-in to the library or if the | ||
| 296 | .Dv ENGINE_FLAGS_MANUAL_CMD_CTRL | ||
| 297 | flag is set in | ||
| 298 | .Fa e . | ||
| 299 | Let the | ||
| 300 | .Fa ctrl_f | ||
| 301 | return positive values on success or negative values on failure. | ||
| 302 | Avoid return values of 0 because they cause dangerous ambiguity. | ||
| 303 | In particular, | ||
| 304 | .Fn ENGINE_ctrl_cmd | ||
| 305 | and | ||
| 306 | .Fn ENGINE_ctrl_cmd_string | ||
| 307 | cannot be used with user-defined commands | ||
| 308 | that may return 0 on success. | ||
| 309 | .Pp | ||
| 310 | .Fn ENGINE_set_cmd_defns | ||
| 311 | install an array of command definitions in | ||
| 312 | .Fa e . | ||
| 313 | .Pp | ||
| 314 | The structure | ||
| 315 | .Vt ENGINE_CMD_DEFN | ||
| 316 | has the following fields: | ||
| 317 | .Bl -tag -width Ds | ||
| 318 | .It Fa "unsigned int cmd_num" | ||
| 319 | A positive, unique, monotonically increasing command number. | ||
| 320 | Avoid using numbers below | ||
| 321 | .Dv ENGINE_CMD_BASE . | ||
| 322 | .It Fa "const char *cmd_name" | ||
| 323 | The unique name of the command. | ||
| 324 | .It Fa "const char *cmd_desc" | ||
| 325 | A short description of the command. | ||
| 326 | .It Fa "unsigned int cmd_flags" | ||
| 327 | The bitwise OR of zero or more of the following flags: | ||
| 328 | .Bl -tag -width Ds | ||
| 329 | .It Dv ENGINE_CMD_FLAG_NUMERIC | ||
| 330 | The command uses | ||
| 331 | .Fa i . | ||
| 332 | .It Dv ENGINE_CMD_FLAG_STRING | ||
| 333 | The command uses | ||
| 334 | .Fa p . | ||
| 335 | .It Dv ENGINE_CMD_FLAG_NO_INPUT | ||
| 336 | The command neither uses | ||
| 337 | .Fa i | ||
| 338 | nor | ||
| 339 | .Fa p . | ||
| 340 | .It Dv ENGINE_CMD_FLAG_INTERNAL | ||
| 341 | This flag has no effect and is only provided for compatibility. | ||
| 342 | .El | ||
| 343 | .El | ||
| 344 | .Pp | ||
| 345 | The last element of | ||
| 346 | .Fa defns | ||
| 347 | does not specify a command, but must have a | ||
| 348 | .Fa cmd_num | ||
| 349 | of 0 and a | ||
| 350 | .Fa cmd_name | ||
| 351 | of | ||
| 352 | .Dv NULL | ||
| 353 | to indicate the end of the array. | ||
| 354 | .Sh RETURN VALUES | ||
| 355 | For | ||
| 356 | .Fn ENGINE_ctrl , | ||
| 357 | positive return values indicate success and negative return values | ||
| 358 | indicate failure. | ||
| 359 | The meaning of a zero return value depends on the particular | ||
| 360 | .Fa cmd | ||
| 361 | and may indicate both success and failure, which is pathetic. | ||
| 362 | .Pp | ||
| 363 | Regardless of the | ||
| 364 | .Fa cmd , | ||
| 365 | .Fn ENGINE_ctrl | ||
| 366 | returns 0 if | ||
| 367 | .Fa e | ||
| 368 | is | ||
| 369 | .Dv NULL | ||
| 370 | or has a reference count of 0. | ||
| 371 | This is quite unfortunate for commands like | ||
| 372 | .Dv ENGINE_CTRL_GET_CMD_FLAGS | ||
| 373 | where 0 may indicate success, so make sure | ||
| 374 | .Fa e | ||
| 375 | is valid before issuing a control command. | ||
| 376 | .Pp | ||
| 377 | For built-in commands except | ||
| 378 | .Dv ENGINE_CTRL_HAS_CTRL_FUNCTION , | ||
| 379 | .Fn ENGINE_ctrl | ||
| 380 | returns \-1 if | ||
| 381 | .Dv ENGINE_FLAGS_MANUAL_CMD_CTRL | ||
| 382 | is set but no | ||
| 383 | .Fa ctrl_f | ||
| 384 | has been installed with | ||
| 385 | .Fn ENGINE_set_ctrl_function . | ||
| 386 | .Pp | ||
| 387 | For commands that are not built in, | ||
| 388 | .Fn ENGINE_ctrl | ||
| 389 | returns 0 if no | ||
| 390 | .Fa ctrl_f | ||
| 391 | has been installed with | ||
| 392 | .Fn ENGINE_set_ctrl_function . | ||
| 393 | .Pp | ||
| 394 | .Fn ENGINE_cmd_is_executable | ||
| 395 | returns 1 if the user-defined | ||
| 396 | .Fa cmd | ||
| 397 | is executable and has at least one of the flags | ||
| 398 | .Dv ENGINE_CMD_FLAG_NUMERIC , | ||
| 399 | .Dv ENGINE_CMD_FLAG_STRING , | ||
| 400 | and | ||
| 401 | .Dv ENGINE_CMD_FLAG_NO_INPUT | ||
| 402 | set, or 0 otherwise. | ||
| 403 | .Pp | ||
| 404 | .Fn ENGINE_ctrl_cmd | ||
| 405 | and | ||
| 406 | .Fn ENGINE_ctrl_cmd_string | ||
| 407 | return 1 on success or 0 on error. | ||
| 408 | .Pp | ||
| 409 | .Fn ENGINE_set_ctrl_function | ||
| 410 | and | ||
| 411 | .Fn ENGINE_set_cmd_defns | ||
| 412 | always return 1. | ||
| 413 | .Pp | ||
| 414 | .Fn ENGINE_get_ctrl_function | ||
| 415 | returns a pointer to the function | ||
| 416 | .Fa ctrl_f | ||
| 417 | installed with | ||
| 418 | .Fn ENGINE_set_ctrl_function , | ||
| 419 | or | ||
| 420 | .Dv NULL | ||
| 421 | if none has been installed. | ||
| 422 | .Pp | ||
| 423 | .Fn ENGINE_get_cmd_defns | ||
| 424 | returns the array of command definitions installed in | ||
| 425 | .Fa e | ||
| 426 | or | ||
| 427 | .Dv NULL | ||
| 428 | if none is installed. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_get_default_RSA.3 b/src/lib/libcrypto/man/ENGINE_get_default_RSA.3 new file mode 100644 index 0000000000..876ccac775 --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_get_default_RSA.3 | |||
| @@ -0,0 +1,133 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_get_default_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE_GET_DEFAULT_RSA 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_get_default_RSA , | ||
| 24 | .Nm ENGINE_get_default_DSA , | ||
| 25 | .Nm ENGINE_get_default_ECDH , | ||
| 26 | .Nm ENGINE_get_default_ECDSA , | ||
| 27 | .Nm ENGINE_get_default_DH , | ||
| 28 | .Nm ENGINE_get_default_RAND , | ||
| 29 | .Nm ENGINE_get_cipher_engine , | ||
| 30 | .Nm ENGINE_get_digest_engine , | ||
| 31 | .Nm ENGINE_set_table_flags , | ||
| 32 | .Nm ENGINE_get_table_flags | ||
| 33 | .Nd retrieve the default ENGINE for an algorithm | ||
| 34 | .Sh SYNOPSIS | ||
| 35 | .In openssl/engine.h | ||
| 36 | .Ft ENGINE * | ||
| 37 | .Fn ENGINE_get_default_RSA void | ||
| 38 | .Ft ENGINE * | ||
| 39 | .Fn ENGINE_get_default_DSA void | ||
| 40 | .Ft ENGINE * | ||
| 41 | .Fn ENGINE_get_default_ECDH void | ||
| 42 | .Ft ENGINE * | ||
| 43 | .Fn ENGINE_get_default_ECDSA void | ||
| 44 | .Ft ENGINE * | ||
| 45 | .Fn ENGINE_get_default_DH void | ||
| 46 | .Ft ENGINE * | ||
| 47 | .Fn ENGINE_get_default_RAND void | ||
| 48 | .Ft ENGINE * | ||
| 49 | .Fo ENGINE_get_cipher_engine | ||
| 50 | .Fa "int nid" | ||
| 51 | .Fc | ||
| 52 | .Ft ENGINE * | ||
| 53 | .Fo ENGINE_get_digest_engine | ||
| 54 | .Fa "int nid" | ||
| 55 | .Fc | ||
| 56 | .Ft void | ||
| 57 | .Fo ENGINE_set_table_flags | ||
| 58 | .Fa "unsigned int flags" | ||
| 59 | .Fc | ||
| 60 | .Ft unsigned int | ||
| 61 | .Fn ENGINE_get_table_flags void | ||
| 62 | .Sh DESCRIPTION | ||
| 63 | These functions retrieve the current default | ||
| 64 | .Vt ENGINE | ||
| 65 | implementing the respective algorithm. | ||
| 66 | .Pp | ||
| 67 | If a default engine was previously selected, | ||
| 68 | .Xr ENGINE_init 3 | ||
| 69 | is called on it again and it is used. | ||
| 70 | Otherwise, these functions inspect the engines registered | ||
| 71 | with the functions documented in | ||
| 72 | .Xr ENGINE_register_RSA 3 | ||
| 73 | in the order of the table for the respective algorithm. | ||
| 74 | If an inspected engine is already successfully initialized, | ||
| 75 | .Xr ENGINE_init 3 | ||
| 76 | is called on it again and it is used as the new default. | ||
| 77 | Otherwise, unless the global flag | ||
| 78 | .Dv ENGINE_TABLE_FLAG_NOINIT | ||
| 79 | is set, | ||
| 80 | .Xr ENGINE_init 3 | ||
| 81 | is tried on it. | ||
| 82 | If it succeeds, that engine is used as the new default. | ||
| 83 | If it fails or if | ||
| 84 | .Dv ENGINE_TABLE_FLAG_NOINIT | ||
| 85 | is set, inspection continues with the next engine. | ||
| 86 | .Pp | ||
| 87 | The global flag can be set by calling | ||
| 88 | .Fn ENGINE_set_table_flags | ||
| 89 | with an argument of | ||
| 90 | .Dv ENGINE_TABLE_FLAG_NOINIT | ||
| 91 | or cleared by calling it with an argument of 0. | ||
| 92 | By default, the flag is not set. | ||
| 93 | .Pp | ||
| 94 | While all the other functions operate on exactly one algorithm, | ||
| 95 | .Fn ENGINE_get_cipher_engine | ||
| 96 | and | ||
| 97 | .Fn ENGINE_get_digest_engine | ||
| 98 | are special in so far as they can handle multiple algorithms, | ||
| 99 | identified by the given | ||
| 100 | .Fa nid . | ||
| 101 | The default engine is remembered separately for each algorithm. | ||
| 102 | .Pp | ||
| 103 | Application programs rarely need to call these functions because | ||
| 104 | they are called automatically when needed, in particular from | ||
| 105 | .Xr RSA_new 3 , | ||
| 106 | .Xr DSA_new 3 , | ||
| 107 | .Fn ECDH_set_method , | ||
| 108 | .Fn ECDH_compute_key , | ||
| 109 | .Xr ECDSA_set_method 3 , | ||
| 110 | .Xr ECDSA_do_sign_ex 3 , | ||
| 111 | .Xr ECDSA_do_verify 3 , | ||
| 112 | .Xr DH_new 3 , | ||
| 113 | .Xr EVP_CipherInit_ex 3 , | ||
| 114 | and | ||
| 115 | .Xr EVP_DigestInit_ex 3 . | ||
| 116 | .Sh RETURN VALUES | ||
| 117 | These functions return a functional reference to an | ||
| 118 | .Vt ENGINE | ||
| 119 | object or | ||
| 120 | .Dv NULL | ||
| 121 | on failure, in particular when no engine implementing the algorithm | ||
| 122 | is available, when | ||
| 123 | .Xr ENGINE_init 3 | ||
| 124 | fails for all implementations, | ||
| 125 | or when insufficient memory is available. | ||
| 126 | Even when these functions fail, the application may still be able | ||
| 127 | to use the algorithm in question because the built-in implementation | ||
| 128 | is used in that case, if one is available. | ||
| 129 | .Pp | ||
| 130 | .Fn ENGINE_get_table_flags | ||
| 131 | returns | ||
| 132 | .Dv ENGINE_TABLE_FLAG_NOINIT | ||
| 133 | if the global flag is set or 0 otherwise. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_init.3 b/src/lib/libcrypto/man/ENGINE_init.3 new file mode 100644 index 0000000000..d94c6a8b66 --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_init.3 | |||
| @@ -0,0 +1,122 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_init.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 3 | .\" | ||
| 4 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 5 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 6 | .\" copyright notice and this permission notice appear in all copies. | ||
| 7 | .\" | ||
| 8 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 9 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 10 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 11 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 12 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 13 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 14 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 15 | .\" | ||
| 16 | .Dd $Mdocdate: April 15 2018 $ | ||
| 17 | .Dt ENGINE_INIT 3 | ||
| 18 | .Os | ||
| 19 | .Sh NAME | ||
| 20 | .Nm ENGINE_init , | ||
| 21 | .Nm ENGINE_finish , | ||
| 22 | .Nm ENGINE_set_init_function , | ||
| 23 | .Nm ENGINE_set_finish_function , | ||
| 24 | .Nm ENGINE_get_init_function , | ||
| 25 | .Nm ENGINE_get_finish_function | ||
| 26 | .Nd initialize ENGINE objects | ||
| 27 | .Sh SYNOPSIS | ||
| 28 | .In openssl/engine.h | ||
| 29 | .Ft int | ||
| 30 | .Fo ENGINE_init | ||
| 31 | .Fa "ENGINE *e" | ||
| 32 | .Fc | ||
| 33 | .Ft int | ||
| 34 | .Fo ENGINE_finish | ||
| 35 | .Fa "ENGINE *e" | ||
| 36 | .Fc | ||
| 37 | .Ft typedef int | ||
| 38 | .Fo (*ENGINE_GEN_INT_FUNC_PTR) | ||
| 39 | .Fa "ENGINE *e" | ||
| 40 | .Fc | ||
| 41 | .Ft int | ||
| 42 | .Fo ENGINE_set_init_function | ||
| 43 | .Fa "ENGINE *e" | ||
| 44 | .Fa "ENGINE_GEN_INT_FUNC_PTR init_f" | ||
| 45 | .Fc | ||
| 46 | .Ft int | ||
| 47 | .Fo ENGINE_set_finish_function | ||
| 48 | .Fa "ENGINE *e" | ||
| 49 | .Fa "ENGINE_GEN_INT_FUNC_PTR finish_f" | ||
| 50 | .Fc | ||
| 51 | .Ft ENGINE_GEN_INT_FUNC_PTR | ||
| 52 | .Fo ENGINE_get_init_function | ||
| 53 | .Fa "const ENGINE *e" | ||
| 54 | .Fc | ||
| 55 | .Ft ENGINE_GEN_INT_FUNC_PTR | ||
| 56 | .Fo ENGINE_get_finish_function | ||
| 57 | .Fa "const ENGINE *e" | ||
| 58 | .Fc | ||
| 59 | .Sh DESCRIPTION | ||
| 60 | .Fn ENGINE_init | ||
| 61 | initializes | ||
| 62 | .Fa e | ||
| 63 | by calling the | ||
| 64 | .Fa init_f | ||
| 65 | previously installed with | ||
| 66 | .Fn ENGINE_set_init_function , | ||
| 67 | if any. | ||
| 68 | In case of success, it also increments both the structural | ||
| 69 | and the functional reference count by 1. | ||
| 70 | If no | ||
| 71 | .Fa init_f | ||
| 72 | was installed, | ||
| 73 | .Fn ENGINE_init | ||
| 74 | always succeeds. | ||
| 75 | Calling | ||
| 76 | .Fn ENGINE_init | ||
| 77 | again after it already succeeded always succeeds, but has no effect | ||
| 78 | except that it increments both the structural and the functional | ||
| 79 | reference count by 1. | ||
| 80 | .Pp | ||
| 81 | .Fn ENGINE_finish | ||
| 82 | decrements the functional reference count by 1. | ||
| 83 | When it reaches 0, it calls the | ||
| 84 | .Fa finish_f | ||
| 85 | previously installed with | ||
| 86 | .Fn ENGINE_set_finish_function , | ||
| 87 | if any. | ||
| 88 | If no | ||
| 89 | .Fa finish_f | ||
| 90 | was installed, | ||
| 91 | .Fn ENGINE_finish | ||
| 92 | always succeeds. | ||
| 93 | Unless | ||
| 94 | .Fa finish_f | ||
| 95 | fails, | ||
| 96 | .Fn ENGINE_finish | ||
| 97 | also calls | ||
| 98 | .Xr ENGINE_free 3 . | ||
| 99 | .Pp | ||
| 100 | .Fn ENGINE_init | ||
| 101 | is internally called by the functions documented in the | ||
| 102 | .Xr ENGINE_get_default_RSA 3 | ||
| 103 | manual page. | ||
| 104 | .Sh RETURN VALUES | ||
| 105 | .Fn ENGINE_init | ||
| 106 | and | ||
| 107 | .Fn ENGINE_finish | ||
| 108 | return 1 on success or 0 on error. | ||
| 109 | .Pp | ||
| 110 | .Fn ENGINE_set_init_function | ||
| 111 | and | ||
| 112 | .Fn ENGINE_set_finish_function | ||
| 113 | always return 1. | ||
| 114 | .Pp | ||
| 115 | .Fn ENGINE_get_init_function | ||
| 116 | and | ||
| 117 | .Fn ENGINE_get_finish_function | ||
| 118 | return a function pointer to the respective callback, or | ||
| 119 | .Dv NULL | ||
| 120 | if none is installed. | ||
| 121 | .Sh SEE ALSO | ||
| 122 | .Xr ENGINE_get_default_RSA 3 | ||
diff --git a/src/lib/libcrypto/man/ENGINE_register_RSA.3 b/src/lib/libcrypto/man/ENGINE_register_RSA.3 new file mode 100644 index 0000000000..95735e814d --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_register_RSA.3 | |||
| @@ -0,0 +1,115 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_register_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE_REGISTER_RSA 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_register_RSA , | ||
| 24 | .Nm ENGINE_register_DSA , | ||
| 25 | .Nm ENGINE_register_ECDH , | ||
| 26 | .Nm ENGINE_register_ECDSA , | ||
| 27 | .Nm ENGINE_register_DH , | ||
| 28 | .Nm ENGINE_register_RAND , | ||
| 29 | .Nm ENGINE_register_STORE , | ||
| 30 | .Nm ENGINE_register_ciphers , | ||
| 31 | .Nm ENGINE_register_digests , | ||
| 32 | .Nm ENGINE_register_complete | ||
| 33 | .Nd register an ENGINE as implementing an algorithm | ||
| 34 | .Sh SYNOPSIS | ||
| 35 | .In openssl/engine.h | ||
| 36 | .Ft int | ||
| 37 | .Fo ENGINE_register_RSA | ||
| 38 | .Fa "ENGINE *e" | ||
| 39 | .Fc | ||
| 40 | .Ft int | ||
| 41 | .Fo ENGINE_register_DSA | ||
| 42 | .Fa "ENGINE *e" | ||
| 43 | .Fc | ||
| 44 | .Ft int | ||
| 45 | .Fo ENGINE_register_ECDH | ||
| 46 | .Fa "ENGINE *e" | ||
| 47 | .Fc | ||
| 48 | .Ft int | ||
| 49 | .Fo ENGINE_register_ECDSA | ||
| 50 | .Fa "ENGINE *e" | ||
| 51 | .Fc | ||
| 52 | .Ft int | ||
| 53 | .Fo ENGINE_register_DH | ||
| 54 | .Fa "ENGINE *e" | ||
| 55 | .Fc | ||
| 56 | .Ft int | ||
| 57 | .Fo ENGINE_register_RAND | ||
| 58 | .Fa "ENGINE *e" | ||
| 59 | .Fc | ||
| 60 | .Ft int | ||
| 61 | .Fo ENGINE_register_STORE | ||
| 62 | .Fa "ENGINE *e" | ||
| 63 | .Fc | ||
| 64 | .Ft int | ||
| 65 | .Fo ENGINE_register_ciphers | ||
| 66 | .Fa "ENGINE *e" | ||
| 67 | .Fc | ||
| 68 | .Ft int | ||
| 69 | .Fo ENGINE_register_digests | ||
| 70 | .Fa "ENGINE *e" | ||
| 71 | .Fc | ||
| 72 | .Ft int | ||
| 73 | .Fo ENGINE_register_complete | ||
| 74 | .Fa "ENGINE *e" | ||
| 75 | .Fc | ||
| 76 | .Sh DESCRIPTION | ||
| 77 | In addition to the global table described in | ||
| 78 | .Xr ENGINE_add 3 , | ||
| 79 | the crypto library maintains several tables containing references to | ||
| 80 | .Vt ENGINE | ||
| 81 | objects implementing one specific cryptographic algorithm. | ||
| 82 | .Pp | ||
| 83 | The functions listed in the present manual page append | ||
| 84 | .Fa e | ||
| 85 | to the end of the table for the respective algorithm. | ||
| 86 | .Pp | ||
| 87 | If | ||
| 88 | .Fa e | ||
| 89 | does not contain a method for the requested algorithm, | ||
| 90 | these functions succeed without having any effect. | ||
| 91 | .Pp | ||
| 92 | If | ||
| 93 | .Fa e | ||
| 94 | is already registered for the given algorithm, | ||
| 95 | they move it to the end of the respective table. | ||
| 96 | .Pp | ||
| 97 | .Fn ENGINE_register_ciphers | ||
| 98 | and | ||
| 99 | .Fn ENGINE_register_digests | ||
| 100 | are special in so far as an engine may implement | ||
| 101 | more than one cipher or more than one digest. | ||
| 102 | In that case, | ||
| 103 | .Fa e | ||
| 104 | is registered for all the ciphers or digests it implements. | ||
| 105 | .Pp | ||
| 106 | .Fn ENGINE_register_complete | ||
| 107 | registers | ||
| 108 | .Fa e | ||
| 109 | for all algorithms it implements by calling all the other functions. | ||
| 110 | .Sh RETURN VALUES | ||
| 111 | These functions return 1 on success or 0 on error. | ||
| 112 | They only fail if insufficient memory is available. | ||
| 113 | .Sh BUGS | ||
| 114 | .Fn ENGINE_register_complete | ||
| 115 | ignores all errors, even memory allocation failure, and always returns 1. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_register_all_RSA.3 b/src/lib/libcrypto/man/ENGINE_register_all_RSA.3 new file mode 100644 index 0000000000..f92a12b2f9 --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_register_all_RSA.3 | |||
| @@ -0,0 +1,73 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_register_all_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE_REGISTER_ALL_RSA 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_register_all_RSA , | ||
| 24 | .Nm ENGINE_register_all_DSA , | ||
| 25 | .Nm ENGINE_register_all_ECDH , | ||
| 26 | .Nm ENGINE_register_all_ECDSA , | ||
| 27 | .Nm ENGINE_register_all_DH , | ||
| 28 | .Nm ENGINE_register_all_RAND , | ||
| 29 | .Nm ENGINE_register_all_STORE , | ||
| 30 | .Nm ENGINE_register_all_ciphers , | ||
| 31 | .Nm ENGINE_register_all_digests , | ||
| 32 | .Nm ENGINE_register_all_complete | ||
| 33 | .Nd register all engines as implementing an algorithm | ||
| 34 | .Sh SYNOPSIS | ||
| 35 | .In openssl/engine.h | ||
| 36 | .Ft void | ||
| 37 | .Fn ENGINE_register_all_RSA void | ||
| 38 | .Ft void | ||
| 39 | .Fn ENGINE_register_all_DSA void | ||
| 40 | .Ft void | ||
| 41 | .Fn ENGINE_register_all_ECDH void | ||
| 42 | .Ft void | ||
| 43 | .Fn ENGINE_register_all_ECDSA void | ||
| 44 | .Ft void | ||
| 45 | .Fn ENGINE_register_all_DH void | ||
| 46 | .Ft void | ||
| 47 | .Fn ENGINE_register_all_RAND void | ||
| 48 | .Ft void | ||
| 49 | .Fn ENGINE_register_all_STORE void | ||
| 50 | .Ft void | ||
| 51 | .Fn ENGINE_register_all_ciphers void | ||
| 52 | .Ft void | ||
| 53 | .Fn ENGINE_register_all_digests void | ||
| 54 | .Ft int | ||
| 55 | .Fn ENGINE_register_all_complete void | ||
| 56 | .Sh DESCRIPTION | ||
| 57 | These functions loop over all the | ||
| 58 | .Vt ENGINE | ||
| 59 | objects contained in the global table described in the | ||
| 60 | .Xr ENGINE_add 3 | ||
| 61 | manual page. | ||
| 62 | They register each object for the respective algorithm | ||
| 63 | by calling the corresponding function described in | ||
| 64 | .Xr ENGINE_register_RSA 3 . | ||
| 65 | .Pp | ||
| 66 | .Fn ENGINE_register_all_complete | ||
| 67 | calls | ||
| 68 | .Fn ENGINE_register_complete | ||
| 69 | in this way, except that it skips those | ||
| 70 | .Vt ENGINE | ||
| 71 | objects that have the | ||
| 72 | .Dv ENGINE_FLAGS_NO_REGISTER_ALL | ||
| 73 | flag set. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_set_default.3 b/src/lib/libcrypto/man/ENGINE_set_default.3 new file mode 100644 index 0000000000..653582b39d --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_set_default.3 | |||
| @@ -0,0 +1,156 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_set_default.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_set_default , | ||
| 24 | .Nm ENGINE_set_default_string , | ||
| 25 | .Nm ENGINE_set_default_RSA , | ||
| 26 | .Nm ENGINE_set_default_DSA , | ||
| 27 | .Nm ENGINE_set_default_ECDH , | ||
| 28 | .Nm ENGINE_set_default_ECDSA , | ||
| 29 | .Nm ENGINE_set_default_DH , | ||
| 30 | .Nm ENGINE_set_default_RAND , | ||
| 31 | .Nm ENGINE_set_default_ciphers , | ||
| 32 | .Nm ENGINE_set_default_digests | ||
| 33 | .Nd register an ENGINE as the default for an algorithm | ||
| 34 | .Sh SYNOPSIS | ||
| 35 | .Ft int | ||
| 36 | .Fo ENGINE_set_default_RSA | ||
| 37 | .Fa "ENGINE *e" | ||
| 38 | .Fc | ||
| 39 | .Ft int | ||
| 40 | .Fo ENGINE_set_default_DSA | ||
| 41 | .Fa "ENGINE *e" | ||
| 42 | .Fc | ||
| 43 | .Ft int | ||
| 44 | .Fo ENGINE_set_default_ECDH | ||
| 45 | .Fa "ENGINE *e" | ||
| 46 | .Fc | ||
| 47 | .Ft int | ||
| 48 | .Fo ENGINE_set_default_ECDSA | ||
| 49 | .Fa "ENGINE *e" | ||
| 50 | .Fc | ||
| 51 | .Ft int | ||
| 52 | .Fo ENGINE_set_default_DH | ||
| 53 | .Fa "ENGINE *e" | ||
| 54 | .Fc | ||
| 55 | .Ft int | ||
| 56 | .Fo ENGINE_set_default_RAND | ||
| 57 | .Fa "ENGINE *e" | ||
| 58 | .Fc | ||
| 59 | .Ft int | ||
| 60 | .Fo ENGINE_set_default_ciphers | ||
| 61 | .Fa "ENGINE *e" | ||
| 62 | .Fc | ||
| 63 | .Ft int | ||
| 64 | .Fo ENGINE_set_default_digests | ||
| 65 | .Fa "ENGINE *e" | ||
| 66 | .Fc | ||
| 67 | .Ft int | ||
| 68 | .Fo ENGINE_set_default | ||
| 69 | .Fa "ENGINE *e" | ||
| 70 | .Fa "unsigned int flags" | ||
| 71 | .Fc | ||
| 72 | .Ft int | ||
| 73 | .Fo ENGINE_set_default_string | ||
| 74 | .Fa "ENGINE *e" | ||
| 75 | .Fa "const char *list" | ||
| 76 | .Fc | ||
| 77 | .Sh DESCRIPTION | ||
| 78 | These functions register | ||
| 79 | .Fa e | ||
| 80 | as implementing the respective algorithm | ||
| 81 | like the functions described in the | ||
| 82 | .Xr ENGINE_register_RSA 3 | ||
| 83 | manual page do it. | ||
| 84 | In addition, they call | ||
| 85 | .Xr ENGINE_init 3 | ||
| 86 | on | ||
| 87 | .Fa e | ||
| 88 | and select | ||
| 89 | .Fa e | ||
| 90 | as the default implementation of the respective algorithm to be | ||
| 91 | returned by the functions described in | ||
| 92 | .Xr ENGINE_get_default_RSA 3 | ||
| 93 | in the future. | ||
| 94 | If another engine was previously selected | ||
| 95 | as the default implementation of the respective algorithm, | ||
| 96 | .Xr ENGINE_finish 3 | ||
| 97 | is called on that previous engine. | ||
| 98 | .Pp | ||
| 99 | If | ||
| 100 | .Fa e | ||
| 101 | implements more than one cipher or digest, | ||
| 102 | .Fn ENGINE_set_default_ciphers | ||
| 103 | and | ||
| 104 | .Fn ENGINE_set_default_digests | ||
| 105 | register and select it for all these ciphers and digests, respectively. | ||
| 106 | .Pp | ||
| 107 | .Fn ENGINE_set_default | ||
| 108 | registers | ||
| 109 | .Fa e | ||
| 110 | as the default implementation of all algorithms specified by the | ||
| 111 | .Fa flags | ||
| 112 | by calling the appropriate ones among the other functions. | ||
| 113 | Algorithms can be selected by combining any number of the | ||
| 114 | following constants with bitwise OR: | ||
| 115 | .Dv ENGINE_METHOD_ALL , | ||
| 116 | .Dv ENGINE_METHOD_RSA , | ||
| 117 | .Dv ENGINE_METHOD_DSA , | ||
| 118 | .Dv ENGINE_METHOD_ECDH , | ||
| 119 | .Dv ENGINE_METHOD_ECDSA , | ||
| 120 | .Dv ENGINE_METHOD_DH , | ||
| 121 | .Dv ENGINE_METHOD_RAND , | ||
| 122 | .Dv ENGINE_METHOD_CIPHERS , | ||
| 123 | .Dv ENGINE_METHOD_DIGESTS , | ||
| 124 | .Dv ENGINE_METHOD_PKEY_METHS , | ||
| 125 | and | ||
| 126 | .Dv ENGINE_METHOD_PKEY_ASN1_METHS . | ||
| 127 | .Pp | ||
| 128 | .Fn ENGINE_set_default_string | ||
| 129 | is similar except that it selects the algorithms according to the string | ||
| 130 | .Fa def_list , | ||
| 131 | which contains an arbitrary number of comma-separated keywords from | ||
| 132 | the following list: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, | ||
| 133 | DIGESTS, PKEY_CRYPTO, PKEY_ASN1, and PKEY. | ||
| 134 | PKEY_CRYPTO corresponds to | ||
| 135 | .Dv ENGINE_METHOD_PKEY_METHS , | ||
| 136 | PKEY_ASN1 to | ||
| 137 | .Dv ENGINE_METHOD_PKEY_ASN1_METHS , | ||
| 138 | and PKEY selects both. | ||
| 139 | .Sh RETURN VALUES | ||
| 140 | These functions return 1 on success or 0 on error. | ||
| 141 | They fail if | ||
| 142 | .Xr ENGINE_init 3 | ||
| 143 | fails or if insufficient memory is available. | ||
| 144 | .Sh CAVEATS | ||
| 145 | Failure of | ||
| 146 | .Xr ENGINE_finish 3 | ||
| 147 | is ignored. | ||
| 148 | .Sh BUGS | ||
| 149 | Even when | ||
| 150 | .Fn ENGINE_set_default | ||
| 151 | or | ||
| 152 | .Fn ENGINE_set_default_string | ||
| 153 | fail, they typically still register | ||
| 154 | .Fa e | ||
| 155 | for some algorithms, but usually not for all it could be registered | ||
| 156 | for by calling the individual functions. | ||
diff --git a/src/lib/libcrypto/man/ENGINE_unregister_RSA.3 b/src/lib/libcrypto/man/ENGINE_unregister_RSA.3 new file mode 100644 index 0000000000..c596554e86 --- /dev/null +++ b/src/lib/libcrypto/man/ENGINE_unregister_RSA.3 | |||
| @@ -0,0 +1,96 @@ | |||
| 1 | .\" $OpenBSD: ENGINE_unregister_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $ | ||
| 2 | .\" content checked up to: | ||
| 3 | .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | ||
| 4 | .\" | ||
| 5 | .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> | ||
| 6 | .\" | ||
| 7 | .\" Permission to use, copy, modify, and distribute this software for any | ||
| 8 | .\" purpose with or without fee is hereby granted, provided that the above | ||
| 9 | .\" copyright notice and this permission notice appear in all copies. | ||
| 10 | .\" | ||
| 11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 17 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 18 | .\" | ||
| 19 | .Dd $Mdocdate: April 15 2018 $ | ||
| 20 | .Dt ENGINE_UNREGISTER_RSA 3 | ||
| 21 | .Os | ||
| 22 | .Sh NAME | ||
| 23 | .Nm ENGINE_unregister_RSA , | ||
| 24 | .Nm ENGINE_unregister_DSA , | ||
| 25 | .Nm ENGINE_unregister_ECDH , | ||
| 26 | .Nm ENGINE_unregister_ECDSA , | ||
| 27 | .Nm ENGINE_unregister_DH , | ||
| 28 | .Nm ENGINE_unregister_RAND , | ||
| 29 | .Nm ENGINE_unregister_STORE , | ||
| 30 | .Nm ENGINE_unregister_ciphers , | ||
| 31 | .Nm ENGINE_unregister_digests | ||
| 32 | .Nd revoke the registration of an ENGINE object | ||
| 33 | .Sh SYNOPSIS | ||
| 34 | .In openssl/engine.h | ||
| 35 | .Ft void | ||
| 36 | .Fo ENGINE_unregister_RSA | ||
| 37 | .Fa "ENGINE *e" | ||
| 38 | .Fc | ||
| 39 | .Ft void | ||
| 40 | .Fo ENGINE_unregister_DSA | ||
| 41 | .Fa "ENGINE *e" | ||
| 42 | .Fc | ||
| 43 | .Ft void | ||
| 44 | .Fo ENGINE_unregister_ECDH | ||
| 45 | .Fa "ENGINE *e" | ||
| 46 | .Fc | ||
| 47 | .Ft void | ||
| 48 | .Fo ENGINE_unregister_ECDSA | ||
| 49 | .Fa "ENGINE *e" | ||
| 50 | .Fc | ||
| 51 | .Ft void | ||
| 52 | .Fo ENGINE_unregister_DH | ||
| 53 | .Fa "ENGINE *e" | ||
| 54 | .Fc | ||
| 55 | .Ft void | ||
| 56 | .Fo ENGINE_unregister_RAND | ||
| 57 | .Fa "ENGINE *e" | ||
| 58 | .Fc | ||
| 59 | .Ft void | ||
| 60 | .Fo ENGINE_unregister_STORE | ||
| 61 | .Fa "ENGINE *e" | ||
| 62 | .Fc | ||
| 63 | .Ft void | ||
| 64 | .Fo ENGINE_unregister_ciphers | ||
| 65 | .Fa "ENGINE *e" | ||
| 66 | .Fc | ||
| 67 | .Ft void | ||
| 68 | .Fo ENGINE_unregister_digests | ||
| 69 | .Fa "ENGINE *e" | ||
| 70 | .Fc | ||
| 71 | .Sh DESCRIPTION | ||
| 72 | These functions remove | ||
| 73 | .Fa e | ||
| 74 | from the list of | ||
| 75 | .Vt ENGINE | ||
| 76 | objects that were previously registered for the respective algorithm | ||
| 77 | with the functions described in | ||
| 78 | .Xr ENGINE_register_RSA 3 . | ||
| 79 | .Pp | ||
| 80 | If | ||
| 81 | .Fa e | ||
| 82 | is currently used as the default engine for the algorithm | ||
| 83 | as described in the | ||
| 84 | .Fn ENGINE_set_default 3 | ||
| 85 | and | ||
| 86 | .Fn ENGINE_get_default_RSA 3 | ||
| 87 | manual pages, | ||
| 88 | .Xr ENGINE_finish | ||
| 89 | is also called. | ||
| 90 | .Pp | ||
| 91 | .Fn ENGINE_unregister_ciphers | ||
| 92 | and | ||
| 93 | .Fn ENGINE_unregister_digests | ||
| 94 | unregister | ||
| 95 | .Fa e | ||
| 96 | for all ciphers or digests, respectively. | ||
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 0405a06663..a83ae5d3ed 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile | |||
| @@ -1,4 +1,4 @@ | |||
| 1 | # $OpenBSD: Makefile,v 1.138 2018/03/18 13:06:36 schwarze Exp $ | 1 | # $OpenBSD: Makefile,v 1.139 2018/04/15 01:43:45 schwarze Exp $ |
| 2 | 2 | ||
| 3 | .include <bsd.own.mk> | 3 | .include <bsd.own.mk> |
| 4 | 4 | ||
| @@ -97,6 +97,14 @@ MAN= \ | |||
| 97 | EC_KEY_new.3 \ | 97 | EC_KEY_new.3 \ |
| 98 | EC_POINT_add.3 \ | 98 | EC_POINT_add.3 \ |
| 99 | EC_POINT_new.3 \ | 99 | EC_POINT_new.3 \ |
| 100 | ENGINE_add.3 \ | ||
| 101 | ENGINE_ctrl.3 \ | ||
| 102 | ENGINE_get_default_RSA.3 \ | ||
| 103 | ENGINE_init.3 \ | ||
| 104 | ENGINE_register_RSA.3 \ | ||
| 105 | ENGINE_register_all_RSA.3 \ | ||
| 106 | ENGINE_set_default.3 \ | ||
| 107 | ENGINE_unregister_RSA.3 \ | ||
| 100 | ERR.3 \ | 108 | ERR.3 \ |
| 101 | ERR_GET_LIB.3 \ | 109 | ERR_GET_LIB.3 \ |
| 102 | ERR_asprintf_error_data.3 \ | 110 | ERR_asprintf_error_data.3 \ |
diff --git a/src/lib/libcrypto/man/engine.3 b/src/lib/libcrypto/man/engine.3 index d93f06f024..fac4fa13e1 100644 --- a/src/lib/libcrypto/man/engine.3 +++ b/src/lib/libcrypto/man/engine.3 | |||
| @@ -1,4 +1,4 @@ | |||
| 1 | .\" $OpenBSD: engine.3,v 1.14 2018/04/14 11:38:32 schwarze Exp $ | 1 | .\" $OpenBSD: engine.3,v 1.15 2018/04/15 01:43:45 schwarze Exp $ |
| 2 | .\" full merge up to: OpenSSL crypto/engine e6390aca Jul 21 10:06:03 2015 -0400 | 2 | .\" full merge up to: OpenSSL crypto/engine e6390aca Jul 21 10:06:03 2015 -0400 |
| 3 | .\" selective merge up to: man3/ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 | 3 | .\" selective merge up to: man3/ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 |
| 4 | .\" | 4 | .\" |
| @@ -51,77 +51,14 @@ | |||
| 51 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | 51 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
| 52 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. | 52 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. |
| 53 | .\" | 53 | .\" |
| 54 | .Dd $Mdocdate: April 14 2018 $ | 54 | .Dd $Mdocdate: April 15 2018 $ |
| 55 | .Dt ENGINE 3 | 55 | .Dt ENGINE 3 |
| 56 | .Os | 56 | .Os |
| 57 | .Sh NAME | 57 | .Sh NAME |
| 58 | .Nm ENGINE_get_first , | ||
| 59 | .Nm ENGINE_get_last , | ||
| 60 | .Nm ENGINE_get_next , | ||
| 61 | .Nm ENGINE_get_prev , | ||
| 62 | .Nm ENGINE_add , | ||
| 63 | .Nm ENGINE_remove , | ||
| 64 | .Nm ENGINE_by_id , | ||
| 65 | .Nm ENGINE_init , | ||
| 66 | .Nm ENGINE_finish , | ||
| 67 | .Nm ENGINE_load_openssl , | 58 | .Nm ENGINE_load_openssl , |
| 68 | .Nm ENGINE_load_dynamic , | 59 | .Nm ENGINE_load_dynamic , |
| 69 | .Nm ENGINE_load_cryptodev , | ||
| 70 | .Nm ENGINE_load_builtin_engines , | 60 | .Nm ENGINE_load_builtin_engines , |
| 71 | .Nm ENGINE_cleanup , | 61 | .Nm ENGINE_cleanup , |
| 72 | .Nm ENGINE_get_default_RSA , | ||
| 73 | .Nm ENGINE_get_default_DSA , | ||
| 74 | .Nm ENGINE_get_default_ECDH , | ||
| 75 | .Nm ENGINE_get_default_ECDSA , | ||
| 76 | .Nm ENGINE_get_default_DH , | ||
| 77 | .Nm ENGINE_get_default_RAND , | ||
| 78 | .Nm ENGINE_get_cipher_engine , | ||
| 79 | .Nm ENGINE_get_digest_engine , | ||
| 80 | .Nm ENGINE_set_default_RSA , | ||
| 81 | .Nm ENGINE_set_default_DSA , | ||
| 82 | .Nm ENGINE_set_default_ECDH , | ||
| 83 | .Nm ENGINE_set_default_ECDSA , | ||
| 84 | .Nm ENGINE_set_default_DH , | ||
| 85 | .Nm ENGINE_set_default_RAND , | ||
| 86 | .Nm ENGINE_set_default_ciphers , | ||
| 87 | .Nm ENGINE_set_default_digests , | ||
| 88 | .Nm ENGINE_set_default_string , | ||
| 89 | .Nm ENGINE_set_default , | ||
| 90 | .Nm ENGINE_get_table_flags , | ||
| 91 | .Nm ENGINE_set_table_flags , | ||
| 92 | .Nm ENGINE_register_RSA , | ||
| 93 | .Nm ENGINE_unregister_RSA , | ||
| 94 | .Nm ENGINE_register_all_RSA , | ||
| 95 | .Nm ENGINE_register_DSA , | ||
| 96 | .Nm ENGINE_unregister_DSA , | ||
| 97 | .Nm ENGINE_register_all_DSA , | ||
| 98 | .Nm ENGINE_register_ECDH , | ||
| 99 | .Nm ENGINE_unregister_ECDH , | ||
| 100 | .Nm ENGINE_register_all_ECDH , | ||
| 101 | .Nm ENGINE_register_ECDSA , | ||
| 102 | .Nm ENGINE_unregister_ECDSA , | ||
| 103 | .Nm ENGINE_register_all_ECDSA , | ||
| 104 | .Nm ENGINE_register_DH , | ||
| 105 | .Nm ENGINE_unregister_DH , | ||
| 106 | .Nm ENGINE_register_all_DH , | ||
| 107 | .Nm ENGINE_register_RAND , | ||
| 108 | .Nm ENGINE_unregister_RAND , | ||
| 109 | .Nm ENGINE_register_all_RAND , | ||
| 110 | .Nm ENGINE_register_STORE , | ||
| 111 | .Nm ENGINE_unregister_STORE , | ||
| 112 | .Nm ENGINE_register_all_STORE , | ||
| 113 | .Nm ENGINE_register_ciphers , | ||
| 114 | .Nm ENGINE_unregister_ciphers , | ||
| 115 | .Nm ENGINE_register_all_ciphers , | ||
| 116 | .Nm ENGINE_register_digests , | ||
| 117 | .Nm ENGINE_unregister_digests , | ||
| 118 | .Nm ENGINE_register_all_digests , | ||
| 119 | .Nm ENGINE_register_complete , | ||
| 120 | .Nm ENGINE_register_all_complete , | ||
| 121 | .Nm ENGINE_ctrl , | ||
| 122 | .Nm ENGINE_cmd_is_executable , | ||
| 123 | .Nm ENGINE_ctrl_cmd , | ||
| 124 | .Nm ENGINE_ctrl_cmd_string , | ||
| 125 | .Nm ENGINE_new , | 62 | .Nm ENGINE_new , |
| 126 | .Nm ENGINE_free , | 63 | .Nm ENGINE_free , |
| 127 | .Nm ENGINE_up_ref , | 64 | .Nm ENGINE_up_ref , |
| @@ -135,15 +72,11 @@ | |||
| 135 | .Nm ENGINE_set_RAND , | 72 | .Nm ENGINE_set_RAND , |
| 136 | .Nm ENGINE_set_STORE , | 73 | .Nm ENGINE_set_STORE , |
| 137 | .Nm ENGINE_set_destroy_function , | 74 | .Nm ENGINE_set_destroy_function , |
| 138 | .Nm ENGINE_set_init_function , | ||
| 139 | .Nm ENGINE_set_finish_function , | ||
| 140 | .Nm ENGINE_set_ctrl_function , | ||
| 141 | .Nm ENGINE_set_load_privkey_function , | 75 | .Nm ENGINE_set_load_privkey_function , |
| 142 | .Nm ENGINE_set_load_pubkey_function , | 76 | .Nm ENGINE_set_load_pubkey_function , |
| 143 | .Nm ENGINE_set_ciphers , | 77 | .Nm ENGINE_set_ciphers , |
| 144 | .Nm ENGINE_set_digests , | 78 | .Nm ENGINE_set_digests , |
| 145 | .Nm ENGINE_set_flags , | 79 | .Nm ENGINE_set_flags , |
| 146 | .Nm ENGINE_set_cmd_defns , | ||
| 147 | .Nm ENGINE_get_id , | 80 | .Nm ENGINE_get_id , |
| 148 | .Nm ENGINE_get_name , | 81 | .Nm ENGINE_get_name , |
| 149 | .Nm ENGINE_get_RSA , | 82 | .Nm ENGINE_get_RSA , |
| @@ -154,9 +87,6 @@ | |||
| 154 | .Nm ENGINE_get_RAND , | 87 | .Nm ENGINE_get_RAND , |
| 155 | .Nm ENGINE_get_STORE , | 88 | .Nm ENGINE_get_STORE , |
| 156 | .Nm ENGINE_get_destroy_function , | 89 | .Nm ENGINE_get_destroy_function , |
| 157 | .Nm ENGINE_get_init_function , | ||
| 158 | .Nm ENGINE_get_finish_function , | ||
| 159 | .Nm ENGINE_get_ctrl_function , | ||
| 160 | .Nm ENGINE_get_load_privkey_function , | 90 | .Nm ENGINE_get_load_privkey_function , |
| 161 | .Nm ENGINE_get_load_pubkey_function , | 91 | .Nm ENGINE_get_load_pubkey_function , |
| 162 | .Nm ENGINE_get_ciphers , | 92 | .Nm ENGINE_get_ciphers , |
| @@ -164,248 +94,20 @@ | |||
| 164 | .Nm ENGINE_get_cipher , | 94 | .Nm ENGINE_get_cipher , |
| 165 | .Nm ENGINE_get_digest , | 95 | .Nm ENGINE_get_digest , |
| 166 | .Nm ENGINE_get_flags , | 96 | .Nm ENGINE_get_flags , |
| 167 | .Nm ENGINE_get_cmd_defns , | ||
| 168 | .Nm ENGINE_load_private_key , | 97 | .Nm ENGINE_load_private_key , |
| 169 | .Nm ENGINE_load_public_key | 98 | .Nm ENGINE_load_public_key |
| 170 | .Nd ENGINE cryptographic module support | 99 | .Nd ENGINE cryptographic module support |
| 171 | .Sh SYNOPSIS | 100 | .Sh SYNOPSIS |
| 172 | .In openssl/engine.h | 101 | .In openssl/engine.h |
| 173 | .Ft ENGINE * | ||
| 174 | .Fn ENGINE_get_first void | ||
| 175 | .Ft ENGINE * | ||
| 176 | .Fn ENGINE_get_last void | ||
| 177 | .Ft ENGINE * | ||
| 178 | .Fo ENGINE_get_next | ||
| 179 | .Fa "ENGINE *e" | ||
| 180 | .Fc | ||
| 181 | .Ft ENGINE * | ||
| 182 | .Fo ENGINE_get_prev | ||
| 183 | .Fa "ENGINE *e" | ||
| 184 | .Fc | ||
| 185 | .Ft int | ||
| 186 | .Fo ENGINE_add | ||
| 187 | .Fa "ENGINE *e" | ||
| 188 | .Fc | ||
| 189 | .Ft int | ||
| 190 | .Fo ENGINE_remove | ||
| 191 | .Fa "ENGINE *e" | ||
| 192 | .Fc | ||
| 193 | .Ft ENGINE * | ||
| 194 | .Fo ENGINE_by_id | ||
| 195 | .Fa "const char *id" | ||
| 196 | .Fc | ||
| 197 | .Ft int | ||
| 198 | .Fo ENGINE_init | ||
| 199 | .Fa "ENGINE *e" | ||
| 200 | .Fc | ||
| 201 | .Ft int | ||
| 202 | .Fo ENGINE_finish | ||
| 203 | .Fa "ENGINE *e" | ||
| 204 | .Fc | ||
| 205 | .Ft void | 102 | .Ft void |
| 206 | .Fn ENGINE_load_openssl void | 103 | .Fn ENGINE_load_openssl void |
| 207 | .Ft void | 104 | .Ft void |
| 208 | .Fn ENGINE_load_dynamic void | 105 | .Fn ENGINE_load_dynamic void |
| 209 | .Ft void | 106 | .Ft void |
| 210 | .Fn ENGINE_load_cryptodev void | ||
| 211 | .Ft void | ||
| 212 | .Fn ENGINE_load_builtin_engines void | 107 | .Fn ENGINE_load_builtin_engines void |
| 213 | .Ft void | 108 | .Ft void |
| 214 | .Fn ENGINE_cleanup void | 109 | .Fn ENGINE_cleanup void |
| 215 | .Ft ENGINE * | 110 | .Ft ENGINE * |
| 216 | .Fn ENGINE_get_default_RSA void | ||
| 217 | .Ft ENGINE * | ||
| 218 | .Fn ENGINE_get_default_DSA void | ||
| 219 | .Ft ENGINE * | ||
| 220 | .Fn ENGINE_get_default_ECDH void | ||
| 221 | .Ft ENGINE * | ||
| 222 | .Fn ENGINE_get_default_ECDSA void | ||
| 223 | .Ft ENGINE * | ||
| 224 | .Fn ENGINE_get_default_DH void | ||
| 225 | .Ft ENGINE * | ||
| 226 | .Fn ENGINE_get_default_RAND void | ||
| 227 | .Ft ENGINE * | ||
| 228 | .Fo ENGINE_get_cipher_engine | ||
| 229 | .Fa "int nid" | ||
| 230 | .Fc | ||
| 231 | .Ft ENGINE * | ||
| 232 | .Fo ENGINE_get_digest_engine | ||
| 233 | .Fa "int nid" | ||
| 234 | .Fc | ||
| 235 | .Ft int | ||
| 236 | .Fo ENGINE_set_default_RSA | ||
| 237 | .Fa "ENGINE *e" | ||
| 238 | .Fc | ||
| 239 | .Ft int | ||
| 240 | .Fo ENGINE_set_default_DSA | ||
| 241 | .Fa "ENGINE *e" | ||
| 242 | .Fc | ||
| 243 | .Ft int | ||
| 244 | .Fo ENGINE_set_default_ECDH | ||
| 245 | .Fa "ENGINE *e" | ||
| 246 | .Fc | ||
| 247 | .Ft int | ||
| 248 | .Fo ENGINE_set_default_ECDSA | ||
| 249 | .Fa "ENGINE *e" | ||
| 250 | .Fc | ||
| 251 | .Ft int | ||
| 252 | .Fo ENGINE_set_default_DH | ||
| 253 | .Fa "ENGINE *e" | ||
| 254 | .Fc | ||
| 255 | .Ft int | ||
| 256 | .Fo ENGINE_set_default_RAND | ||
| 257 | .Fa "ENGINE *e" | ||
| 258 | .Fc | ||
| 259 | .Ft int | ||
| 260 | .Fo ENGINE_set_default_ciphers | ||
| 261 | .Fa "ENGINE *e" | ||
| 262 | .Fc | ||
| 263 | .Ft int | ||
| 264 | .Fo ENGINE_set_default_digests | ||
| 265 | .Fa "ENGINE *e" | ||
| 266 | .Fc | ||
| 267 | .Ft int | ||
| 268 | .Fo ENGINE_set_default_string | ||
| 269 | .Fa "ENGINE *e" | ||
| 270 | .Fa "const char *list" | ||
| 271 | .Fc | ||
| 272 | .Ft int | ||
| 273 | .Fo ENGINE_set_default | ||
| 274 | .Fa "ENGINE *e" | ||
| 275 | .Fa "unsigned int flags" | ||
| 276 | .Fc | ||
| 277 | .Ft unsigned int | ||
| 278 | .Fn ENGINE_get_table_flags void | ||
| 279 | .Ft void | ||
| 280 | .Fo ENGINE_set_table_flags | ||
| 281 | .Fa "unsigned int flags" | ||
| 282 | .Fc | ||
| 283 | .Ft int | ||
| 284 | .Fo ENGINE_register_RSA | ||
| 285 | .Fa "ENGINE *e" | ||
| 286 | .Fc | ||
| 287 | .Ft void | ||
| 288 | .Fo ENGINE_unregister_RSA | ||
| 289 | .Fa "ENGINE *e" | ||
| 290 | .Fc | ||
| 291 | .Ft void | ||
| 292 | .Fn ENGINE_register_all_RSA void | ||
| 293 | .Ft int | ||
| 294 | .Fo ENGINE_register_DSA | ||
| 295 | .Fa "ENGINE *e" | ||
| 296 | .Fc | ||
| 297 | .Ft void | ||
| 298 | .Fo ENGINE_unregister_DSA | ||
| 299 | .Fa "ENGINE *e" | ||
| 300 | .Fc | ||
| 301 | .Ft void | ||
| 302 | .Fn ENGINE_register_all_DSA void | ||
| 303 | .Ft int | ||
| 304 | .Fo ENGINE_register_ECDH | ||
| 305 | .Fa "ENGINE *e" | ||
| 306 | .Fc | ||
| 307 | .Ft void | ||
| 308 | .Fo ENGINE_unregister_ECDH | ||
| 309 | .Fa "ENGINE *e" | ||
| 310 | .Fc | ||
| 311 | .Ft void | ||
| 312 | .Fn ENGINE_register_all_ECDH void | ||
| 313 | .Ft int | ||
| 314 | .Fo ENGINE_register_ECDSA | ||
| 315 | .Fa "ENGINE *e" | ||
| 316 | .Fc | ||
| 317 | .Ft void | ||
| 318 | .Fo ENGINE_unregister_ECDSA | ||
| 319 | .Fa "ENGINE *e" | ||
| 320 | .Fc | ||
| 321 | .Ft void | ||
| 322 | .Fn ENGINE_register_all_ECDSA void | ||
| 323 | .Ft int | ||
| 324 | .Fo ENGINE_register_DH | ||
| 325 | .Fa "ENGINE *e" | ||
| 326 | .Fc | ||
| 327 | .Ft void | ||
| 328 | .Fo ENGINE_unregister_DH | ||
| 329 | .Fa "ENGINE *e" | ||
| 330 | .Fc | ||
| 331 | .Ft void | ||
| 332 | .Fn ENGINE_register_all_DH void | ||
| 333 | .Ft int | ||
| 334 | .Fo ENGINE_register_RAND | ||
| 335 | .Fa "ENGINE *e" | ||
| 336 | .Fc | ||
| 337 | .Ft void | ||
| 338 | .Fo ENGINE_unregister_RAND | ||
| 339 | .Fa "ENGINE *e" | ||
| 340 | .Fc | ||
| 341 | .Ft void | ||
| 342 | .Fn ENGINE_register_all_RAND void | ||
| 343 | .Ft int | ||
| 344 | .Fo ENGINE_register_STORE | ||
| 345 | .Fa "ENGINE *e" | ||
| 346 | .Fc | ||
| 347 | .Ft void | ||
| 348 | .Fo ENGINE_unregister_STORE | ||
| 349 | .Fa "ENGINE *e" | ||
| 350 | .Fc | ||
| 351 | .Ft void | ||
| 352 | .Fn ENGINE_register_all_STORE void | ||
| 353 | .Ft int | ||
| 354 | .Fo ENGINE_register_ciphers | ||
| 355 | .Fa "ENGINE *e" | ||
| 356 | .Fc | ||
| 357 | .Ft void | ||
| 358 | .Fo ENGINE_unregister_ciphers | ||
| 359 | .Fa "ENGINE *e" | ||
| 360 | .Fc | ||
| 361 | .Ft void | ||
| 362 | .Fn ENGINE_register_all_ciphers void | ||
| 363 | .Ft int | ||
| 364 | .Fo ENGINE_register_digests | ||
| 365 | .Fa "ENGINE *e" | ||
| 366 | .Fc | ||
| 367 | .Ft void | ||
| 368 | .Fo ENGINE_unregister_digests | ||
| 369 | .Fa "ENGINE *e" | ||
| 370 | .Fc | ||
| 371 | .Ft void | ||
| 372 | .Fn ENGINE_register_all_digests void | ||
| 373 | .Ft int | ||
| 374 | .Fo ENGINE_register_complete | ||
| 375 | .Fa "ENGINE *e" | ||
| 376 | .Fc | ||
| 377 | .Ft int | ||
| 378 | .Fn ENGINE_register_all_complete void | ||
| 379 | .Ft int | ||
| 380 | .Fo ENGINE_ctrl | ||
| 381 | .Fa "ENGINE *e" | ||
| 382 | .Fa "int cmd" | ||
| 383 | .Fa "long i" | ||
| 384 | .Fa "void *p" | ||
| 385 | .Fa "void (*f)(void)" | ||
| 386 | .Fc | ||
| 387 | .Ft int | ||
| 388 | .Fo ENGINE_cmd_is_executable | ||
| 389 | .Fa "ENGINE *e" | ||
| 390 | .Fa "int cmd" | ||
| 391 | .Fc | ||
| 392 | .Ft int | ||
| 393 | .Fo ENGINE_ctrl_cmd | ||
| 394 | .Fa "ENGINE *e" | ||
| 395 | .Fa "const char *cmd_name" | ||
| 396 | .Fa "long i" | ||
| 397 | .Fa "void *p" | ||
| 398 | .Fa "void (*f)(void)" | ||
| 399 | .Fa "int cmd_optional" | ||
| 400 | .Fc | ||
| 401 | .Ft int | ||
| 402 | .Fo ENGINE_ctrl_cmd_string | ||
| 403 | .Fa "ENGINE *e" | ||
| 404 | .Fa "const char *cmd_name" | ||
| 405 | .Fa "const char *arg" | ||
| 406 | .Fa "int cmd_optional" | ||
| 407 | .Fc | ||
| 408 | .Ft ENGINE * | ||
| 409 | .Fn ENGINE_new void | 111 | .Fn ENGINE_new void |
| 410 | .Ft int | 112 | .Ft int |
| 411 | .Fo ENGINE_free | 113 | .Fo ENGINE_free |
| @@ -466,21 +168,6 @@ | |||
| 466 | .Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f" | 168 | .Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f" |
| 467 | .Fc | 169 | .Fc |
| 468 | .Ft int | 170 | .Ft int |
| 469 | .Fo ENGINE_set_init_function | ||
| 470 | .Fa "ENGINE *e" | ||
| 471 | .Fa "ENGINE_GEN_INT_FUNC_PTR init_f" | ||
| 472 | .Fc | ||
| 473 | .Ft int | ||
| 474 | .Fo ENGINE_set_finish_function | ||
| 475 | .Fa "ENGINE *e" | ||
| 476 | .Fa "ENGINE_GEN_INT_FUNC_PTR finish_f" | ||
| 477 | .Fc | ||
| 478 | .Ft int | ||
| 479 | .Fo ENGINE_set_ctrl_function | ||
| 480 | .Fa "ENGINE *e" | ||
| 481 | .Fa "ENGINE_CTRL_FUNC_PTR ctrl_f" | ||
| 482 | .Fc | ||
| 483 | .Ft int | ||
| 484 | .Fo ENGINE_set_load_privkey_function | 171 | .Fo ENGINE_set_load_privkey_function |
| 485 | .Fa "ENGINE *e" | 172 | .Fa "ENGINE *e" |
| 486 | .Fa "ENGINE_LOAD_KEY_PTR loadpriv_f" | 173 | .Fa "ENGINE_LOAD_KEY_PTR loadpriv_f" |
| @@ -505,11 +192,6 @@ | |||
| 505 | .Fa "ENGINE *e" | 192 | .Fa "ENGINE *e" |
| 506 | .Fa "int flags" | 193 | .Fa "int flags" |
| 507 | .Fc | 194 | .Fc |
| 508 | .Ft int | ||
| 509 | .Fo ENGINE_set_cmd_defns | ||
| 510 | .Fa "ENGINE *e" | ||
| 511 | .Fa "const ENGINE_CMD_DEFN *defns" | ||
| 512 | .Fc | ||
| 513 | .Ft const char * | 195 | .Ft const char * |
| 514 | .Fo ENGINE_get_id | 196 | .Fo ENGINE_get_id |
| 515 | .Fa "const ENGINE *e" | 197 | .Fa "const ENGINE *e" |
| @@ -550,18 +232,6 @@ | |||
| 550 | .Fo ENGINE_get_destroy_function | 232 | .Fo ENGINE_get_destroy_function |
| 551 | .Fa "const ENGINE *e" | 233 | .Fa "const ENGINE *e" |
| 552 | .Fc | 234 | .Fc |
| 553 | .Ft ENGINE_GEN_INT_FUNC_PTR | ||
| 554 | .Fo ENGINE_get_init_function | ||
| 555 | .Fa "const ENGINE *e" | ||
| 556 | .Fc | ||
| 557 | .Ft ENGINE_GEN_INT_FUNC_PTR | ||
| 558 | .Fo ENGINE_get_finish_function | ||
| 559 | .Fa "const ENGINE *e" | ||
| 560 | .Fc | ||
| 561 | .Ft ENGINE_CTRL_FUNC_PTR | ||
| 562 | .Fo ENGINE_get_ctrl_function | ||
| 563 | .Fa "const ENGINE *e" | ||
| 564 | .Fc | ||
| 565 | .Ft ENGINE_LOAD_KEY_PTR | 235 | .Ft ENGINE_LOAD_KEY_PTR |
| 566 | .Fo ENGINE_get_load_privkey_function | 236 | .Fo ENGINE_get_load_privkey_function |
| 567 | .Fa "const ENGINE *e" | 237 | .Fa "const ENGINE *e" |
| @@ -592,10 +262,6 @@ | |||
| 592 | .Fo ENGINE_get_flags | 262 | .Fo ENGINE_get_flags |
| 593 | .Fa "const ENGINE *e" | 263 | .Fa "const ENGINE *e" |
| 594 | .Fc | 264 | .Fc |
| 595 | .Ft const ENGINE_CMD_DEFN * | ||
| 596 | .Fo ENGINE_get_cmd_defns | ||
| 597 | .Fa "const ENGINE *e" | ||
| 598 | .Fc | ||
| 599 | .Ft EVP_PKEY * | 265 | .Ft EVP_PKEY * |
| 600 | .Fo ENGINE_load_private_key | 266 | .Fo ENGINE_load_private_key |
| 601 | .Fa "ENGINE *e" | 267 | .Fa "ENGINE *e" |
| @@ -712,20 +378,23 @@ and its functional reference count to 0. | |||
| 712 | Many functions increment the structural reference count by 1 | 378 | Many functions increment the structural reference count by 1 |
| 713 | when successful. | 379 | when successful. |
| 714 | Some of them, including | 380 | Some of them, including |
| 715 | .Fn ENGINE_by_id , | 381 | .Xr ENGINE_by_id 3 , |
| 716 | .Fn ENGINE_get_first , | 382 | .Xr ENGINE_get_first 3 , |
| 717 | .Fn ENGINE_get_last , | 383 | .Xr ENGINE_get_last 3 , |
| 718 | .Fn ENGINE_get_next , | 384 | .Xr ENGINE_get_next 3 , |
| 719 | and | 385 | and |
| 720 | .Fn ENGINE_get_prev , | 386 | .Xr ENGINE_get_prev 3 , |
| 721 | do so because they return a structural reference to the user. | 387 | do so because they return a structural reference to the user. |
| 722 | Other functions, including | 388 | Other functions, including |
| 723 | .Fn ENGINE_add , | 389 | .Xr ENGINE_add 3 , |
| 724 | .Fn ENGINE_init , | 390 | .Xr ENGINE_init 3 , |
| 725 | .Fn ENGINE_get_default_* , | 391 | .Xr ENGINE_get_cipher_engine 3 , |
| 726 | .Fn ENGINE_get_*_engine , | 392 | .Xr ENGINE_get_digest_engine 3 , |
| 393 | and the | ||
| 394 | .Xr ENGINE_get_default_RSA 3 | ||
| 727 | and | 395 | and |
| 728 | .Fn ENGINE_set_default_* , | 396 | .Xr ENGINE_set_default 3 |
| 397 | families of functions | ||
| 729 | do so because they store a structural refence internally. | 398 | do so because they store a structural refence internally. |
| 730 | .Fn ENGINE_up_ref | 399 | .Fn ENGINE_up_ref |
| 731 | explicitly increment the structural reference count by 1. | 400 | explicitly increment the structural reference count by 1. |
| @@ -747,144 +416,17 @@ pointer, no action occurs. | |||
| 747 | Many functions internally call the equivalent of | 416 | Many functions internally call the equivalent of |
| 748 | .Fn ENGINE_free . | 417 | .Fn ENGINE_free . |
| 749 | Some of them, including | 418 | Some of them, including |
| 750 | .Fn ENGINE_get_next | 419 | .Xr ENGINE_get_next 3 |
| 751 | and | 420 | and |
| 752 | .Fn ENGINE_get_prev , | 421 | .Xr ENGINE_get_prev 3 , |
| 753 | thus invalidate the structural reference passed in by the user. | 422 | thus invalidate the structural reference passed in by the user. |
| 754 | Other functions, including | 423 | Other functions, including |
| 755 | .Fn ENGINE_finish , | 424 | .Xr ENGINE_finish 3 , |
| 756 | .Fn ENGINE_remove , | 425 | .Xr ENGINE_remove 3 , |
| 757 | .Fn ENGINE_get_default_* , | 426 | and the |
| 758 | .Fn ENGINE_get_*_engine , | 427 | .Xr ENGINE_set_default 3 |
| 759 | and | 428 | family of functions |
| 760 | .Fn ENGINE_set_default_* , | ||
| 761 | do so when an internally stored structural reference is no longer needed. | 429 | do so when an internally stored structural reference is no longer needed. |
| 762 | .Pp | ||
| 763 | .Em Functional references | ||
| 764 | .Pp | ||
| 765 | As mentioned, functional references exist when the cryptographic | ||
| 766 | functionality of an | ||
| 767 | .Vt ENGINE | ||
| 768 | is required to be available. | ||
| 769 | A functional reference can be obtained in one of two ways; from an | ||
| 770 | existing structural reference to the required | ||
| 771 | .Vt ENGINE , | ||
| 772 | or by asking OpenSSL for the default operational | ||
| 773 | .Vt ENGINE | ||
| 774 | for a given cryptographic purpose. | ||
| 775 | .Pp | ||
| 776 | To obtain a functional reference from an existing structural reference, | ||
| 777 | call the | ||
| 778 | .Fn ENGINE_init | ||
| 779 | function. | ||
| 780 | This returns zero if the | ||
| 781 | .Vt ENGINE | ||
| 782 | was not already operational and couldn't be successfully initialised | ||
| 783 | (e.g. lack of system drivers, no special hardware attached), | ||
| 784 | otherwise it will return non-zero to indicate that the | ||
| 785 | .Vt ENGINE | ||
| 786 | is now operational and will have allocated a new | ||
| 787 | .Sy functional | ||
| 788 | reference to the | ||
| 789 | .Vt ENGINE . | ||
| 790 | All functional references are released by calling | ||
| 791 | .Fn ENGINE_finish , | ||
| 792 | which removes the implicit structural reference as well. | ||
| 793 | .Pp | ||
| 794 | The second way to get a functional reference is by asking OpenSSL for a | ||
| 795 | default implementation for a given task, e.g. | ||
| 796 | by | ||
| 797 | .Fn ENGINE_get_default_RSA , | ||
| 798 | .Fn ENGINE_get_default_cipher_engine , | ||
| 799 | etc. | ||
| 800 | These are discussed in the next section, though they are not usually | ||
| 801 | required by application programmers as they are used automatically when | ||
| 802 | creating and using the relevant algorithm-specific types in OpenSSL, | ||
| 803 | such as RSA, DSA, EVP_CIPHER_CTX, etc. | ||
| 804 | .Ss Default implementations | ||
| 805 | For each supported abstraction, the | ||
| 806 | .Nm engine | ||
| 807 | code maintains an internal table of state to control which | ||
| 808 | implementations are available for a given abstraction and which | ||
| 809 | should be used by default. | ||
| 810 | These implementations are registered in the tables and indexed by an | ||
| 811 | .Fa nid | ||
| 812 | value, because abstractions like | ||
| 813 | .Vt EVP_CIPHER | ||
| 814 | and | ||
| 815 | .Vt EVP_DIGEST | ||
| 816 | support many distinct algorithms and modes, and | ||
| 817 | .Vt ENGINE Ns s | ||
| 818 | can support arbitrarily many of them. | ||
| 819 | In the case of other abstractions like RSA, DSA, etc., there is | ||
| 820 | only one "algorithm" so all implementations implicitly register | ||
| 821 | using the same | ||
| 822 | .Fa nid | ||
| 823 | index. | ||
| 824 | .Pp | ||
| 825 | When a default | ||
| 826 | .Vt ENGINE | ||
| 827 | is requested for a given abstraction/algorithm/mode, (e.g. when | ||
| 828 | calling | ||
| 829 | .Fn RSA_new_method NULL ) , | ||
| 830 | a "get_default" call will be made to the | ||
| 831 | .Nm engine | ||
| 832 | subsystem to process the corresponding state table and return | ||
| 833 | a functional reference to an initialised | ||
| 834 | .Vt ENGINE | ||
| 835 | whose implementation should be used. | ||
| 836 | If no | ||
| 837 | .Vt ENGINE | ||
| 838 | should (or can) be used, it will return | ||
| 839 | .Dv NULL | ||
| 840 | and the caller will operate with a | ||
| 841 | .Dv NULL | ||
| 842 | .Vt ENGINE | ||
| 843 | handle. | ||
| 844 | This usually equates to using the conventional software implementation. | ||
| 845 | In the latter case, OpenSSL will from then on behave the way it used to | ||
| 846 | before the | ||
| 847 | .Nm engine | ||
| 848 | API existed. | ||
| 849 | .Pp | ||
| 850 | Each state table has a flag to note whether it has processed this | ||
| 851 | "get_default" query since the table was last modified, because to | ||
| 852 | process this question it must iterate across all the registered | ||
| 853 | .Vt ENGINE Ns s | ||
| 854 | in the table trying to initialise each of them in turn, in case one of | ||
| 855 | them is operational. | ||
| 856 | If it returns a functional reference to an | ||
| 857 | .Vt ENGINE , | ||
| 858 | it will also cache another reference to speed up processing future | ||
| 859 | queries (without needing to iterate across the table). | ||
| 860 | Likewise, it will cache a | ||
| 861 | .Dv NULL | ||
| 862 | response if no | ||
| 863 | .Vt ENGINE | ||
| 864 | was available so that future queries won't repeat the same iteration | ||
| 865 | unless the state table changes. | ||
| 866 | This behaviour can also be changed; if the | ||
| 867 | .Dv ENGINE_TABLE_FLAG_NOINIT | ||
| 868 | flag is set (using | ||
| 869 | .Fn ENGINE_set_table_flags ) , | ||
| 870 | no attempted initialisations will take place, instead the only way for | ||
| 871 | the state table to return a | ||
| 872 | .Pf non- Dv NULL | ||
| 873 | .Vt ENGINE | ||
| 874 | to the "get_default" query will be if one is expressly set in the table. | ||
| 875 | For example, | ||
| 876 | .Fn ENGINE_set_default_RSA | ||
| 877 | does the same job as | ||
| 878 | .Fn ENGINE_register_RSA | ||
| 879 | except that it also sets the state table's cached response for the | ||
| 880 | "get_default" query. | ||
| 881 | In the case of abstractions like | ||
| 882 | .Vt EVP_CIPHER , | ||
| 883 | where implementations are indexed by | ||
| 884 | .Fa nid , | ||
| 885 | these flags and cached-responses are distinct for each | ||
| 886 | .Fa nid | ||
| 887 | value. | ||
| 888 | .Ss Application requirements | 430 | .Ss Application requirements |
| 889 | This section will explain the basic things an application programmer | 431 | This section will explain the basic things an application programmer |
| 890 | should support to make the most useful elements of the | 432 | should support to make the most useful elements of the |
| @@ -1029,7 +571,7 @@ For example, the next time OpenSSL tries to set up an RSA key, any bundled | |||
| 1029 | that implement | 571 | that implement |
| 1030 | .Vt RSA_METHOD | 572 | .Vt RSA_METHOD |
| 1031 | will be passed to | 573 | will be passed to |
| 1032 | .Fn ENGINE_init | 574 | .Xr ENGINE_init 3 |
| 1033 | and if any of those succeed, that | 575 | and if any of those succeed, that |
| 1034 | .Vt ENGINE | 576 | .Vt ENGINE |
| 1035 | will be set as the default for RSA use from then on. | 577 | will be set as the default for RSA use from then on. |
| @@ -1074,11 +616,11 @@ This class of commands typically needs to be passed to an | |||
| 1074 | .Vt ENGINE | 616 | .Vt ENGINE |
| 1075 | .Sy before | 617 | .Sy before |
| 1076 | attempting to initialise it, i.e. before calling | 618 | attempting to initialise it, i.e. before calling |
| 1077 | .Fn ENGINE_init . | 619 | .Xr ENGINE_init 3 . |
| 1078 | The other class of commands consist of settings or operations that tweak | 620 | The other class of commands consist of settings or operations that tweak |
| 1079 | certain behaviour or cause certain operations to take place, and these | 621 | certain behaviour or cause certain operations to take place, and these |
| 1080 | commands may work either before or after | 622 | commands may work either before or after |
| 1081 | .Fn ENGINE_init , | 623 | .Xr ENGINE_init 3 , |
| 1082 | or in some cases both. | 624 | or in some cases both. |
| 1083 | .Vt ENGINE | 625 | .Vt ENGINE |
| 1084 | implementations should provide indications of this in the descriptions | 626 | implementations should provide indications of this in the descriptions |
| @@ -1295,55 +837,22 @@ to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and | |||
| 1295 | could therefore decide whether or not to support this "foo"-specific | 837 | could therefore decide whether or not to support this "foo"-specific |
| 1296 | extension). | 838 | extension). |
| 1297 | .Sh RETURN VALUES | 839 | .Sh RETURN VALUES |
| 1298 | .Fn ENGINE_get_first , | ||
| 1299 | .Fn ENGINE_get_last , | ||
| 1300 | .Fn ENGINE_get_next , | ||
| 1301 | .Fn ENGINE_get_prev , | ||
| 1302 | .Fn ENGINE_by_id , | ||
| 1303 | .Fn ENGINE_get_cipher_engine , | 840 | .Fn ENGINE_get_cipher_engine , |
| 1304 | .Fn ENGINE_get_digest_engine , | 841 | .Fn ENGINE_get_digest_engine , |
| 1305 | .Fn ENGINE_new , | 842 | and |
| 1306 | and all | 843 | .Fn ENGINE_new |
| 1307 | .Fn ENGINE_get_default_* | 844 | return a valid |
| 1308 | functions return a valid | ||
| 1309 | .Vt ENGINE | 845 | .Vt ENGINE |
| 1310 | structure or | 846 | structure or |
| 1311 | .Dv NULL | 847 | .Dv NULL |
| 1312 | if an error occurred. | 848 | if an error occurred. |
| 1313 | .Pp | 849 | .Pp |
| 1314 | .Fn ENGINE_add , | ||
| 1315 | .Fn ENGINE_remove , | ||
| 1316 | .Fn ENGINE_init , | ||
| 1317 | .Fn ENGINE_finish , | ||
| 1318 | .Fn ENGINE_ctrl_cmd , | ||
| 1319 | .Fn ENGINE_ctrl_cmd_string , | ||
| 1320 | .Fn ENGINE_free , | 850 | .Fn ENGINE_free , |
| 1321 | .Fn ENGINE_up_ref , | 851 | .Fn ENGINE_up_ref , |
| 1322 | and all | 852 | and all |
| 1323 | .Fn ENGINE_set_* | 853 | .Fn ENGINE_set_* |
| 1324 | and | ||
| 1325 | .Fn ENGINE_register_* | ||
| 1326 | functions return 1 on success or 0 on error. | 854 | functions return 1 on success or 0 on error. |
| 1327 | .Pp | 855 | .Pp |
| 1328 | .Fn ENGINE_get_table_flags | ||
| 1329 | returns an unsigned integer value representing the global table | ||
| 1330 | flags which are used to control the registration behaviour of | ||
| 1331 | .Vt ENGINE | ||
| 1332 | implementations. | ||
| 1333 | .Pp | ||
| 1334 | For | ||
| 1335 | .Fn ENGINE_ctrl , | ||
| 1336 | positive return values indicate success and negative return values | ||
| 1337 | indicate failure. | ||
| 1338 | The meaning of a zero return value depends on the particular | ||
| 1339 | .Fa cmd | ||
| 1340 | and may indicate both success and failure, which is pathetic. | ||
| 1341 | .Pp | ||
| 1342 | .Fn ENGINE_cmd_is_executable | ||
| 1343 | returns 1 if | ||
| 1344 | .Fa cmd | ||
| 1345 | is executable or 0 otherwise. | ||
| 1346 | .Pp | ||
| 1347 | .Fn ENGINE_get_id | 856 | .Fn ENGINE_get_id |
| 1348 | and | 857 | and |
| 1349 | .Fn ENGINE_get_name | 858 | .Fn ENGINE_get_name |
| @@ -1361,9 +870,6 @@ and | |||
| 1361 | return a method structure for the respective algorithm. | 870 | return a method structure for the respective algorithm. |
| 1362 | .Pp | 871 | .Pp |
| 1363 | .Fn ENGINE_get_destroy_function , | 872 | .Fn ENGINE_get_destroy_function , |
| 1364 | .Fn ENGINE_get_init_function , | ||
| 1365 | .Fn ENGINE_get_finish_function , | ||
| 1366 | .Fn ENGINE_get_ctrl_function , | ||
| 1367 | .Fn ENGINE_get_load_privkey_function , | 873 | .Fn ENGINE_get_load_privkey_function , |
| 1368 | .Fn ENGINE_get_load_pubkey_function , | 874 | .Fn ENGINE_get_load_pubkey_function , |
| 1369 | .Fn ENGINE_get_ciphers , | 875 | .Fn ENGINE_get_ciphers , |
| @@ -1390,13 +896,6 @@ returns an integer representing the flags | |||
| 1390 | which are used to control various behaviours of an | 896 | which are used to control various behaviours of an |
| 1391 | .Vt ENGINE . | 897 | .Vt ENGINE . |
| 1392 | .Pp | 898 | .Pp |
| 1393 | .Fn ENGINE_get_cmd_defns | ||
| 1394 | returns an | ||
| 1395 | .Vt ENGINE_CMD_DEFN | ||
| 1396 | structure or | ||
| 1397 | .Dv NULL | ||
| 1398 | if none is set. | ||
| 1399 | .Pp | ||
| 1400 | .Fn ENGINE_load_private_key | 899 | .Fn ENGINE_load_private_key |
| 1401 | and | 900 | and |
| 1402 | .Fn ENGINE_load_public_key | 901 | .Fn ENGINE_load_public_key |
