/ 
Net-SSLeay-1.94
⭐ Starred 32 / update-exported-constants

NAME

update-exported-constants - Manage constants exported by Net::SSLeay

VERSION

This document describes version 1.94 of update-exported-constants.

USAGE

# Edit constants.txt to add or remove a libssl/libcrypto constant

# Export the new list of constants in Net::SSLeay, document them, and test
# for their availability in the test suite:
update-exported-constants

DESCRIPTION

Net::SSLeay exports a number of constants defined by libssl and libcrypto. Several time-consuming and error-prone steps must be performed whenever this set of constants changes: each one must be recognised as a valid constant name by Net::SSLeay's XS code, defined as an exportable symbol in Net::SSLeay's Perl code, documented in Net::SSLeay's user documentation, and tested in the Net::SSLeay test suite to ensure that referencing it either returns a defined value or raises an exception depending on whether it is defined in the version of OpenSSL or LibreSSL being used.

update-exported-constants simplifies the process of changing the set of exportable constants by automating it: it consumes a configuration file containing a list of constants, and performs each of the steps above for each of the constants listed in the file.

DEPENDENCIES

update-exported-constants requires Perl 5.8.1 or higher.

OPTIONS

update-exported-constants accepts the following command line options:

  • -C FILE, --config=FILE: the path to a file defining the libssl and libcrypto constants that Net::SSLeay should attempt to export. See "CONFIGURATION" for a description of the expected format. Defaults to constants.txt, relative to the path to update-exported-constants.

  • -c FILE, --constants-file=FILE: the path at which to write the C source file defining the constant function; this file should be included by SSLeay.xs. If a file exists at the given path, it will be overwritten. Defaults to ../constants.c, relative to the path to update-exported-constants.

  • -m FILE, --module-file=FILE: the path to Net::SSLeay's source code; the value of the @constants array defined in this file will be overwritten. Defaults to ../lib/Net/SSLeay.pm, relative to the path to update-exported-constants.

  • -p FILE, --pod-file=FILE: the path to et::SSLeay's documentation; the list of constants given in the "Constants" in Net::SSLeay section of this file will be overwritten. Defaults to ../lib/Net/SSLeay.pod, relative to the path to update-exported-constants.

  • -t FILE, --test-file=FILE: the path at which to write the constant autoloading test script. If a file exists at the given path, it will be overwritten. Defaults to ../t/local/21_constants.t, relative to the path to update-exported-constants.

The above defaults ensure that update-exported-constants can be executed from a directory containing the Net-SSLeay source code without needing to specify any options.

CONFIGURATION

The configuration file is a plain text file containing libssl and libcrypto constant names, one per line. Empty lines and lines beginning with # are ignored.

libssl and libcrypto constants are C preprocessor macro names. update-exported-constants checks that constant names given in the configuration file appear to be valid macro names, and will output a badly-formatted constant name; skipping warning on stderr whenever it encounters a line in the configuration file that does not appear to be a valid macro name. Since the set of valid constant names differs between versions of OpenSSL and LibreSSL, it is not possible to validate that constant names listed in the configuration file are in fact valid constant names for a particular libssl or libcrypto version.

OUTPUT

update-exported-constants generates the following files (overwriting any file that already exists at that path):

  • A C source file defining a function with the prototype static double constant(char*, size_t). For a given constant name and length, this function returns the value of the constant with the given name if it is recognised as exportable by Net::SSLeay and exists in libssl/libcrypto, returns 0 and sets errno to ENOENT if the constant is exportable but does not exist in libssl/libcrypto, or returns 0 and sets errno to EINVAL if the constant is not recognised as exportable by Net::SSLeay. This file is expected to be included by SSLeay.xs.

  • A Net::SSLeay test script that ensures each constant is exportable if it is defined, or raises a specific exception if it is not. This test script is expected to run as part of the standard Net::SSLeay test suite.

update-exported-constants updates the following files (which therefore must already exist and be writable):

  • The source file for the Net::SSLeay module - the value of the @constants array defined in this file is overwritten with the new list of constants that the module can export.

  • The Pod file documenting the Net::SSLeay module - the list of exportable constants given in the "Constants" in Net::SSLeay section of this file is overwritten with the new list of constants that the module can export.

DIAGNOSTICS

update-exported-constants outputs a diagnostic message to stderr and immediately exits with exit code 1 if an error occurs. Error messages listed below indicate invalid input or a problem with the state of the system that can usually be fixed. Error messages not listed below are internal and should never be encountered under normal operation; please report any occurrences of such errors as bugs (see "BUGS").

Failed to parse command line options: configuration file PATH does not exist

The configuration file listing the constants to export, as specified by the -C command line option (or constants.txt in the same directory as update-exported-constants if a value for -C was not specified), does not exist. Ensure constants.txt exists, or specify an alternative path with -C PATH.

Failed to parse command line options: Net::SSLeay module file PATH does not exist

update-exported-constants updates and overwrites the Net::SSLeay module file specified by the -m command line option (or ../lib/Net/SSLeay.pm relative to the path to update-exported-constants if a value for -m was not specified), but a file could not be found at this path. Ensure ../lib/Net/SSLeay.pm exists, or specify an alternative path with -m PATH.

Failed to parse command line options: Pod file PATH does not exist

update-exported-constants updates and overwrites the Pod file containing the Net::SSLeay documentation at the path specified by the -p command line option (or ../lib/Net/SSLeay.pod relative to the path to update-exported-constants if a value for -p was not specified), but a file could not be found at this path. Ensure ../lib/Net/SSLeay.pod exists, or specify an alternative path with -p PATH.

Failed to load configuration file: REASON

The configuration file could not be loaded because of REASON, which is probably an OS-level error. Ensure the path given by the -C option, or the default path if -C was not specified, is readable.

Failed to generate constants file: REASON

The constants C source file could not be written because of REASON, which is probably an OS-level error. Ensure that the path given by the -c option, or the default path if -c was not specified, is writable.

Failed to generate constants test script: REASON

The constants test script could not be written because of REASON, which is probably an OS-level error. Ensure that the path given by the -t option, or the default path if -t was not specified, is writable.

Failed to update Net::SSLeay module file: could not find @constants declaration

The Net::SSLeay module file was read, but an updated constants list could not be written to it because the definition of the @constants array could not be found. update-exported-constants expects this array to be defined with the following syntax:

my @constants = qw(
    # <Constants list>
);

Ensure the @constants array is defined in this way in the Net::SSLeay module.

Failed to update Net::SSLeay module file: REASON

The Net::SSLeay module file could not be either read or written because of REASON, which is probably an OS-level error. Ensure that the path given by the -m option, or the default path if -m was not specified, is both readable and writable.

Failed to update Pod file: could not find constants block

The Net::SSLeay documentation file was read, but an updated constants list could not be written to it because the Pod code block listing the constants could not be found. update-exported-constants expects this block to be surrounded by the following Pod commands:

=for start_constants

    <Constants list>

=for end_constants

Ensure the constants list is defined in this way in the documentation.

Failed to update Pod file: REASON

The Net::SSLeay documentation file could not be either read or written because of REASON, which is probably an OS-level error. Ensure that the path given by the -p option, or the default path if -p was not specified, is both readable and writable.

LIMITATIONS

Net::SSLeay currently returns the values of libssl and libcrypto constants as double-precision floating-point numbers, regardless of the data type of the underlying constant as it is defined by OpenSSL and/or LibreSSL; the C source file generated by update-exported-constants therefore defines a function constant with the return type double. While all constants currently exported by Net::SSLeay can be stored in this way without loss of precision, this may not necessarily be the case for all constants defined by libssl and libcrypto, either now or in the future.

SEE ALSO

The man pages for OpenSSL and LibreSSL, which describe the constants they define (and therefore the constants that may be exported by Net::SSLeay).

BUGS

If you encounter a problem with this program that you believe is a bug, please create a new issue in the Net-SSLeay GitHub repository. Please make sure your bug report includes the following information:

  • the list of command line options passed to update-exported-constants;

  • the full configuration file given by the -C command line option (or the default configuration file if -C was not specified);

  • the full output of update-exported-constants;

  • your operating system name and version;

  • the output of perl -V;

  • the version of Net-SSLeay you are using.

AUTHORS

Originally written by Chris Novakovic.

Maintained by Chris Novakovic and Heikki Vatiainen.

COPYRIGHT AND LICENSE

Copyright 2021- Chris Novakovic <chris@chrisn.me.uk>.

Copyright 2021- Heikki Vatiainen <hvn@radiatorsoftware.com>.

This module is released under the terms of the Artistic License 2.0. For details, see the LICENSE file distributed with Net-SSLeay's source code.