DOC: tpm2_unseal manpage complaints (PCR Policy Un/Sealing)

[SharkOverBite]

I had a go at sealing a secret using a PCR policy using command-line tpm2-tools. After piecing together some scattered references It wasn't too hard getting it working. The command sequence I ended up with (comments welcome) is:

Click to show

Example seals secret to current value of sha256:5 PCR

seal.sh

#!/bin/sh

# exit on error
set -e

# creatse secret
echo "Hello World!" > message

tpm2_createprimary -C o -g sha256 -G ecc -c primary_sh.ctx

# create pcr policy
tpm2_pcrread "sha256:5" -o pcr.bin
tpm2_startauthsession -S session.ctx
tpm2_policypcr -S session.ctx -l "sha256:5" -f pcr.bin -L pcr.policy
tpm2_flushcontext session.ctx

# create sealed blob
tpm2_create -C primary_sh.ctx -i message -u message.seal.pub -r message.seal.priv \
    -L pcr.policy -a "fixedtpm|fixedparent"

unseal.sh

#!/bin/sh

# exit on error
set -e

tpm2_createprimary -C o -g sha256 -G ecc -c primary_sh.ctx

tpm2_load -C primary_sh.ctx -u message.seal.pub -r message.seal.priv -c message.seal.ctx

# satisfy policy
tpm2_startauthsession --policy-session  -S session.ctx
tpm2_policypcr -S session.ctx -l "sha256:5" -f pcr.bin -L pcr.policy

# decrypt blob
tpm2_unseal -p session:session.ctx -c message.seal.ctx

The gripe I have, and what took a bit of googling to figure out was the last command

tpm2_unseal -p session:session.ctx -c message.seal.ctx

Here's what tpm2_unseal(1) says:

        -p, --auth=AUTH:

         Optional auth value to use for the key specified by -c.

        -S, --session=FILE:

         The session created using tpm2_startauthsession. 

<...>

   Sessions
       When  using  a  policy session to authorize the use of an object, prefix the option argument with the session
       keyword.  Then indicate a path to a session file that was created with tpm2_startauthsession(1).  Optionally,
       if the session requires an auth value to be sent with the session handle (eg policy password), then append  a
       + and a string as described in the Passwords section.

   Examples
       To use a session context file called session.ctx.

              session:session.ctx

Which raises several objections:

1. the object passed to -c is not "a key" as the description for -p suggests, but an encrypted blob.
2. I used tpm2_startauthsession to satisfy the PCR policy, so I naively assumed that to pass the policy to tpm2_unseal I should use -S session.ctx. Not so. Even though -p discusses auth and does not mention sessions, I'm supposed to somehow "just know" that session:session.ctx is the expected way to pass the policy session to this command.
3. The "Sessions" section (much lower in the manpage), once properly decrypted by the reader, tells you what you're supposed to do. But it is not explicit about what it's talking about (i.e. ".. to authorize the used of an object using -p"), nor is "the option argument" really explain this. In the example, why show "session:session.ctx" instead of the far clearer "-p session:session.ctx", that way, someone at least stand a chance of figuring out how to use the tool from the manpage, instead of frantically googling for an StackExchange question on the subject (which I had to do).