From 3ed91b141c14c115ac544d150cef6c8b5e47325f Mon Sep 17 00:00:00 2001
From: Chad Retz <chad.retz@gmail.com>
Date: Wed, 16 May 2018 17:56:00 -0500
Subject: [PATCH] Some ed25519 and key function docs

---
 torutil/ed25519/ed25519.go |  7 +++++++
 torutil/key.go             | 10 ++++++++++
 2 files changed, 17 insertions(+)

diff --git a/torutil/ed25519/ed25519.go b/torutil/ed25519/ed25519.go
index 289c4b0..a1807b7 100644
--- a/torutil/ed25519/ed25519.go
+++ b/torutil/ed25519/ed25519.go
@@ -38,10 +38,16 @@ func FromCryptoPublicKey(key ed25519.PublicKey) PublicKey {
 	return PublicKey(key)
 }
 
+// Public simply delegates to PublicKey() to satisfy crypto.Signer. This method
+// does a bit more work than the traditional Go ed25519's private key's Public()
+// method so developers are encouraged to reuse the result.
 func (p PrivateKey) Public() crypto.PublicKey {
 	return p.PublicKey()
 }
 
+// PublicKey generates a public key for this private key. This method does a bit
+// more work than the traditional Go ed25519's private key's Public() method so
+// developers are encouraged to reuse the result.
 func (p PrivateKey) PublicKey() PublicKey {
 	var A edwards25519.ExtendedGroupElement
 	var hBytes [32]byte
@@ -52,6 +58,7 @@ func (p PrivateKey) PublicKey() PublicKey {
 	return publicKeyBytes[:]
 }
 
+// Sign is not yet implemented.
 func (p PrivateKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error) {
 	if opts.HashFunc() != crypto.Hash(0) {
 		return nil, errors.New("ed25519: cannot sign hashed message")
diff --git a/torutil/key.go b/torutil/key.go
index 3185b3b..f2861fa 100644
--- a/torutil/key.go
+++ b/torutil/key.go
@@ -15,6 +15,9 @@ import (
 
 var serviceIDEncoding = base32.StdEncoding.WithPadding(base32.NoPadding)
 
+// OnionServiceIDFromPrivateKey generates the onion service ID from the given
+// private key. This panics if the private key is not a crypto/*rsa.PrivateKey
+// or github.com/cretz/bine/torutil/ed25519.PrivateKey.
 func OnionServiceIDFromPrivateKey(key crypto.PrivateKey) string {
 	switch k := key.(type) {
 	case *rsa.PrivateKey:
@@ -25,6 +28,9 @@ func OnionServiceIDFromPrivateKey(key crypto.PrivateKey) string {
 	panic(fmt.Sprintf("Unrecognized private key type: %T", key))
 }
 
+// OnionServiceIDFromPublicKey generates the onion service ID from the given
+// public key. This panics if the public key is not a crypto/*rsa.PublicKey or
+// github.com/cretz/bine/torutil/ed25519.PublicKey.
 func OnionServiceIDFromPublicKey(key crypto.PublicKey) string {
 	switch k := key.(type) {
 	case *rsa.PublicKey:
@@ -35,12 +41,16 @@ func OnionServiceIDFromPublicKey(key crypto.PublicKey) string {
 	panic(fmt.Sprintf("Unrecognized private key type: %T", key))
 }
 
+// OnionServiceIDFromV2PublicKey generates a V2 service ID for the given
+// RSA-1024 public key.
 func OnionServiceIDFromV2PublicKey(key *rsa.PublicKey) string {
 	h := sha1.New()
 	h.Write(x509.MarshalPKCS1PublicKey(key))
 	return strings.ToLower(serviceIDEncoding.EncodeToString(h.Sum(nil)[:10]))
 }
 
+// OnionServiceIDFromV3PublicKey generates a V3 service ID for the given
+// ED25519 public key.
 func OnionServiceIDFromV3PublicKey(key ed25519.PublicKey) string {
 	checkSum := sha3.Sum256(append(append([]byte(".onion checksum"), key...), 0x03))
 	var keyBytes [35]byte