docs: module, client, clientconfig Go documentation

Author: wobondar

Diff for: doc.go

@@ -1,4 +1,73 @@
 // Copyright Chainify Group LTD. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+// Package sdk is the Unofficial Go SDK implementation of the AWS Encryption SDK.
+//
+// # Getting started
+//
+// To install the AWS Encryption SDK for Go, use the following command:
+//
+//	go get github.com/chainifynet/aws-encryption-sdk-go@latest
+//
+// # Usage
+//
+// The following example demonstrates how to use SDK to encrypt and decrypt data using a static key.
+//
+//	package main
+//
+//	import (
+//		"context"
+//		"fmt"
+//
+//		"github.com/chainifynet/aws-encryption-sdk-go/pkg/client"
+//		"github.com/chainifynet/aws-encryption-sdk-go/pkg/materials"
+//		"github.com/chainifynet/aws-encryption-sdk-go/pkg/providers/rawprovider"
+//	)
+//
+//	func main() {
+//		// static key to use for encryption and decryption
+//		staticKey1 := []byte("superSecureKeySecureKey32bytes32")
+//
+//		// data to encrypt
+//		secretData := []byte("secret data to encrypt")
+//
+//		// setup Encryption SDK client with default configuration
+//		sdkClient := client.NewClient()
+//
+//		// setup Raw Key provider
+//		rawKeyProvider, err := rawprovider.NewWithOpts(
+//			"raw",
+//			rawprovider.WithStaticKey("static1", staticKey1),
+//		)
+//		if err != nil {
+//			panic(err) // handle error
+//		}
+//
+//		// setup crypto materials manager
+//		cmm, err := materials.NewDefault(rawKeyProvider)
+//		if err != nil {
+//			panic(err) // handle error
+//		}
+//
+//		// encrypt data without encryption context passing nil as the third argument
+//		encrypted, header, err := sdkClient.Encrypt(context.TODO(), secretData, nil, cmm)
+//		if err != nil {
+//			panic(err) // handle error
+//		}
+//
+//		fmt.Printf("encrypted encryption context: %v\n", header.AADData().EncryptionContext())
+//
+//		// decrypt "encrypted" data
+//		decrypted, _, err := sdkClient.Decrypt(context.TODO(), encrypted, cmm)
+//		if err != nil {
+//			panic(err) // handle error
+//		}
+//
+//		fmt.Printf("decrypted data: %s\n", decrypted)
+//
+//		// verify that "decrypted" plaintext is identical to the original secret data
+//		if string(decrypted) != string(secretData) {
+//			panic("decrypted data does not match with the original data")
+//		}
+//	}
 package sdk

Diff for: pkg/client/doc.go

@@ -0,0 +1,5 @@
+// Copyright Chainify Group LTD. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package client provides the entrypoint for using AWS Encryption SDK for Go.
+package client

Diff for: pkg/client/options.go

@@ -12,7 +12,8 @@ import (
 )
 
 const (
-	DefaultFrameLength = int(4096) // default frame size for encryption
+	// DefaultFrameLength default frame length for encryption.
+	DefaultFrameLength = int(4096)
 )
 
 // EncryptOptions defines the configuration options for the encryption process.
@@ -25,9 +26,12 @@ const (
 //   - Handler: Specifies a function that creates [model.EncryptionHandler] encryption handler.
 //     If not set, a default [encrypter.New] function is used.
 type EncryptOptions struct {
-	Algorithm   *suite.AlgorithmSuite
+	// Algorithm that defines the encryption algorithm to be used.
+	Algorithm *suite.AlgorithmSuite
+	// FrameLength specifies the frame length for encryption.
 	FrameLength int
-	Handler     func(config crypto.EncrypterConfig, cmm model.CryptoMaterialsManager) model.EncryptionHandler
+	// Handler specifies a function that creates model.EncryptionHandler encryption handler.
+	Handler func(config crypto.EncrypterConfig, cmm model.CryptoMaterialsManager) model.EncryptionHandler
 }
 
 // DecryptOptions defines the configuration options for the decryption process.
@@ -36,6 +40,7 @@ type EncryptOptions struct {
 //   - Handler: Specifies a function that creates [model.DecryptionHandler] decryption handler.
 //     If not set, a default [decrypter.New] function is used.
 type DecryptOptions struct {
+	// Handler specifies a function that creates model.DecryptionHandler decryption handler.
 	Handler func(config crypto.DecrypterConfig, cmm model.CryptoMaterialsManager) model.DecryptionHandler
 }
 

Diff for: pkg/clientconfig/client_config.go

@@ -10,34 +10,56 @@ import (
 	"github.com/chainifynet/aws-encryption-sdk-go/pkg/suite"
 )
 
+// ConfigOptions is a holder of the configuration options for the client.
 type ConfigOptions struct {
-	CommitmentPolicy     suite.CommitmentPolicy
+	// CommitmentPolicy is the commitment policy for the client.
+	CommitmentPolicy suite.CommitmentPolicy
+
+	// MaxEncryptedDataKeys is the maximum number of encrypted data keys that can be used in a single message.
 	MaxEncryptedDataKeys int
 }
 
+// ConfigOptionFunc is a function that sets a configuration option.
 type ConfigOptionFunc func(o *ConfigOptions) error
 
+// ClientConfig is the configuration for the client.
 type ClientConfig struct {
 	commitmentPolicy     suite.CommitmentPolicy
 	maxEncryptedDataKeys int
 }
 
+// CommitmentPolicy returns the commitment policy for the client.
 func (c ClientConfig) CommitmentPolicy() suite.CommitmentPolicy {
 	return c.commitmentPolicy
 }
 
+// MaxEncryptedDataKeys returns the maximum number of encrypted data keys that can be used in a single message.
 func (c ClientConfig) MaxEncryptedDataKeys() int {
 	return c.maxEncryptedDataKeys
 }
 
+// NewConfig returns a new client configuration with the default options.
 func NewConfig() (*ClientConfig, error) {
 	return NewConfigWithOpts()
 }
 
+// NewConfigWithOpts returns a new client configuration with the provided options.
+// The options are passed as [ConfigOptionFunc] functions, which modify the [ConfigOptions] struct.
+//
+// The default values for the configuration options are as follows:
+//   - CommitmentPolicy: [DefaultCommitment]
+//   - MaxEncryptedDataKeys: [DefaultMaxEDK]
+//
+// Example usage:
+//
+//	cfg, err := NewConfigWithOpts(
+//		WithCommitmentPolicy(suite.CommitmentPolicyRequireEncryptAllowDecrypt),
+//		WithMaxEncryptedDataKeys(5),
+//	)
 func NewConfigWithOpts(optFns ...ConfigOptionFunc) (*ClientConfig, error) {
 	opts := ConfigOptions{
-		CommitmentPolicy:     defaultCommitment,
-		MaxEncryptedDataKeys: defaultMaxEDK,
+		CommitmentPolicy:     DefaultCommitment,
+		MaxEncryptedDataKeys: DefaultMaxEDK,
 	}
 	for _, optFn := range optFns {
 		if err := optFn(&opts); err != nil {
@@ -50,6 +72,7 @@ func NewConfigWithOpts(optFns ...ConfigOptionFunc) (*ClientConfig, error) {
 	}, nil
 }
 
+// WithCommitmentPolicy returns a [ConfigOptionFunc] that sets the commitment policy for the client.
 func WithCommitmentPolicy(policy suite.CommitmentPolicy) ConfigOptionFunc {
 	return func(o *ConfigOptions) error {
 		if err := suite.ValidateCommitmentPolicy(policy); err != nil {
@@ -60,6 +83,8 @@ func WithCommitmentPolicy(policy suite.CommitmentPolicy) ConfigOptionFunc {
 	}
 }
 
+// WithMaxEncryptedDataKeys returns a [ConfigOptionFunc] that sets the maximum
+// number of encrypted data keys that can be used in a single message.
 func WithMaxEncryptedDataKeys(maxEncryptedDataKeys int) ConfigOptionFunc {
 	return func(o *ConfigOptions) error {
 		if maxEncryptedDataKeys > math.MaxUint8 {

Diff for: pkg/clientconfig/client_config_test.go

@@ -15,8 +15,8 @@ func TestNewConfig(t *testing.T) {
 	defaultCfg, err := NewConfig()
 	assert.NoError(t, err)
 
-	assert.Equal(t, defaultCommitment, defaultCfg.CommitmentPolicy())
-	assert.Equal(t, defaultMaxEDK, defaultCfg.MaxEncryptedDataKeys())
+	assert.Equal(t, DefaultCommitment, defaultCfg.CommitmentPolicy())
+	assert.Equal(t, DefaultMaxEDK, defaultCfg.MaxEncryptedDataKeys())
 }
 
 func TestNewConfigWithOpts(t *testing.T) {

Diff for: pkg/clientconfig/client_defaults.go

@@ -6,6 +6,10 @@ package clientconfig
 import "github.com/chainifynet/aws-encryption-sdk-go/pkg/suite"
 
 const (
-	defaultCommitment = suite.CommitmentPolicyRequireEncryptRequireDecrypt
-	defaultMaxEDK     = 10
+	// DefaultCommitment is the default commitment policy for the client.
+	DefaultCommitment = suite.CommitmentPolicyRequireEncryptRequireDecrypt
+
+	// DefaultMaxEDK is the default maximum number of encrypted data keys that can be
+	// used to encrypt or decrypt a single message.
+	DefaultMaxEDK = 10
 )

Diff for: pkg/clientconfig/doc.go

@@ -0,0 +1,5 @@
+// Copyright Chainify Group LTD. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package clientconfig provides a way to configure SDK client.
+package clientconfig

Diff for: pkg/crypto/config.go

@@ -8,12 +8,14 @@ import (
 	"github.com/chainifynet/aws-encryption-sdk-go/pkg/suite"
 )
 
+// EncrypterConfig is the configuration for the encrypter.
 type EncrypterConfig struct {
 	ClientCfg   clientconfig.ClientConfig
 	Algorithm   *suite.AlgorithmSuite
 	FrameLength int
 }
 
+// DecrypterConfig is the configuration for the decrypter.
 type DecrypterConfig struct {
 	ClientCfg clientconfig.ClientConfig
 }

Diff for: pkg/crypto/doc.go

@@ -0,0 +1,5 @@
+// Copyright Chainify Group LTD. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package crypto provides common errors and encryption configuration.
+package crypto

Diff for: pkg/doc.go

@@ -0,0 +1,5 @@
+// Copyright Chainify Group LTD. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package pkg provides the core SDK packages.
+package pkg

Diff for: pkg/version.go

@@ -3,4 +3,5 @@
 
 package pkg
 
+// Version is the current version of the SDK.
 const Version = "0.3.2"