| 1 | Adding new libraries
|
|---|
| 2 | ====================
|
|---|
| 3 |
|
|---|
| 4 | When adding a new sub-library to OpenSSL, assign it a library number
|
|---|
| 5 | `ERR_LIB_XXX`, define a macro `XXXerr()` (both in `err.h`), add its
|
|---|
| 6 | name to `ERR_str_libraries[]` (in `crypto/err/err.c`), and add
|
|---|
| 7 | `ERR_load_XXX_strings()` to the `ERR_load_crypto_strings()` function
|
|---|
| 8 | (in `crypto/err/err_all.c`). Finally, add an entry:
|
|---|
| 9 |
|
|---|
| 10 | L XXX xxx.h xxx_err.c
|
|---|
| 11 |
|
|---|
| 12 | to `crypto/err/openssl.ec`, and add `xxx_err.c` to the `Makefile`.
|
|---|
| 13 | Running make errors will then generate a file `xxx_err.c`, and
|
|---|
| 14 | add all error codes used in the library to `xxx.h`.
|
|---|
| 15 |
|
|---|
| 16 | Additionally the library include file must have a certain form.
|
|---|
| 17 | Typically it will initially look like this:
|
|---|
| 18 |
|
|---|
| 19 | #ifndef HEADER_XXX_H
|
|---|
| 20 | #define HEADER_XXX_H
|
|---|
| 21 |
|
|---|
| 22 | #ifdef __cplusplus
|
|---|
| 23 | extern "C" {
|
|---|
| 24 | #endif
|
|---|
| 25 |
|
|---|
| 26 | /* Include files */
|
|---|
| 27 |
|
|---|
| 28 | #include <openssl/bio.h>
|
|---|
| 29 | #include <openssl/x509.h>
|
|---|
| 30 |
|
|---|
| 31 | /* Macros, structures and function prototypes */
|
|---|
| 32 |
|
|---|
| 33 |
|
|---|
| 34 | /* BEGIN ERROR CODES */
|
|---|
| 35 |
|
|---|
| 36 | The `BEGIN ERROR CODES` sequence is used by the error code
|
|---|
| 37 | generation script as the point to place new error codes, any text
|
|---|
| 38 | after this point will be overwritten when make errors is run.
|
|---|
| 39 | The closing `#endif` etc will be automatically added by the script.
|
|---|
| 40 |
|
|---|
| 41 | The generated C error code file `xxx_err.c` will load the header
|
|---|
| 42 | files `stdio.h`, `openssl/err.h` and `openssl/xxx.h` so the
|
|---|
| 43 | header file must load any additional header files containing any
|
|---|
| 44 | definitions it uses.
|
|---|
| 45 |
|
|---|
| 46 | Adding new error codes
|
|---|
| 47 | ======================
|
|---|
| 48 |
|
|---|
| 49 | Instead of manually adding error codes into `crypto/err/openssl.txt`,
|
|---|
| 50 | it is recommended to leverage `make update` for error code generation.
|
|---|
| 51 | The target will process relevant sources and generate error codes for
|
|---|
| 52 | any *used* error codes.
|
|---|
| 53 |
|
|---|
| 54 | If an error code is added manually into `crypto/err/openssl.txt`,
|
|---|
| 55 | subsequent `make update` has no effect.
|
|---|
