Skip to contentSkip to conversation

docs: update trusted-encrypted.rst

PATCH RESEND Superseded Coly Li 4 participants 13 messages Aug 15, 2020 – Aug 19, 2020

Subsystems (4)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Coly Li

author
#0 lore raw

PATCH RESEND 1/1 docs: update trusted-encrypted.rst

The parameters in tmp2 commands are outdated, people are not able to create trusted key by the example commands.

This patch updates the paramerters of tpm2 commands, they are verified by tpm2-tools-4.1 with Linux v5.8 kernel.

Cc Dan Williams <[email protected]>
Cc James Bottomley <[email protected]>
Cc Jarkko Sakkinen <[email protected]>
Cc Mimi Zohar <[email protected]>
Cc Stefan Berger <[email protected]>
---
 Documentation/security/keys/trusted-encrypted.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/security/keys/trusted-encrypted.rst +4 -5
index 9483a7425ad5..442a2775156e 100644
@@ -39,10 +39,9 @@ With the IBM TSS 2 stack::
 
 Or with the Intel TSS 2 stack::
 
-  #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt
+  #> tpm2_createprimary --hierarchy o -G rsa2048 key.ctxt
   [...]
-  handle: 0x800000FF
-  #> tpm2_evictcontrol -c key.ctxt -p 0x81000001
+  #> tpm2_evictcontrol -c key.ctxt 0x81000001
   persistentHandle: 0x81000001
 
 Usage::
@@ -115,7 +114,7 @@ append 'keyhandle=0x81000001' to statements between quotes, such as
 
 ::
 
-    $ keyctl add trusted kmk "new 32" @u
+    $ keyctl add trusted kmk "new 32 keyhandle=0x81000001" @u
     440502848
 
     $ keyctl show
@@ -138,7 +137,7 @@ append 'keyhandle=0x81000001' to statements between quotes, such as
 
 Load a trusted key from the saved blob::
 
-    $ keyctl add trusted kmk "load `cat kmk.blob`" @u
+    $ keyctl add trusted kmk "load `cat kmk.blob` keyhandle=0x81000001" @u
     268728824
 
     $ keyctl print 268728824
Signature · 1 line
2.26.2
#1 lore raw
Quoted 21 lines · Coly Li

The parameters in tmp2 commands are outdated, people are not able to create trusted key by the example commands.

This patch updates the paramerters of tpm2 commands, they are verified by tpm2-tools-4.1 with Linux v5.8 kernel.

Cc Dan Williams <[email protected]>
Cc James Bottomley <[email protected]>
Cc Jarkko Sakkinen <[email protected]>
Cc Mimi Zohar <[email protected]>
Cc Stefan Berger <[email protected]>
---
  Documentation/security/keys/trusted-encrypted.rst | 9 ++++-----
  1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/security/keys/trusted-encrypted.rst +0 -0
index 9483a7425ad5..442a2775156e 100644

Documentation/security/keys/trusted-encrypted.rst With the IBM TSS 2 stack:: · line 44

Quoted 7 lines
Documentation/security/keys/trusted-encrypted.rst +1 -2
@@ -39,10 +39,9 @@ With the IBM TSS 2 stack::
 
  Or with the Intel TSS 2 stack::
 
-  #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt
+  #> tpm2_createprimary --hierarchy o -G rsa2048 key.ctxt
[...]
-  handle: 0x800000FF

Are you sure about this? My documentation for 4.1.3 on F32 states

-c, --key-context=FILE:

         The file path to save the object context of the generated
primary object.

Documentation/security/keys/trusted-encrypted.rst With the IBM TSS 2 stack:: · line 45

Quoted 3 lines
Documentation/security/keys/trusted-encrypted.rst +1 -1
-  #> tpm2_evictcontrol -c key.ctxt -p 0x81000001
+  #> tpm2_evictcontrol -c key.ctxt 0x81000001
    persistentHandle: 0x81000001

This seems correct.

Documentation/security/keys/trusted-encrypted.rst append 'keyhandle=0x81000001' to statements between quotes, such as

Quoted 3 lines

Usage::

Documentation/security/keys/trusted-encrypted.rst +0 -0
@@ -115,7 +114,7 @@ append 'keyhandle=0x81000001' to statements between quotes, such as

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 17 lines
Documentation/security/keys/trusted-encrypted.rst +2 -2
  ::
 
-    $ keyctl add trusted kmk "new 32" @u
+    $ keyctl add trusted kmk "new 32 keyhandle=0x81000001" @u
      440502848
 
      $ keyctl show
@@ -138,7 +137,7 @@ append 'keyhandle=0x81000001' to statements between quotes, such as
 
  Load a trusted key from the saved blob::
 
-    $ keyctl add trusted kmk "load `cat kmk.blob`" @u
+    $ keyctl add trusted kmk "load `cat kmk.blob` keyhandle=0x81000001" @u
      268728824
 
      $ keyctl print 268728824
#2 lore raw

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 10 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

James

author
#3 lore raw
Quoted 13 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 10 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 5 lines

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Hi James,

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Thanks.

Coly Li

#4 lore raw
Quoted 19 lines · Coly Li
Quoted 12 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 9 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 5 lines

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Quoted 4 lines

Hi James,

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Well, as I said above it depends on not yet upstream precursor patches.
They have been pending for about a year, so I've no real idea of the
timeline.

James

author
#5 lore raw
Quoted 20 lines · James Bottomley
Quoted 19 lines · Coly Li
Quoted 17 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 9 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Quoted 8 lines
Quoted 4 lines

Hi James,

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Well, as I said above it depends on not yet upstream precursor patches.
They have been pending for about a year, so I've no real idea of the
timeline.

I see. Then I will post a v2 patch only does the s/-o/-c fix, and leave others untouched.

Thanks.

Coly Li

#6 lore raw
In reply to James Bottomley
Quoted 22 lines · James Bottomley
Quoted 21 lines · Coly Li
Quoted 12 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 9 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 5 lines

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Hi James,

Quoted 8 lines
Quoted 2 lines

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Well, as I said above it depends on not yet upstream precursor patches.
They have been pending for about a year, so I've no real idea of the
timeline.

James

As far as I remember there was not much left in the previous version to do. Some time has passed when it was discussed but I recall it was mainly about documenting the key format.

/Jarkko

#7 lore raw
Quoted 31 lines · Jarkko Sakkinen
Quoted 30 lines · James Bottomley
Quoted 20 lines · Coly Li
Quoted 12 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 9 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 6 lines

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Quoted 4 lines

Hi James,

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Well, as I said above it depends on not yet upstream precursor patches. They have been pending for about a year, so I've no real idea of the timeline.

Quoted 5 lines
Quoted 1 line

James

As far as I remember there was not much left in the previous version to do. Some time has passed when it was discussed but I recall it was mainly about documenting the key format.

Actually, no, unfortunately it's not in that update. Generating an on- the-fly primary would involve the cryptographic security patch (same mechanism as used to generate the null primary). I was thinking I'd extract just that piece and use it in a follow on. So both the rework of the key format and this extra patch that's not yet even broken out of the TPM security series are required precursors.

James

#8 lore raw
Quoted 38 lines · James Bottomley
Quoted 31 lines · Jarkko Sakkinen
Quoted 30 lines · James Bottomley
Quoted 20 lines · Coly Li
Quoted 12 lines · James Bottomley

On Sun, 2020-08-16 at 12:06 -0400, Stefan Berger wrote:
[...]

Quoted 9 lines

A note in this file states this:

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 6 lines

Actually, I also have a plan to match what userspace does and simply assume a keyhandle of 40000001 (generate an EC Storage Primary Key on the fly) if it's not specified, which will make the TPM1.2 and 2.0 versions of this the same. Unfortunately the necessary precursor patches are taking an age to get upstream.

Quoted 4 lines

Hi James,

Do you have a plan to push such patches into upstream soon? If yes than I may wait for your patch and withdraw this one.

Well, as I said above it depends on not yet upstream precursor patches. They have been pending for about a year, so I've no real idea of the timeline.

Quoted 5 lines
Quoted 1 line

James

As far as I remember there was not much left in the previous version to do. Some time has passed when it was discussed but I recall it was mainly about documenting the key format.

Quoted 8 lines

Actually, no, unfortunately it's not in that update. Generating an on- the-fly primary would involve the cryptographic security patch (same mechanism as used to generate the null primary). I was thinking I'd extract just that piece and use it in a follow on. So both the rework of the key format and this extra patch that's not yet even broken out of the TPM security series are required precursors.

James

OK, sorry I mixed up thinks. Thanks.

/Jarkko

author
#9 lore raw
In reply to Stefan Berger
Quoted 33 lines · Stefan Berger
Quoted 22 lines · Coly Li

The parameters in tmp2 commands are outdated, people are not able to create trusted key by the example commands.

This patch updates the paramerters of tpm2 commands, they are verified by tpm2-tools-4.1 with Linux v5.8 kernel.

Cc Dan Williams <[email protected]>
Cc James Bottomley <[email protected]>
Cc Jarkko Sakkinen <[email protected]>
Cc Mimi Zohar <[email protected]>
Cc Stefan Berger <[email protected]>

---
  Documentation/security/keys/trusted-encrypted.rst | 9 ++++-----

  1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/security/keys/trusted-encrypted.rst +0 -0
index 9483a7425ad5..442a2775156e 100644
@@ -39,10 +39,9 @@ With the IBM TSS 2 stack::
Quoted 5 lines

    Or with the Intel TSS 2 stack::
  -  #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt +  #> tpm2_createprimary --hierarchy o -G rsa2048 key.ctxt [...]
-  handle: 0x800000FF

Are you sure about this? My documentation for 4.1.3 on F32 states

Quoted 6 lines

-c, --key-context=FILE:

         The file path to save the object context of the generated primary object.

Yes of course you are right, it is s/-o/-c

Quoted 16 lines
Quoted 4 lines

-  #> tpm2_evictcontrol -c key.ctxt -p 0x81000001
+  #> tpm2_evictcontrol -c key.ctxt 0x81000001
    persistentHandle: 0x81000001

This seems correct.

Quoted 3 lines

    Usage::

Documentation/security/keys/trusted-encrypted.rst +0 -0
@@ -115,7 +114,7 @@ append 'keyhandle=0x81000001' to statements

between quotes, such as

A note in this file states this:

Quoted 9 lines

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

I agree. Indeed I have no idea why number 0x81000001 is used, and I don't have practice experience with TPM 1.2. Now the purpose of this patch accomplished: experts response and confirm my guess :-)

Thanks.

Quoted 5 lines
Quoted 5 lines

    ::
  -    $ keyctl add trusted kmk "new 32" @u
+    $ keyctl add trusted kmk "new 32 keyhandle=0x81000001" @u 440502848

        $ keyctl show
Quoted 10 lines
Quoted 8 lines
Documentation/security/keys/trusted-encrypted.rst +0 -0
@@ -138,7 +137,7 @@ append 'keyhandle=0x81000001' to statements

between quotes, such as
    Load a trusted key from the saved blob::
  -    $ keyctl add trusted kmk "load cat kmk.blob" @u +    $ keyctl add trusted kmk "load cat kmk.blob keyhandle=0x81000001" @u
      268728824

        $ keyctl print 268728824

Coly Li

#10 lore raw
Quoted 2 lines · Coly Li
Quoted 1 line · Stefan Berger

On 8/15/20 3:51 AM, Coly Li wrote:

[...]

Quoted 17 lines
Quoted 7 lines
Quoted 3 lines
    Usage::
(quoted diff) +0 -0
@@ -115,7 +114,7 @@ append 'keyhandle=0x81000001' to statements

between quotes, such as

A note in this file states this:

Quoted 9 lines

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 3 lines

I agree. Indeed I have no idea why number 0x81000001 is used, and I don't have practice experience with TPM 1.2. Now the purpose of this patch accomplished: experts response and confirm my guess :-)

It was the conventional persistent value for the RSA 2048 version of the primary storage seed. Originally the PC spec required the manufacturer provision this on all TPM 2.0 based PC class systems. Unfortunately in spite of it being in the Windows Hardware guide no manufacturer ever did, meaning you either have to create it yourself or do something different. Because of usability problems, every consumer of TPM key function has opted to do something different, namely derive the EC primary if no parent is specified.

James

author
#11 lore raw
Quoted 25 lines · James Bottomley
Quoted 2 lines · Coly Li
Quoted 1 line · Stefan Berger

On 8/15/20 3:51 AM, Coly Li wrote:

[...]

Quoted 17 lines
Quoted 7 lines
Quoted 3 lines
    Usage::
(quoted diff) +0 -0
@@ -115,7 +114,7 @@ append 'keyhandle=0x81000001' to statements

between quotes, such as

A note in this file states this:

Quoted 9 lines

Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".

Now if someone was (still) interested in TPM 1.2 then the below changes you are proposing wouldn't work for them. Maybe you should adapt the note to state that these keyhandle=... should be removed for the TPM 1.2 case.

Quoted 3 lines

I agree. Indeed I have no idea why number 0x81000001 is used, and I don't have practice experience with TPM 1.2. Now the purpose of this patch accomplished: experts response and confirm my guess :-)

Quoted 8 lines

It was the conventional persistent value for the RSA 2048 version of the primary storage seed. Originally the PC spec required the manufacturer provision this on all TPM 2.0 based PC class systems. Unfortunately in spite of it being in the Windows Hardware guide no manufacturer ever did, meaning you either have to create it yourself or do something different. Because of usability problems, every consumer of TPM key function has opted to do something different, namely derive the EC primary if no parent is specified.

Aha, thanks for the hint :-)

My motivation is for the NVDIMM security with TPM 2.0 chip on x86 server (Lenovo SR650). To automatically load a trusted key, I encounter the outdated command line in trusted-encrypted.rst. From your response, it seems 0x81000001 is still a working value that I can recommend to other people who want to encrypt/decrypt their NVDIMM banks.

Coly Li

author
#12 lore raw
In reply to Stefan Berger
Quoted 33 lines · Stefan Berger
Quoted 22 lines · Coly Li

The parameters in tmp2 commands are outdated, people are not able to create trusted key by the example commands.

This patch updates the paramerters of tpm2 commands, they are verified by tpm2-tools-4.1 with Linux v5.8 kernel.

Cc Dan Williams <[email protected]>
Cc James Bottomley <[email protected]>
Cc Jarkko Sakkinen <[email protected]>
Cc Mimi Zohar <[email protected]>
Cc Stefan Berger <[email protected]>

---
  Documentation/security/keys/trusted-encrypted.rst | 9 ++++-----

  1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/security/keys/trusted-encrypted.rst +0 -0
index 9483a7425ad5..442a2775156e 100644
@@ -39,10 +39,9 @@ With the IBM TSS 2 stack::
Quoted 5 lines

    Or with the Intel TSS 2 stack::
  -  #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt +  #> tpm2_createprimary --hierarchy o -G rsa2048 key.ctxt [...]
-  handle: 0x800000FF

Are you sure about this? My documentation for 4.1.3 on F32 states

Quoted 5 lines

-c, --key-context=FILE:

         The file path to save the object context of the generated primary object.

BTW, where can I get the document you mentioned for "4.1.3 on F32 states" ? I only have a pdf file "A practical Guide to TPM 2.0" which does not have 4.1.3

Thanks.

Coly Li