add documentation

types.go

@@ -1,35 +1,51 @@
+// Package pki provides an easier way to create crypto related structures
+// with the intent of making the management of these structures easier for
+// other programs.
+// Currently it provides mechanisms to create private keys in ECDSA and RSA,
+// create public keys, create certificate sign requests and certificates.
+//
+// To create a new private key, there are two ways
+// for an ecdsa key
+//   private_key, err := NewPrivateKeyEcdsa(elliptic.P521())
+// or for a RSA key
+//   private_key, err := NewPrivateKeyRSA(4096)
+//
+// Getting a private key from the private key can be done with
+//   public_key := private_key.Public()
 package pki
 
 import (
   "crypto"
 )
 
-// this file holds all the interfaces used in the program until it can be split
-// properly
-
+// This label is used as the type in the pem encoding of public keys.
 const PemLabelPublic = "PUBLIC KEY"
 
 type (
-  // interface for any private key
+  // This is the common interface for all private keys.
   PrivateKey interface {
-    // derive a public key from the private key
+    // Derive a new public key from the private key.
     Public() PublicKey
     // Sign a message using the public key and the given hash method.
     // To use a hash method, include the package
     //   import _ "crypto/sha512"
     Sign(message []byte, hash crypto.Hash) ([]byte, error)
 
-    // return the private key structure
+    // Return the original go structure of the private key.
     PrivateKey() crypto.PrivateKey
   }
 
-  // interface for any public key
+  // This interface has to be implemented by every public key structure.
   PublicKey interface {
     Pemmer
-    // use the public key to verify a message against a signature
+    // This function can be used to verify a message against a provided signature
+    // using the given hash function.
     Verify(message []byte, signature []byte, hash crypto.Hash) (bool, error)
   }
 
+  // This interface is used by all crypto structures which need to be available
+  // in the pem format. The result can then be written to any structure
+  // implementing the io.Writer interface.
   Pemmer interface {
     MarshalPem() (marshalledPemBlock, error)
   }