feat: add examples for CLI usage

Refactor encrypt and decrypt
opentdf · Nov 5, 2024 · d89a56c · d89a56c
1 parent 57966ff
commit d89a56c
Show file tree

Hide file tree

Showing 14 changed files with 213 additions and 135 deletions.
diff --git a/cmd/tdf-decrypt.go b/cmd/tdf-decrypt.go
@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"bytes"
 	"errors"
 	"fmt"
 	"os"
@@ -14,15 +13,11 @@ 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")
-	if tdfType == "" {
-		tdfType = TDF3
-	}
 
 	// check for piped input
 	piped := readPipedStdin()
@@ -39,16 +34,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)
-	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)
 	if err != nil {
 		cli.ExitWithError("Failed to decrypt file", err)
 	}
@@ -80,6 +66,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,

diff --git a/cmd/tdf-encrypt.go b/cmd/tdf-encrypt.go
@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"bytes"
 	"fmt"
 	"io"
 	"log/slog"
@@ -16,15 +15,16 @@ import (
 )
 
 const (
-	TDF3     = "tdf3"
-	NANO     = "nano"
-	Size_1MB = 1024 * 1024
+	TDFTYPE_ZTDF = "ztdf"
+	TDF3         = "tdf3"
+	NANO         = "nano"
+	Size_1MB     = 1024 * 1024
 )
 
 var attrValues []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()
 
@@ -39,9 +39,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()
@@ -90,17 +87,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)
-	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"))
 	if err != nil {
 		cli.ExitWithError("Failed to encrypt", err)
 	}

diff --git a/docs/man/auth/_index.md b/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.
diff --git a/docs/man/auth/clear-client-credentials.md b/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.
diff --git a/docs/man/auth/client-credentials.md b/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>
+```
diff --git a/docs/man/auth/login.md b/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

diff --git a/docs/man/auth/logout.md b/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.
diff --git a/docs/man/auth/print-access-token.md b/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.
diff --git a/docs/man/decrypt/_index.md b/docs/man/decrypt/_index.md
@@ -9,25 +9,32 @@ 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.
+      default: ''
 ---
 
 Decrypt a Trusted Data Format (TDF) file and output the contents to stdout or a file in the current working directory.
 
 The first argument is the TDF file with path from the current working directory being decrypted.
 
-## Examples:
+## Examples
+
+Various ways to decrypt a TDF file
+
+```shell
+# decrypt file and write to standard output
+otdfctl decrypt hello.txt.tdf
 
-```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
+# decrypt file and write to hello.txt file
+otdfctl decrypt hello.txt.tdf -o hello.txt
 
-# pipe the TDF to decrypt
-cat hello.txt.tdf | otdfctl decrypt > 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
+```
diff --git a/docs/man/encrypt/_index.md b/docs/man/encrypt/_index.md
@@ -17,6 +17,7 @@ command:
       description: The type of tdf to encrypt as. TDF3 supports structured manifests and larger payloads. Nano has a smaller footprint and more performant, but does not support structured manifests or large payloads.
       enum:
         - tdf3
+        - ztdf
         - nano
       default: tdf3
     - name: ecdsa-binding
@@ -28,17 +29,54 @@ command:
 
 Build a Trusted Data Format (TDF) with encrypted content from a specified file or input from stdin utilizing OpenTDF platform.
 
-## Examples:
+## Examples
 
-```bash
+Various ways to encrypt a file
+
+```shell
 # output to stdout
-echo "some text" | otdfctl encrypt
 otdfctl encrypt hello.txt
-# pipe stdout to a bucket
-echo "my secret" | otdfctl encrypt | aws s3 cp - s3://my-bucket/secret.txt.tdf
 
-# output hello.txt.tdf in root directory
-echo "hello world" | otdfctl encrypt -o hello.txt
-cat hello.txt | otdfctl encrypt -o hello.txt
-cat hello.txt | otdfctl encrypt -o hello.txt.tdf #.tdf extension is only added once
+# output to hello.txt.tdf
+otdfctl encrypt hello.txt --out hello.txt.tdf
+
+# encrypt piped content and write to hello.txt.tdf
+cat hello.txt | otdfctl encrypt --out hello.txt.tdf
+```
+
+Automatically append .tdf to the output file name
+
+```shell
+$ cat hello.txt | otdfctl encrypt --out hello.txt; ls
+hello.txt  hello.txt.tdf
+
+$ cat hello.txt | otdfctl encrypt --out hello.txt.tdf; ls
+hello.txt  hello.txt.tdf
+```
+
+Advanced piping is supported
+
+```shell
+$ echo "hello world" | otdfctl encrypt | otdfctl decrypt | cat
+hello world
+```
+
+## Attributes
+
+Attributes can be added to the encrypted data. The attribute value is a Fully Qualified Name (FQN) that is used to
+restrict access to the data based on entity entitlements.
+
+```shell
+# output to hello.txt.tdf with attribute
+otdfctl encrypt hello.txt --out hello.txt.tdf --attr https://example.com/attr/attr1/value/value1
+```
+
+## NanoTDF
+
+NanoTDF is a lightweight TDF format that is more performant and has a smaller footprint than TDF3. NanoTDF does not
+support structured manifests or large payloads.
+
+```shell
+# output to nano.tdf
+otdfctl encrypt hello.txt --tdf-type nano --out hello.txt.tdf
 ```
diff --git a/go.mod b/go.mod
@@ -16,7 +16,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/opentdf/platform/lib/flattening v0.1.1
 	github.com/opentdf/platform/protocol/go v0.2.18
-	github.com/opentdf/platform/sdk v0.3.15
+	github.com/opentdf/platform/sdk v0.3.17
 	github.com/spf13/cobra v1.8.1
 	github.com/spf13/viper v1.19.0
 	github.com/stretchr/testify v1.9.0

diff --git a/go.sum b/go.sum
@@ -225,6 +225,8 @@ github.com/opentdf/platform/protocol/go v0.2.18 h1:s+TVZkOPGCzy7WyObtJWJNaFeOGDU
 github.com/opentdf/platform/protocol/go v0.2.18/go.mod h1:WqDcnFQJb0v8ivRQPidbehcL8ils5ZSZYXkuv0nyvsI=
 github.com/opentdf/platform/sdk v0.3.15 h1:RFSZ93SlBiZfFY6JAFLWbv4JC/H/KwC1acxyxCjPNnM=
 github.com/opentdf/platform/sdk v0.3.15/go.mod h1:c2+nrsRLvLf2OOryXnNy0iGZN/TScc21Pul7uqKVXIs=
+github.com/opentdf/platform/sdk v0.3.17 h1:Uo/kTMneB18i0gZNfTRtvw34bGLFUc8BEnA/BMK0VVs=
+github.com/opentdf/platform/sdk v0.3.17/go.mod h1:c2+nrsRLvLf2OOryXnNy0iGZN/TScc21Pul7uqKVXIs=
 github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs=
 github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc=
 github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=

diff --git a/pkg/handlers/nano-tdf.go b/pkg/handlers/nano-tdf.go