2 # Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
4 # Licensed under the Apache License 2.0 (the "License"). You may not use
5 # this file except in compliance with the License. You can obtain a copy
6 # in the file LICENSE in the source distribution or at
7 # https://www.openssl.org/source/license.html
16 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
19 @EXPORT = qw(cmp_versions quotify1 quotify_l fixup_cmd_elements fixup_cmd
25 OpenSSL::Util - small OpenSSL utilities
31 $versiondiff = cmp_versions('1.0.2k', '3.0.1');
32 # $versiondiff should be -1
34 $versiondiff = cmp_versions('1.1.0', '1.0.2a');
35 # $versiondiff should be 1
37 $versiondiff = cmp_versions('1.1.1', '1.1.1');
38 # $versiondiff should be 0
44 =item B<cmp_versions "VERSION1", "VERSION2">
46 Compares VERSION1 with VERSION2, paying attention to OpenSSL versioning.
48 Returns 1 if VERSION1 is greater than VERSION2, 0 if they are equal, and
49 -1 if VERSION1 is less than VERSION2.
55 # Until we're rid of everything with the old version scheme,
56 # we need to be able to handle older style x.y.zl versions.
57 # In terms of comparison, the x.y.zl and the x.y.z schemes
58 # are compatible... mostly because the latter starts at a
59 # new major release with a new major number.
60 sub _ossl_versionsplit {
61 my $textversion = shift;
62 return $textversion if $textversion eq '*';
63 my ($major,$minor,$edit,$letter) =
64 $textversion =~ /^(\d+)\.(\d+)\.(\d+)([a-z]{0,2})$/;
66 return ($major,$minor,$edit,$letter);
70 my @a_split = _ossl_versionsplit(shift);
71 my @b_split = _ossl_versionsplit(shift);
75 # The last part is a letter sequence (or a '*')
76 if (scalar @a_split == 1) {
77 $verdict = $a_split[0] cmp $b_split[0];
79 $verdict = $a_split[0] <=> $b_split[0];
83 last unless $verdict == 0;
89 # It might be practical to quotify some strings and have them protected
90 # from possible harm. These functions primarily quote things that might
91 # be interpreted wrongly by a perl eval.
97 This adds quotes (") around the given string, and escapes any $, @, \,
98 " and ' by prepending a \ to them.
106 $s =~ s/([\$\@\\"'])/\\$1/g;
114 For each defined element in LIST (i.e. elements that aren't undef), have
115 it quotified with 'quotify1'.
116 Undefined elements are ignored.
132 =item fixup_cmd_elements LIST
134 Fixes up the command line elements given by LIST in a platform specific
137 The result of this function is a copy of LIST with strings where quotes and
138 escapes have been injected as necessary depending on the content of each
141 This can also be used to put quotes around the executable of a command.
142 I<This must never ever be done on VMS.>
148 sub fixup_cmd_elements {
149 # A formatter for the command arguments, defaulting to the Unix setup
152 ($_ eq '' || /\s|[\{\}\\\$\[\]\*\?\|\&:;<>]/) ? "'$_'" : $_ };
154 if ( $^O eq "VMS") { # VMS setup
155 $arg_formatter = sub {
157 if ($_ eq '' || /\s|[!"[:upper:]]/) {
164 } elsif ( $^O eq "MSWin32") { # MSWin setup
165 $arg_formatter = sub {
167 if ($_ eq '' || /\s|["\|\&\*\;<>]/) {
176 return ( map { $arg_formatter->($_) } @_ );
183 This is a sibling of fixup_cmd_elements() that expects the LIST to be a
184 complete command line. It does the same thing as fixup_cmd_elements(),
185 expect that it treats the first LIST element specially on VMS.
192 return fixup_cmd_elements(@_) unless $^O eq 'VMS';
194 # The rest is VMS specific
197 # Prefix to be applied as needed. Essentially, we need to determine
198 # if the command is an executable file (something.EXE), and invoke it
199 # with the MCR command in that case. MCR is an old PDP-11 command that
203 if ($cmd =~ m|^\@|) {
204 # The command is an invocation of a command procedure (also known as
205 # "script"), no modification needed.
207 } elsif ($cmd =~ m|^MCR$|) {
208 # The command is MCR, so there's nothing much to do apart from
209 # making sure that the file name following it isn't treated with
210 # fixup_cmd_elements(), 'cause MCR doesn't like strings.
214 # All that's left now is to check whether the command is an executable
215 # file, and if it's not, simply assume that it is a DCL command.
217 # Make sure we have a proper file name, i.e. add the default
218 # extension '.exe' if there isn't one already.
219 my $executable = ($cmd =~ m|.[a-z0-9\$]*$|) ? $cmd : $cmd . '.exe';
220 if (-e $executable) {
221 # It seems to be an executable, so we make sure to prefix it
222 # with MCR, for proper invocation. We also make sure that
223 # there's a directory specification, or otherwise, MCR will
224 # assume that the executable is in SYS$SYSTEM:
226 $cmd = '[]' . $cmd unless $cmd =~ /^(?:[\$a-z0-9_]+:)?[<\[]/i;
228 # If it isn't an executable, then we assume that it's a DCL
229 # command, and do no further processing, apart from argument
235 return ( @prefix, $cmd, fixup_cmd_elements(@_) );
238 =item dump_data REF, OPTS
240 Dump the data from REF into a string that can be evaluated into the same
243 OPTS is the rest of the arguments, expected to be pairs formed with C<< => >>.
244 The following OPTS keywords are understood:
248 =item B<delimiters =E<gt> 0 | 1>
250 Include the outer delimiter of the REF type in the resulting string if C<1>,
253 =item B<indent =E<gt> num>
255 The indentation of the caller, i.e. an initial value. If not given, there
256 will be no indentation at all, and the string will only be one line.
265 # indent => callers indentation ( undef for no indentation,
266 # an integer otherwise )
267 # delimiters => 1 if outer delimiters should be added
270 my $indent = $opts{indent} // 1;
271 # Indentation of the whole structure, where applicable
272 my $nlindent1 = defined $opts{indent} ? "\n" . ' ' x $indent : ' ';
273 # Indentation of individual items, where applicable
274 my $nlindent2 = defined $opts{indent} ? "\n" . ' ' x ($indent + 4) : ' ';
277 $subopts{delimiters} = 1;
278 $subopts{indent} = $opts{indent} + 4 if defined $opts{indent};
280 my $product; # Finished product, or reference to a function that
281 # produces a string, given $_
282 # The following are only used when $product is a function reference
283 my $delim_l; # Left delimiter of structure
284 my $delim_r; # Right delimiter of structure
285 my $separator; # Item separator
286 my @items; # Items to iterate over
288 if (ref($ref) eq "ARRAY") {
289 if (scalar @$ref == 0) {
290 $product = $opts{delimiters} ? '[]' : '';
293 dump_data(\$_, %subopts)
295 $delim_l = ($opts{delimiters} ? '[' : '').$nlindent2;
296 $delim_r = $nlindent1.($opts{delimiters} ? ']' : '');
297 $separator = ",$nlindent2";
300 } elsif (ref($ref) eq "HASH") {
301 if (scalar keys %$ref == 0) {
302 $product = $opts{delimiters} ? '{}' : '';
305 quotify1($_) . " => " . dump_data($ref->{$_}, %subopts);
307 $delim_l = ($opts{delimiters} ? '{' : '').$nlindent2;
308 $delim_r = $nlindent1.($opts{delimiters} ? '}' : '');
309 $separator = ",$nlindent2";
310 @items = sort keys %$ref;
312 } elsif (ref($ref) eq "SCALAR") {
313 $product = defined $$ref ? quotify1 $$ref : "undef";
315 $product = defined $ref ? quotify1 $ref : "undef";
318 if (ref($product) eq "CODE") {
319 $delim_l . join($separator, map { &$product } @items) . $delim_r;