feat: refactor encrypt and decrypt + CLI examples (#418)

- Refactor encrypt and decrypt
- Docs
  - Encrypt, Decrypt
  - Auth

---------

Co-authored-by: Jake Van Vorhis <[email protected]>

Author: jrschumacher

.github/spellcheck.ignore

@@ -22,6 +22,7 @@ NPM
 Namespace
 namespace's
 Nano
+NanoTDF
 OIDC
 OpenTDF
 OpenID
@@ -108,8 +109,11 @@ uri
 with-client-creds
 with-client-creds-file
 yaml
+ZTDF
+ztdf
 tdo
 appliesToState
 stanag
 nato
-ocl
+ocl
+cryptographically

cmd/tdf-decrypt.go

@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"bytes"
 	"errors"
 	"fmt"
 	"os"
@@ -14,16 +13,12 @@ import (
 var TDF = "tdf"
 
 func dev_tdfDecryptCmd(cmd *cobra.Command, args []string) {
-	c := cli.New(cmd, args)
+	c := cli.New(cmd, args, cli.WithPrintJson())
 	h := NewHandler(c)
 	defer h.Close()
 
 	output := c.Flags.GetOptionalString("out")
-	tdfType := c.Flags.GetOptionalString("tdf-type")
 	disableAssertionVerification := c.Flags.GetOptionalBool("no-verify-assertions")
-	if tdfType == "" {
-		tdfType = TDF3
-	}
 
 	// check for piped input
 	piped := readPipedStdin()
@@ -40,16 +35,7 @@ func dev_tdfDecryptCmd(cmd *cobra.Command, args []string) {
 		cli.ExitWithError("Must provide ONE of the following to decrypt: [file argument, stdin input]", errors.New("no input provided"))
 	}
 
-	var decrypted *bytes.Buffer
-	var err error
-	switch tdfType {
-	case TDF3:
-		decrypted, err = h.DecryptTDF(bytesToDecrypt, disableAssertionVerification)
-	case NANO:
-		decrypted, err = h.DecryptNanoTDF(bytesToDecrypt)
-	default:
-		cli.ExitWithError("Failed to decrypt", fmt.Errorf("unrecognized tdf-type: %s", tdfType))
-	}
+	decrypted, err := h.DecryptBytes(bytesToDecrypt, disableAssertionVerification)
 	if err != nil {
 		cli.ExitWithError("Failed to decrypt file", err)
 	}
@@ -81,6 +67,7 @@ func init() {
 		decryptCmd.GetDocFlag("out").Default,
 		decryptCmd.GetDocFlag("out").Description,
 	)
+	// deprecated flag
 	decryptCmd.Flags().StringP(
 		decryptCmd.GetDocFlag("tdf-type").Name,
 		decryptCmd.GetDocFlag("tdf-type").Shorthand,

cmd/tdf-encrypt.go

@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"bytes"
 	"fmt"
 	"io"
 	"log/slog"
@@ -16,16 +15,17 @@ import (
 )
 
 const (
-	TDF3     = "tdf3"
-	NANO     = "nano"
-	Size_1MB = 1024 * 1024
+	TDFTYPE_ZTDF = "ztdf"
+	TDF3         = "tdf3"
+	NANO         = "nano"
+	Size_1MB     = 1024 * 1024
 )
 
 var attrValues []string
 var assertions string
 
 func dev_tdfEncryptCmd(cmd *cobra.Command, args []string) {
-	c := cli.New(cmd, args)
+	c := cli.New(cmd, args, cli.WithPrintJson())
 	h := NewHandler(c)
 	defer h.Close()
 
@@ -40,9 +40,6 @@ func dev_tdfEncryptCmd(cmd *cobra.Command, args []string) {
 	fileMimeType := c.Flags.GetOptionalString("mime-type")
 	attrValues = c.Flags.GetStringSlice("attr", attrValues, cli.FlagsStringSliceOptions{Min: 0})
 	tdfType := c.Flags.GetOptionalString("tdf-type")
-	if tdfType == "" {
-		tdfType = TDF3
-	}
 	kasURLPath := c.Flags.GetOptionalString("kas-url-path")
 
 	piped := readPipedStdin()
@@ -91,17 +88,7 @@ func dev_tdfEncryptCmd(cmd *cobra.Command, args []string) {
 	)
 
 	// Do the encryption
-	var encrypted *bytes.Buffer
-	var err error
-	switch tdfType {
-	case TDF3:
-		encrypted, err = h.EncryptBytes(bytesSlice, attrValues, fileMimeType, kasURLPath, assertions)
-	case NANO:
-		ecdsaBinding := c.Flags.GetOptionalBool("ecdsa-binding")
-		encrypted, err = h.EncryptNanoBytes(bytesSlice, attrValues, kasURLPath, ecdsaBinding)
-	default:
-		cli.ExitWithError("Failed to encrypt", fmt.Errorf("unrecognized tdf-type: %s", tdfType))
-	}
+	encrypted, err := h.EncryptBytes(tdfType, bytesSlice, attrValues, fileMimeType, kasURLPath, c.Flags.GetOptionalBool("ecdsa-binding"), assertions)
 	if err != nil {
 		cli.ExitWithError("Failed to encrypt", err)
 	}

docs/man/auth/_index.md

@@ -5,4 +5,8 @@ command:
   name: auth
 ---
 
-This command will allow you to manage your local authentication session with the OpenTDF platform.
+> [!NOTE]
+> Requires experimental profiles feature. (Linux not yet supported. Windows is brittle.)
+
+The auth commands facilitate the process of authenticating the user with the system using profiles to store the
+credentials.

docs/man/auth/clear-client-credentials.md

@@ -9,4 +9,5 @@ command:
       default: false
 ---
 
-This command has been deprecated. Use the `profile` subcommand to manage profiles and credentials.
+> [!WARNING]
+> Deprecated. Use the `profile` subcommand to manage profiles and credentials.

docs/man/auth/client-credentials.md

@@ -9,5 +9,28 @@ command:
     - client-secret
 ---
 
+> [!NOTE]
+> Requires experimental profiles feature.
+>
+> | OS | Keychain | State |
+> | --- | --- | --- |
+> | MacOS | Keychain | Stable |
+> | Windows | Credential Manager | Alpha |
+> | Linux | Secret Service | Not yet supported |
+
 Allows the user to login in via Client Credentials flow. The client credentials will be stored safely
 in the OS keyring for future use.
+
+## Examples
+
+Authenticate with client credentials (secret provided interactively)
+
+```shell
+opentdf auth client-credentials --client-id <client-id>
+```
+
+Authenticate with client credentials (secret provided as argument)
+
+```shell
+opentdf auth client-credentials --client-id <client-id> --client-secret <client-secret>
+```

docs/man/auth/login.md

@@ -10,6 +10,15 @@ command:
       required: false
 ---
 
+> [!NOTE]
+> Requires experimental profiles feature.
+>
+> | OS | Keychain | State |
+> | --- | --- | --- |
+> | MacOS | Keychain | Stable |
+> | Windows | Credential Manager | Alpha |
+> | Linux | Secret Service | Not yet supported |
+
 Authenticate for use of the OpenTDF Platform through a browser (required).
 
 Provide a specific public 'client-id' known to support the Auth Code PKCE flow and recognized

docs/man/auth/logout.md

@@ -5,5 +5,15 @@ command:
   name: logout
 ---
 
+
+> [!NOTE]
+> Requires experimental profiles feature.
+>
+> | OS | Keychain | State |
+> | --- | --- | --- |
+> | MacOS | Keychain | Stable |
+> | Windows | Credential Manager | Alpha |
+> | Linux | Secret Service | Not yet supported |
+
 Removes any auth credentials (Client Credentials or an Access Token from a login)
 from the current profile.

docs/man/auth/print-access-token.md

@@ -9,4 +9,13 @@ command:
       default: false
 ---
 
-Retrieves a new OIDC Access Token using the client credentials from the OS-specific keychain and prints to stdout if found.
+> [!NOTE]
+> Requires experimental profiles feature.
+>
+> | OS | Keychain | State |
+> | --- | --- | --- |
+> | MacOS | Keychain | Stable |
+> | Windows | Credential Manager | Alpha |
+> | Linux | Secret Service | Not yet supported |
+
+Retrieves a new OIDC Access Token using the client credentials and prints to stdout if found.

docs/man/decrypt/_index.md

@@ -9,11 +9,7 @@ command:
       default: ''
     - name: tdf-type
       shorthand: t
-      description:  The type of tdf to decrypt as
-      enum:
-        - tdf3
-        - nano
-      default: tdf3
+      description: Deprecated. TDF type is now auto-detected.
     - name: no-verify-assertions
       description: disable verification of assertions
       default: false
@@ -23,14 +19,24 @@ Decrypt a Trusted Data Format (TDF) file and output the contents to stdout or a
 
 The first argument is the TDF file with path from the current working directory being decrypted.
 
-## Examples:
+## Examples
 
-```bash
-# specify the TDF to decrypt then output decrypted contents
-otdfctl decrypt hello.txt.tdf # write to stdout
-otdfctl decrypt hello.txt.tdf > hello.txt # consume stdout to write to hello.txt file
-otdfctl decrypt hello.txt.tdf -o hello.txt # write to hello.txt file instead of stdout
+Various ways to decrypt a TDF file
 
-# pipe the TDF to decrypt
-cat hello.txt.tdf | otdfctl decrypt > hello.txt
+```shell
+# decrypt file and write to standard output
+otdfctl decrypt hello.txt.tdf
+
+# decrypt file and write to hello.txt file
+otdfctl decrypt hello.txt.tdf -o hello.txt
+
+# decrypt piped TDF content and write to hello.txt file
+cat hello.txt.tdf | otdfctl decrypt -o hello.txt
+```
+
+Advanced piping is supported
+
+```shell
+$ echo "hello world" | otdfctl encrypt | otdfctl decrypt | cat
+hello world
 ```