From 4ef882c564576578a50cefbf1c8f9ab75dc31454 Mon Sep 17 00:00:00 2001 From: Daniel Huigens Date: Wed, 15 May 2019 14:57:35 +0200 Subject: [PATCH] More documentation fixes --- armor/armor.go | 14 ++++++++------ constants/armor.go | 3 ++- constants/cipher.go | 4 ++-- crypto/keyring.go | 2 +- internal/armor.go | 2 +- internal/common.go | 8 +++++--- models/models.go | 9 +++++---- subtle/subtle.go | 2 ++ 8 files changed, 26 insertions(+), 18 deletions(-) diff --git a/armor/armor.go b/armor/armor.go index ad051be..082f48c 100644 --- a/armor/armor.go +++ b/armor/armor.go @@ -1,4 +1,5 @@ -// This package contains a set of helper methods for armoring and unarmoring +// Package armor contains a set of helper methods for armoring and unarmoring +// data. package armor import ( @@ -12,17 +13,18 @@ import ( "io/ioutil" ) -// ArmorKey makes bytes input key to armor format +// ArmorKey armors input as a public key. func ArmorKey(input []byte) (string, error) { return ArmorWithType(input, constants.PublicKeyHeader) } -// ArmorWithTypeBuffered takes input from io.Writer and returns io.WriteCloser which can be read for armored code +// ArmorWithTypeBuffered returns a io.WriteCloser which, when written to, writes +// armored data to w with the given armorType. func ArmorWithTypeBuffered(w io.Writer, armorType string) (io.WriteCloser, error) { return armor.Encode(w, armorType, nil) } -// ArmorWithType makes bytes input to armor format +// ArmorWithType armors input with the given armorType. func ArmorWithType(input []byte, armorType string) (string, error) { var b bytes.Buffer @@ -39,7 +41,7 @@ func ArmorWithType(input []byte, armorType string) (string, error) { return b.String(), nil } -// Unarmor an armored key to bytes key +// Unarmor unarmors an armored key. func Unarmor(input string) ([]byte, error) { b, err := internal.Unarmor(input) if err != nil { @@ -48,7 +50,7 @@ func Unarmor(input string) ([]byte, error) { return ioutil.ReadAll(b.Body) } -// ReadClearSignedMessage reads clear message from a clearsign package (package containing cleartext and signature) +// ReadClearSignedMessage returns the message body from a clearsigned message. func ReadClearSignedMessage(signedMessage string) (string, error) { modulusBlock, rest := clearsign.Decode([]byte(signedMessage)) if len(rest) != 0 { diff --git a/constants/armor.go b/constants/armor.go index 016df5b..357c9ee 100644 --- a/constants/armor.go +++ b/constants/armor.go @@ -1,6 +1,7 @@ +// Package constants provides a set of common OpenPGP constants. package constants -// Definitions for armored data +// Constants for armored data. const ( ArmorHeaderVersion = "GopenPGP 0.0.1 (" + Version + ")" ArmorHeaderComment = "https://gopenpgp.org" diff --git a/constants/cipher.go b/constants/cipher.go index cc91aab..1f1f8fa 100644 --- a/constants/cipher.go +++ b/constants/cipher.go @@ -1,9 +1,9 @@ package constants -// Definitions for cipher suites +// Cipher suite names. const ( ThreeDES = "3des" - TripleDES = "tripledes" + TripleDES = "tripledes" // Both "3des" and "tripledes" refer to 3DES. CAST5 = "cast5" AES128 = "aes128" AES192 = "aes192" diff --git a/crypto/keyring.go b/crypto/keyring.go index 104b091..ea312d3 100644 --- a/crypto/keyring.go +++ b/crypto/keyring.go @@ -174,7 +174,7 @@ func (kr *KeyRing) Encrypt(w io.Writer, sign *KeyRing, filename string, canonica func() time.Time { return GetGopenPGP().GetTime() }) } -// EncryptCore is common encryption method for desktop and mobile clients +// EncryptCore is lower-level encryption method used by KeyRing.Encrypt. func EncryptCore(w io.Writer, encryptEntities []*openpgp.Entity, signEntity *openpgp.Entity, filename string, canonicalizeText bool, timeGenerator func() time.Time) (io.WriteCloser, error) { diff --git a/internal/armor.go b/internal/armor.go index 7ed9e14..9788e30 100644 --- a/internal/armor.go +++ b/internal/armor.go @@ -5,7 +5,7 @@ import ( "strings" ) -// Unarmor from string +// Unarmor unarmors an armored string. func Unarmor(input string) (*armor.Block, error) { io := strings.NewReader(input) b, err := armor.Decode(io) diff --git a/internal/common.go b/internal/common.go index ed7d664..b372807 100644 --- a/internal/common.go +++ b/internal/common.go @@ -1,3 +1,4 @@ +// Package internal contains internal methods and constants. package internal import ( @@ -6,17 +7,18 @@ import ( "github.com/ProtonMail/gopenpgp/constants" ) -// TrimNewlines removes a whitespace in the end of string (don't stop on linebreak) +// TrimNewlines removes whitespace from the end of each line of the input +// string. func TrimNewlines(input string) string { var re = regexp.MustCompile(`(?m)[ \t]*$`) return re.ReplaceAllString(input, "") } // CreationTimeOffset stores the amount of seconds that a signature may be -// created in the future, to compensate for clock skew +// created in the future, to compensate for clock skew. const CreationTimeOffset = int64(60 * 60 * 24 * 2) -// ArmorHeaders from gopenpgp +// ArmorHeaders is a map of default armor headers. var ArmorHeaders = map[string]string{ "Version": constants.ArmorHeaderVersion, "Comment": constants.ArmorHeaderComment, diff --git a/models/models.go b/models/models.go index 4fd60ff..721d41c 100644 --- a/models/models.go +++ b/models/models.go @@ -1,20 +1,21 @@ -// Provides high-level public data models used for communication mainly with mobile clients +// Package models provides structs containing message data. package models -// EncryptedSplit when encrypt attachment +// EncryptedSplit contains a separate session key packet and symmetrically +// encrypted data packet. type EncryptedSplit struct { DataPacket []byte KeyPacket []byte Algo string } -// EncryptedSigned encrypt_sign_package +// EncryptedSigned contains an encrypted message and signature. type EncryptedSigned struct { Encrypted string Signature string } -// DecryptSignedVerify decrypt_sign_verify +// DecryptSignedVerify contains a decrypted message and verification result. type DecryptSignedVerify struct { //clear text Plaintext string diff --git a/subtle/subtle.go b/subtle/subtle.go index c7f076b..5da5b3c 100644 --- a/subtle/subtle.go +++ b/subtle/subtle.go @@ -1,3 +1,5 @@ +// Package subtle contains subtly insecure methods not recommended for casual +// use. package subtle import (