update docs

Signed-off-by: sal rashid <[email protected]>

Author: salrashid123

README.md

@@ -2,7 +2,7 @@
 
 where private keys as embedded inside `Trusted Platform Module (TPM)`
 
-Basically, you will get a [crypto.Signer](https://pkg.go.dev/crypto#Signer) interface for the private key..  
+Basically, you will get a [crypto.Signer](https://pkg.go.dev/crypto#Signer) interface for the private key. 
 
 Use the signer to create a TLS session, sign CA/CSRs, or just sign anything.
 
@@ -54,87 +54,13 @@ import (
 
 ### Sign/Verify
 
-see `example/sign_verify_tpm` folder and the Example Setup section below
+see `example/sign_verify_tpm` folder.
 
-### Usage TLS
-
-* for tpm see [mTLS with TPM bound private key](https://github.com/salrashid123/go_tpm_https_embed)
-
-### Sign/Verify ECC
-
-The default output signature format for ECC based keys is ASN1 format as described in [ecdsa.SignASN1](https://pkg.go.dev/crypto/ecdsa#Sign)
-
-If you need the raw output format, set `ECCRawOutput:  true` in the config.
-
-See the examples folder for usage
-
-### Usage: Generate CSR
-
-The following will generate a TPM based key and then issue a CSR against it.
-
-```bash
-### create key, rsassa
- # using H2 template ( https://gist.github.com/salrashid123/9822b151ebb66f4083c5f71fd4cdbe40 )
-printf '\x00\x00' > unique.dat
-tpm2_createprimary -C o -G ecc  -g sha256 \
-   -c primary.ctx -a "fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda|restricted|decrypt" -u unique.dat
-   
- tpm2_create -G rsa2048:rsassa:null -g sha256 -u key.pub -r key.priv -C primary.ctx
- tpm2_flushcontext -t
- tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
- tpm2_evictcontrol -C o -c key.ctx 0x81008001
- tpm2_flushcontext -t
- tpm2_encodeobject -C primary.ctx -u key.pub -r key.priv -o private.pem
-
-cd util/csrgen/
-go run csrgen/csrgen.go -cn server.domain.com  --persistentHandle 0x81008001
-```
+To use this, the key must be first created on the TPM and accessed as a PersistentHandle or TPM PEM file
 
-### Usage: Generate self-signed certificate
-
-The following will generate a key on the tpm, then use that RSA key to issue a CSR and then sign that CSR with by itself to get an x509.
-
-You can ofcourse modify it to just sign any csr with a TPM backed key
+You can create these keys using `go-tpm` or using  `tpm2_tools`.  The example below uses tpm2_tools but for others languages and standalone applicatoins, see [openssl tpm2 provider](https://github.com/salrashid123/tpm2?tab=readme-ov-file#tpm-based-private-key) or [tpm2genkey](https://github.com/salrashid123/tpm2genkey)
 
-
-```bash
- # using H2 template ( https://gist.github.com/salrashid123/9822b151ebb66f4083c5f71fd4cdbe40 )
-printf '\x00\x00' > unique.dat
-tpm2_createprimary -C o -G ecc  -g sha256 \
-   -c primary.ctx -a "fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda|restricted|decrypt" -u unique.dat
-
- tpm2_create -G rsa2048:rsassa:null -g sha256 -u key.pub -r key.priv -C primary.ctx
- tpm2_flushcontext -t
- tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
- tpm2_evictcontrol -C o -c key.ctx 0x81008002
- tpm2_flushcontext -t
- tpm2_encodeobject -C primary.ctx -u key.pub -r key.priv -o private.pem
-
-go run certgen/certgen.go -cn server.domain.com --persistentHandle 0x81008002
-```
-
----
-
-If you just want to issue JWT's, see
-
-* [https://github.com/salrashid123/golang-jwt-tpm](https://github.com/salrashid123/golang-jwt-tpm)
-* [https://github.com/salrashid123/golang-jwt-pkcs11](https://github.com/salrashid123/golang-jwt-pkcs11)
-
-or real random:
-
-* [TPM backed crypto/rand Reader](https://github.com/salrashid123/tpmrand)
-
----
-
-### Example Setup - TPM
-
-
-example usage generates a new TPM unrestricted RSA key and sign,verify some data.
-
-
-You can create the persistent handles using go-tpm or using  `tpm2_tools` and make it persistent, 
-
-First install latest [tpm2_tools](https://tpm2-tools.readthedocs.io/en/latest/INSTALL/)
+For this, install latest [tpm2_tools](https://tpm2-tools.readthedocs.io/en/latest/INSTALL/) 
 
 ```bash
 cd example/
@@ -147,11 +73,12 @@ cd example/
 ## and for tpm2_tools, export the following var
 # export TPM2TOOLS_TCTI="swtpm:port=2321"
 
-## note if you want, the primary can be the "H2" profile from https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html#name-parent
+## if you are using a real tpm set --tpm-path=/dev/tpmrm0
+
+## note the primary can be the "H2" profile from https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html#name-parent
 # printf '\x00\x00' > unique.dat
 # tpm2_createprimary -C o -G ecc  -g sha256  -c primary.ctx -a "fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda|restricted|decrypt" -u unique.dat
 
-
 ## RSA - no password
 
 	tpm2_createprimary -C o -G rsa2048:aes128cfb -g sha256 -c primary.ctx -a 'restricted|decrypt|fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda'
@@ -208,39 +135,132 @@ go run sign_verify_tpm/ecc/main.go --tpm-path="127.0.0.1:2321" --handle 0x810080
 	tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
 	tpm2_evictcontrol -C o -c key.ctx 0x81008006
 
+go run sign_verify_tpm/policy_pcr/main.go --handle=0x81008006 --tpm-path="127.0.0.1:2321"
+
 ## for policyPassword
 
 	tpm2_createprimary -C o  -G rsa2048:aes128cfb -g sha256  -c primary.ctx -a 'restricted|decrypt|fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda'
 	tpm2_create -G rsa2048:rsassa:null -p testpwd -g sha256 -u key.pub -r key.priv -C primary.ctx 
 	tpm2_flushcontext -t && tpm2_flushcontext -s && tpm2_flushcontext -l
 	tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx 
 	tpm2_evictcontrol -C o -c key.ctx 0x81008007
-    
-## ===== 
 
-tpm2_flushcontext -t && tpm2_flushcontext -s && tpm2_flushcontext -l
+go run sign_verify_tpm/policy_password/main.go --handle=0x81008007 --tpm-path="127.0.0.1:2321"
 
-cd example/
+```
 
-## RSA-SSA managed externally
-go run sign_verify_tpm/rsassa/main.go --handle=0x81008001 --tpm-path="127.0.0.1:2321"
 
-## RSA with PEM KeyFile
-go run sign_verify_tpm/keyfile/main.go --pemFile=/path/to/key.pem --tpm-path="127.0.0.1:2321"
+### Usage TLS
 
-## RSA-PSS
-go run sign_verify_tpm/rsapss/main.go --handle=0x81008004 --tpm-path="127.0.0.1:2321"
+* for tpm see [mTLS with TPM bound private key](https://github.com/salrashid123/go_tpm_https_embed)
 
-## ECC
-go run sign_verify_tpm/ecc/main.go --handle=0x81008005 --tpm-path="127.0.0.1:2321"
+### Sign/Verify ECC
 
-## RSA with pcr policy
-go run sign_verify_tpm/policy_pcr/main.go --handle=0x81008006 --tpm-path="127.0.0.1:2321"
+The default output signature format for ECC based keys is ASN1 format as described in [ecdsa.SignASN1](https://pkg.go.dev/crypto/ecdsa#Sign)
 
-## RSA with password policy
-go run sign_verify_tpm/policy_password/main.go --handle=0x81008007 --tpm-path="127.0.0.1:2321"
+If you need the raw output format, set `ECCRawOutput:  true` in the config.
+
+See the examples folder for usage
+
+### Usage: Generate CSR
+
+The following will generate a TPM based key and then issue a CSR against it.
+
+```bash
+### create key, rsassa
+ # using H2 template ( https://gist.github.com/salrashid123/9822b151ebb66f4083c5f71fd4cdbe40 )
+printf '\x00\x00' > unique.dat
+tpm2_createprimary -C o -G ecc  -g sha256 \
+   -c primary.ctx -a "fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda|restricted|decrypt" -u unique.dat
+   
+ tpm2_create -G rsa2048:rsassa:null -g sha256 -u key.pub -r key.priv -C primary.ctx
+ tpm2_flushcontext -t
+ tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
+ tpm2_evictcontrol -C o -c key.ctx 0x81008001
+ tpm2_flushcontext -t
+ tpm2_encodeobject -C primary.ctx -u key.pub -r key.priv -o private.pem
+
+cd util/csrgen/
+go run csrgen/csrgen.go -cn server.domain.com  --persistentHandle 0x81008001
 ```
 
+### Usage: Generate self-signed certificate
+
+The following will generate a key on the tpm, then use that RSA key to issue a CSR and then sign that CSR with by itself to get an x509.
+
+You can ofcourse modify it to just sign any csr with a TPM backed key
+
+
+```bash
+ # using H2 template ( https://gist.github.com/salrashid123/9822b151ebb66f4083c5f71fd4cdbe40 )
+printf '\x00\x00' > unique.dat
+tpm2_createprimary -C o -G ecc  -g sha256 \
+   -c primary.ctx -a "fixedtpm|fixedparent|sensitivedataorigin|userwithauth|noda|restricted|decrypt" -u unique.dat
+
+ tpm2_create -G rsa2048:rsassa:null -g sha256 -u key.pub -r key.priv -C primary.ctx
+ tpm2_flushcontext -t
+ tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
+ tpm2_evictcontrol -C o -c key.ctx 0x81008002
+ tpm2_flushcontext -t
+ tpm2_encodeobject -C primary.ctx -u key.pub -r key.priv -o private.pem
+
+go run certgen/certgen.go -cn server.domain.com --persistentHandle 0x81008002
+```
+
+---
+
+If you just want to issue JWT's, see
+
+* [https://github.com/salrashid123/golang-jwt-tpm](https://github.com/salrashid123/golang-jwt-tpm)
+* [https://github.com/salrashid123/golang-jwt-pkcs11](https://github.com/salrashid123/golang-jwt-pkcs11)
+
+or real random:
+
+* [TPM backed crypto/rand Reader](https://github.com/salrashid123/tpmrand)
+
+---
+
+#### Keys with Auth Policy
+
+If the key is setup with an AuthPolicy (eg, a policy that requires a passphrase or a predefined PCR values to exist), you can specify those in code or define your own
+
+
+##### PasswordPolicy
+
+If the key requires a password, initialize a `NewPasswordSession`
+
+```golang
+	se, err := saltpm.NewPasswordSession(rwr, []byte(*keyPass))
+
+	rr, err := saltpm.NewTPMCrypto(&saltpm.TPM{
+		TpmDevice:   rwc,
+		Handle:      tpm2.TPMHandle(*handle),
+		AuthSession: se,
+	})
+```
+
+##### PCRPolicy
+
+If the key requires a password, initialize a `NewPCRSession`
+
+```golang
+	se, err := saltpm.NewPCRSession(rwr, []tpm2.TPMSPCRSelection{
+		{
+			Hash:      tpm2.TPMAlgSHA256,
+			PCRSelect: tpm2.PCClientCompatible.PCRs(uint(*pcr)),
+		},
+	})
+
+	rr, err := saltpm.NewTPMCrypto(&saltpm.TPM{
+		TpmDevice:   rwc,
+		Handle:      tpm2.TPMHandle(*handle),
+		AuthSession: se,
+	})
+
+```
+
+##### CustomPolicy
+
 Note, you can define your own policy for import too...just implement the "session" interface from the signer:
 
 ```golang