Updated various icert/iclient/imgr/iswift godoc's

Author: edmc-ss

icert/README.md

@@ -47,9 +47,9 @@ A `-ttl` must be specified.
 
 Both `-caCert` and `-caKey` must be specified.
 
-if `-ca` is specified:
+If `-ca` is specified:
 * neither `-cert` nor `key` may be specified
-* no `-dns` or `-ip` may be specified
+* neither `-dns` nor `-ip` may be specified
 
 If `-ca` is not specified:
 * both `-cert` and `-key` must be specified

icert/icertpkg/api.go

@@ -1,8 +1,14 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Package icertpkg provides functions to generate certificates compatible
+// with standard TLS and HTTPS packages. Functions are provided to create
+// RootCA certificates that may then subsequently be used to generate
+// endpoint certificates signed by a RootCA. The functions are designed to
+// work with either on-disk PEM files and/or in-memory PEM blocks (byte slices).
+//
 // Inspired by https://shaneutt.com/blog/golang-ca-and-signed-cert-go/
-
+//
 package icertpkg
 
 import (
@@ -33,7 +39,7 @@ const (
 	// GeneratedFilePerm is the permission bits that, after the application
 	// of umask, will specify the mode of the created cert|key files.
 	//
-	GeneratedFilePerm = 0644
+	GeneratedFilePerm = 0400
 )
 
 // GenCACert is called to generate a Certificate Authority using the requested

icert/main.go

@@ -1,6 +1,57 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Program icert provides a command-line wrapper around package icertpkg APIs.
+//
+// The following can be obtained by running the "icert -h" command:
+//
+//  Usage of icert:
+//    -ca
+//      	generated CA Certicate usable for signing Endpoint Certificates
+//    -caCert string
+//      	path to CA Certificate
+//    -caKey string
+//      	path to CA Certificate's PrivateKey
+//    -cert string
+//      	path to Endpoint Certificate
+//    -country value
+//      	generated Certificate's Subject.Country
+//    -dns value
+//      	generated Certificate's DNS Name
+//    -ed25519
+//      	generate key via Ed25519
+//    -ip value
+//      	generated Certificate's IP Address
+//    -key string
+//      	path to Endpoint Certificate's PrivateKey
+//    -locality value
+//      	generated Certificate's Subject.Locality
+//    -organization value
+//      	generated Certificate's Subject.Organization
+//    -postalCode value
+//      	generated Certificate's Subject.PostalCode
+//    -province value
+//      	generated Certificate's Subject.Province
+//    -rsa
+//      	generate key via RSA
+//    -streetAddress value
+//      	generated Certificate's Subject.StreetAddress
+//    -ttl uint
+//      	generated Certificate's time to live in days
+//    -v	verbose mode
+//
+// Precisely one of "-ed25519" or "-rsa" must be specified.
+//
+// A "-ttl" must be specified.
+//
+// Both "-caCert" and "-caKey" must be specified.
+//
+// If "-ca" is specified, none of "-cert" nor "key" may be specified.
+// Similarly, neither "-dns" nor "-ip" may be specified.
+//
+// If "-ca" is not specified, both "-cert" and "-key" must be specified.
+// Similarly, at least one "-dns" and/or one "-ip" must be specified.
+//
 package main
 
 import (

iclient/main.go

@@ -1,6 +1,12 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Program iclient provides a command-line wrapper around package iclientpkg APIs.
+//
+// The program requires a single argument that is a path to a package config
+// formatted configuration to load. Optionally, overrides the the config may
+// be passed as additional arguments in the form <section_name>.<option_name>=<value>.
+//
 package main
 
 func main() {}

imgr/main.go

@@ -1,6 +1,12 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Program imgr provides a command-line wrapper around package imgrpkg APIs.
+//
+// The program requires a single argument that is a path to a package config
+// formatted configuration to load. Optionally, overrides the the config may
+// be passed as additional arguments in the form <section_name>.<option_name>=<value>.
+//
 package main
 
 import (

iswift/iswiftpkg/api.go

@@ -1,27 +1,48 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Package iswiftpkg implements an emulation of OpenStack Swift by presenting
+// a Swift Proxy responding to a minimal set of base OpenStack Swift HTTP
+// methods. While there is no support for TLS, a simple Auth functionality
+// is provided and its usage is enforced.
+//
+// To configure an iswiftpkg instance, Start() is called passing, as the sole
+// argument, a package conf ConfMap. Here is a sample .conf file:
+//
+//  [ISWIFT]
+//  SwiftProxyIPAddr:       127.0.0.1
+//  SwiftProxyTCPPort:      8080
+//
+//  MaxAccountNameLength:   256
+//  MaxContainerNameLength: 256
+//  MaxObjectNameLength:    1024
+//  AccountListingLimit:    10000
+//  ContainerListingLimit:  10000
+//
 package iswiftpkg
 
 import (
 	"github.com/NVIDIA/proxyfs/conf"
 )
 
 // Start is called to start serving the NoAuth Swift Proxy Port and,
-// optionally, the Auth Swift Proxy Port
+// optionally, the Auth Swift Proxy Port.
 //
 func Start(confMap conf.ConfMap) (err error) {
 	err = start(confMap)
 	return
 }
 
-// Stop is called to stop serving
+// Stop is called to stop serving.
 //
 func Stop() (err error) {
 	err = stop()
 	return
 }
 
+// ForceReAuth is called to force a "401 Unauthorized" response to a
+// client's subsequent request forcing the client to reauthenticate.
+//
 func ForceReAuth() {
 	forceReAuth()
 }

iswift/main.go

@@ -1,6 +1,12 @@
 // Copyright (c) 2015-2021, NVIDIA CORPORATION.
 // SPDX-License-Identifier: Apache-2.0
 
+// Program iswift provides a command-line wrapper around package iswiftpkg APIs.
+//
+// The program requires a single argument that is a path to a package config
+// formatted configuration to load. Optionally, overrides the the config may
+// be passed as additional arguments in the form <section_name>.<option_name>=<value>.
+//
 package main
 
 import (