Command line pskctool: PSKC Library (libpskc) Manual

## Command line pskctool

To simplify working with PSKC data a command line tool is also provided, called "pskctool". When invoked without parameters, it will print some instructions describing what it does and the parameters it accepts.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    Usage: pskctool [OPTION]... [FILE]...
    Manipulate Portable Symmetric Key Container (PSKC) data.

    This tool allows you to parse, print, validate, sign and verify PSKC data.  The
    input is provided in FILE or on standard input.

      -h, --help             Print help and exit
      -V, --version          Print version and exit
          --strict           Fail hard on PSKC parse error  (default=off)
      -d, --debug            Show debug messages on stderr  (default=off)
      -q, --quiet            Quiet operation  (default=off)
      -v, --verbose          Produce more output  (default=off)

    Selecting one of the following modes is required:

     Mode: info
      -i, --info             Parse and print human readable summary of PSKC input
                               (default=off)

     Mode: validate
      -e, --validate         Validate PSKC input against XML Schema  (default=off)

     Mode: sign
      Digitally sign PSKC data
          --sign             Sign PSKC input  (default=off)
          --sign-key=FILE    Private key to sign with
          --sign-crt=FILE    X.509 certificate to sign with

     Mode: verify
      Verify digitally signed PSKC data
          --verify           Verify signed PSKC input  (default=off)
          --verify-crt=FILE  Trusted X.509 certificate for verification

    Report bugs to: oath-toolkit-help@nongnu.org
    pskctool home page: <https://www.nongnu.org/oath-toolkit/>
    General help using GNU software: <https://www.gnu.org/gethelp/>

As you can see, the pskctool have a few different modes: info, validate, sign and verify. We describe each of them in the next few sections.

## Parse and print summary of PSKC data

The most common parameter to use is --info (-i) to parse and print a human readable summary of PSKC data. This step is also known as "pretty printing" the PSKC data. A filename can be supplied to have the tool read PSKC data from that file, or if no filename is supplied, the tool will read from standard input. To illustrate how the tool works, we will assume the following PSKC data is available in a file "pskc.xml".

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    <?xml version="1.0" encoding="UTF-8"?>
    <KeyContainer Version="1.0"
    	      xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
      <KeyPackage>
        <DeviceInfo>
          <Manufacturer>Manufacturer</Manufacturer>
          <SerialNo>987654321</SerialNo>
        </DeviceInfo>
        <Key Id="12345678"
             Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
          <AlgorithmParameters>
            <ResponseFormat Length="8" Encoding="DECIMAL"/>
          </AlgorithmParameters>
          <Data>
            <Secret>
              <PlainValue>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
              </PlainValue>
            </Secret>
            <Counter>
              <PlainValue>0</PlainValue>
            </Counter>
          </Data>
        </Key>
      </KeyPackage>
    </KeyContainer>

Running the tool with the --info parameter, i.e., "pskctool --info pskc.xml" will produce a human readable variant of the PSKC data.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    Portable Symmetric Key Container (PSKC):
    	Version: 1.0
    	Signed: NO
    	KeyPackage 0:
    		DeviceInfo:
    			Manufacturer: Manufacturer
    			SerialNo: 987654321
    		Key:
    			Id: 12345678
    			Algorithm: urn:ietf:params:xml:ns:keyprov:pskc:hotp
    			Key Secret (base64): MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
    			Key Counter: 0
    			Response Format Length: 8
    			Response Format Encoding: DECIMAL

If the --verbose (-v) parameter is given, the tool will also print an indented version of the XML structure. Note that this will invalidate any digital signatures on the PSKC data. Thus, this is normally only useful to simplify human reading of the XML code of an PSKC file. The output will also contain the human readable summary, but you may use --quiet (-q) to suppress that part. Together, the combination of --verbose and --quiet can be used in batch jobs to indent PSKC data (but beware that this breaks any signatures).

In some situations when using pskctool --info the tool may print a warning about unsupported elements. The --debug parameter can be used in these situations to get more information about the source of the problem. For example, running "pskctool --info --debug --quiet" on the data in figure 6 of RFC 6030 will currently yield the following output on stderr.

    1
    2
    3
    4
    5
    6
    debug: unknown <KeyContainer> element <EncryptionKey>
    debug: unknown <KeyContainer> element <MACMethod>
    debug: non-compliant Manufacturer value: Manufacturer
    debug: unknown <Secret> element <EncryptedValue>
    debug: unknown <Secret> element <ValueMAC>
    warning: parse error (use -d to diagnose), output may be incomplete

Even when noticing a problem, the tool continue with the parsing and will eventually print the information it managed to parse. In some situations (e.g., batch jobs) you would prefer the tool to signal this error. The --strict parameter can be used to make the tool fail when there is a parse error.