TPM2-Plugin/lib/include/tpm2_options.h

   1 /*
   2  * Copyright (c) 2016, Intel Corporation
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright notice,
   9  * this list of conditions and the following disclaimer.
  10  *
  11  * 2. Redistributions in binary form must reproduce the above copyright notice,
  12  * this list of conditions and the following disclaimer in the documentation
  13  * and/or other materials provided with the distribution.
  14  *
  15  * 3. Neither the name of Intel Corporation nor the names of its contributors
  16  * may be used to endorse or promote products derived from this software without
  17  * specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  23  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  29  * THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31 #ifndef OPTIONS_H
  32 #define OPTIONS_H
  33
  34 #include <stdbool.h>
  35 #include <stdint.h>
  36 #include <stdio.h>
  37
  38 #include <getopt.h>
  39
  40 #include <tss2/tss2_sys.h>
  41
  42 typedef union tpm2_option_flags tpm2_option_flags;
  43 union tpm2_option_flags {
  44     struct {
  45         UINT8 verbose : 1;
  46         UINT8 quiet   : 1;
  47         UINT8 enable_errata  : 1;
  48     };
  49     UINT8 all;
  50 };
  51
  52 /**
  53  * This function pointer defines the interface for tcti initialization.
  54  * ALL tool supported TCTIs should implement this interface.
  55  * @param opts
  56  *  An option string, that is defined by the tcti, and is passed
  57  *  via the --tcti= or -T options.
  58  *
  59  *  Anything following the : in the --tcti option is provides as opts.
  60  * @return
  61  *   NULL on error or an initialized TCTI.
  62  */
  63 typedef TSS2_TCTI_CONTEXT *(*tcti_init)(char *opts);
  64
  65 /**
  66  * Tools may implement this optional interface if they need
  67  * to handle options.
  68  * @param key
  69  *  The key of the option, ie short option return value from getopt_long().
  70  * @param value
  71  *  The getopt_long optarg value.
  72  * @return
  73  *  true on success, false on error.
  74  * @note
  75  *  LOG_INFO and TOOL_OUTPUT will not work correctly during this callback.
  76  *  This is called after onstart() finishes, but before
  77  *  onrun() is invoked.
  78  *
  79  */
  80 typedef bool (*tpm2_option_handler)(char key, char *value);
  81
  82 /**
  83  * Called after option handling to process arguments, if specified.
  84  * @param argc
  85  *  The number of args in argv.
  86  * @param argv
  87  *  The arguments.
  88  * @return
  89  *  true on success, false otherwise.
  90  * @note
  91  *  LOG_INFO adn TOOL_OUTPUT will not work correctly during this callback.
  92  *  This is called after onstart() and tpm2_option_handler() (if specified),
  93  *  but before onrun() is invoked.
  94  *
  95  */
  96 typedef bool (*tpm2_arg_handler)(int argc, char **argv);
  97
  98 /**
  99  * TPM2_OPTIONS_* flags change default behavior of the argument parser
 100  *
 101  * TPM2_OPTIONS_SHOW_USAGE:
 102  *  Enable printing a short usage summary (I.e. help)
 103  * TPM2_OPTIONS_NO_SAPI:
 104  *  Skip SAPI initialization. Removes the "-T" common option.
 105  */
 106 #define TPM2_OPTIONS_SHOW_USAGE 0x1
 107 #define TPM2_OPTIONS_NO_SAPI 0x2
 108
 109 struct tpm2_options {
 110     struct {
 111         tpm2_option_handler on_opt;
 112         tpm2_arg_handler on_arg;
 113     } callbacks;
 114     char *short_opts;
 115     size_t len;
 116     UINT32 flags;
 117     struct option long_opts[];
 118 };
 119
 120 typedef struct tpm2_options tpm2_options;
 121
 122 /**
 123  * The onstart() routine expects a return of NULL or a tpm2_options structure.
 124  * This routine initializes said object.
 125  * @param short_opts
 126  *  Any short options you wish to specify to getopt_long.
 127  * @param len
 128  *  The length of the long_opts array.
 129  * @param long_opts
 130  *  Any long options you wish to specify to getopt_long().
 131  * @param on_opt
 132  *  An option handling callback, which may be null if you don't wish
 133  *  to handle options.
 134  * @param on_arg
 135  *  An argument handling callback, which may be null if you don't wish
 136  *  to handle arguments.
 137  * @param flags
 138  *  TPM2_OPTIONS_* bit flags
 139  * @return
 140  *  NULL on failure or an initialized tpm2_options object.
 141  */
 142 tpm2_options *tpm2_options_new(const char *short_opts, size_t len,
 143         const struct option *long_opts, tpm2_option_handler on_opt,
 144         tpm2_arg_handler on_arg, UINT32 flags);
 145
 146 /**
 147  * Concatenates two tpm2_options objects, with src appended on
 148  * dest. The internal callbacks for tpm2_arg_handler and tpm2_option_handler
 149  * which were specified during tpm2_options_new() are copied from src to
 150  * dest, thus overwriting dest. Short and long options are concatenated.
 151  * @param dest
 152  *  The tpm2_options object to append to.
 153  * @param src
 154  *  The source tpm2_options to append onto dest.
 155  * @return
 156  *  true on success, false otherwise.
 157  */
 158 bool tpm2_options_cat(tpm2_options **dest, tpm2_options *src);
 159
 160 /**
 161  * Free's a tpm2_options created via tpm2_options_new().
 162  * @param opts
 163  *  The tpm2_options object to deallocate.
 164  */
 165 void tpm2_options_free(tpm2_options *opts);
 166
 167 typedef enum tpm2_option_code tpm2_option_code;
 168 enum tpm2_option_code {
 169     tpm2_option_code_continue,
 170     tpm2_option_code_stop,
 171     tpm2_option_code_err
 172 };
 173
 174 /**
 175  * Parses the tpm2_tool command line.
 176  *
 177  * @param argc
 178  *  The argc from main.
 179  * @param argv
 180  *  The argv from main.
 181  * @param tool_opts
 182  *  The tool options gathered during onstart() lifecycle call.
 183  * @param flags
 184  *  The tpm2_option_flags to set during parsing.
 185  * @param tcti
 186  *  The tcti initialized from the tcti options.
 187  * @return
 188  *  A tpm option code indicating if an error, further processing
 189  *  or an immediate exit is desired.
 190  * @note
 191  *  Used by tpm2_tool, and likely should only be used there.
 192  *
 193  */
 194 tpm2_option_code tpm2_handle_options (int argc, char **argv,
 195         tpm2_options *tool_opts, tpm2_option_flags *flags,
 196         TSS2_TCTI_CONTEXT **tcti);
 197
 198 /**
 199  * Print usage summary for a given tpm2 tool.
 200  *
 201  * @param command
 202  *  The command to print its usage summary text.
 203  * @param tool_opts
 204  *  The tpm2_options array that contains the tool options to print as a summary.
 205  */
 206 void tpm2_print_usage(const char *command, struct tpm2_options *tool_opts);
 207
 208 #endif /* OPTIONS_H */