add more documentation to ecdsa

1 files changed, 17 insertions, 10 deletions

diff --git a/ecdsa.go b/ecdsa.go
index 2844350..4531d4e 100644
--- a/ecdsa.go
+++ b/ecdsa.go
@@ -12,9 +12,8 @@ import (
   "math/big"
 )
 
-const (
-  PemLabelEcdsa = "EC PRIVATE KEY"
-)
+// This label is used as the type in the pem encoding of ECDSA private keys.
+const PemLabelEcdsa = "EC PRIVATE KEY"
 
 type (
   // This type handles the function calls to the ecdsa private key by
@@ -23,16 +22,20 @@ type (
     private_key *ecdsa.PrivateKey
   }
 
+  // EcdsaPublicKey is the specific public key type for ecdsa. It implements the
+  // the PublicKey interface.
   EcdsaPublicKey struct {
     public_key *ecdsa.PublicKey
   }
 
+  // This struct is used to marshal and parse the ecdsa signature.
   signatureEcdsa struct {
     R, S *big.Int
   }
 )
 
 // Create a new ECDSA private key using the specified curve.
+// For available curves, please take a look at the crypto/elliptic package.
 func NewPrivateKeyEcdsa(curve elliptic.Curve) (*EcdsaPrivateKey, error) {
   key, err := ecdsa.GenerateKey(curve, rand.Reader)
   if err != nil { return nil, err }
@@ -46,12 +49,12 @@ func LoadPrivateKeyEcdsa(raw []byte) (*EcdsaPrivateKey, error) {
   return &EcdsaPrivateKey{key}, nil
 }
 
-// derive a public key from the private key
+// Create a new public key from the private key.
 func (pr EcdsaPrivateKey) Public() PublicKey {
   return &EcdsaPublicKey{pr.private_key.Public().(*ecdsa.PublicKey)}
 }
 
-// sign a message with the private key
+// Sign a message using the private key and the provided hash function.
 func (pr EcdsaPrivateKey) Sign(message []byte, hash crypto.Hash) ([]byte, error) {
   empty := make([]byte, 0)
   if !hash.Available() {
@@ -62,12 +65,13 @@ func (pr EcdsaPrivateKey) Sign(message []byte, hash crypto.Hash) ([]byte, error)
   return pr.private_key.Sign(rand.Reader, hashed_message.Sum(nil), hash)
 }
 
-// get the private key
+// This function returns the crypto.PrivateKey structure of the ECDSA key.
 func (pr EcdsaPrivateKey) PrivateKey() crypto.PrivateKey {
   return pr.private_key
 }
 
-// implement Pemmer interface
+// This function implements the Pemmer interface to marshal the private key
+// into a pem block.
 func (pr EcdsaPrivateKey) MarshalPem() (marshalledPemBlock, error) {
   asn1, err := x509.MarshalECPrivateKey(pr.private_key)
   if err != nil { return nil, err }
@@ -75,7 +79,7 @@ func (pr EcdsaPrivateKey) MarshalPem() (marshalledPemBlock, error) {
   return pem.EncodeToMemory(&pem_block), nil
 }
 
-// load an ecdsa public key
+// This functoin loads an ecdsa public key from the asn.1 representation.
 func LoadPublicKeyEcdsa(raw []byte) (*EcdsaPublicKey, error) {
   raw_pub, err := x509.ParsePKIXPublicKey(raw)
   if err != nil { return nil, err }
@@ -85,7 +89,8 @@ func LoadPublicKeyEcdsa(raw []byte) (*EcdsaPublicKey, error) {
   return &EcdsaPublicKey{pub}, nil
 }
 
-// marshal the public key to a pem block
+// This function implements the Pemmer interface to marshal the public key into
+// a pem block.
 func (pu *EcdsaPublicKey) MarshalPem() (marshalledPemBlock, error) {
   asn1, err := x509.MarshalPKIXPublicKey(pu.public_key)
   if err != nil { return nil, err }
@@ -93,7 +98,9 @@ func (pu *EcdsaPublicKey) MarshalPem() (marshalledPemBlock, error) {
   return pem.EncodeToMemory(&pem_block), nil
 }
 
-// verify a message using the ecdsa public key
+// This function verifies a message using the public key, signature and hash
+// function.
+// The hash function must be the same as was used to create the signature.
 func (pu *EcdsaPublicKey) Verify(message []byte, signature_raw []byte, hash crypto.Hash) (bool, error) {
   var sig signatureEcdsa
   _, err := asn1.Unmarshal(signature_raw, &sig)