[IMP] Add Docs to helper objs & fix sphinx syntax

cfssl/defaults.py

@@ -2,6 +2,9 @@
 # Copyright 2016 LasLabs Inc.
 # License MIT (https://opensource.org/licenses/MIT).
 
+from datetime import timedelta
+
+
 DEFAULT_ALGORITHM = 'rsa'
 DEFAULT_STRENGTH = 4096
-DEFAULT_EXPIRE_MINUTES = 365 * 24 * 60
+DEFAULT_EXPIRE_DELTA = timedelta(days=365)

cfssl/models/certificate_request.py

@@ -11,6 +11,18 @@ class CertificateRequest(object):
     """ It provides a Certificate Request compatible with CFSSL. """
 
     def __init__(self, common_name, names=None, hosts=None, key=None):
+        """ Initialize a new CertificateRequest.
+
+        Args:
+            common_name (:obj:`str`): The fully qualified domain name for the
+                server. This must be an exact match.
+            names (:type:`iter` of :obj:`cfssl.SubjectInfo`, optional):
+                Subject Information to be added to the request.
+            hosts (:type:`iter` of :obj:`cfssl.Host`, optional): Hosts
+                to be added to the request.
+            key (:obj:`cfssl.ConfigKey`, optional): Key configuration
+                for the request.
+        """
         self.common_name = common_name
         self.names = names or []
         self.hosts = hosts or []

cfssl/models/config_client.py

@@ -10,6 +10,18 @@ class ConfigClient(ConfigMixer):
 
     def __init__(self, sign_policy_default,
                  sign_policies_add, auth_policies, remotes):
+        """ Initialize a new Client Configuration.
+
+        Args:
+            sign_policy_default (:obj:`cfssl.PolicySign`): Default signing
+                policy for client to use.
+            sign_policies_add (:type:`iter` of :obj:`cfssl.PolicySign`):
+                Additional signing policies to use for the client.
+            auth_policies (:type:`iter` of :obj:`cfssl.PolicyAuth`): Auth
+                policies for the client.
+            remotes (:type:`iter` of :obj:`cfssl.Host`): Remote hosts that
+                client trusts.
+        """
         super(ConfigClient, self).__init__(
             sign_policy_default, auth_policies, remotes,
         )

cfssl/models/config_key.py

@@ -10,6 +10,14 @@ class ConfigKey(object):
 
     def __init__(self, algorithm=DEFAULT_ALGORITHM,
                  strength=DEFAULT_STRENGTH):
+        """ Initialize a new Client Configuration.
+
+        Args:
+            algorithm (:obj:`str`, optional): Algorithm to use for key, one of
+                ``rsa`` or ``ecdsa``. Defaults to ``rsa``.
+            strength (:obj:`int`, optional): Key bit strength. Defaults to
+                ``4096``.
+        """
         self.algorithm = algorithm
         self.strength = strength
 

cfssl/models/config_mixer.py

@@ -7,6 +7,16 @@ class ConfigMixer(object):
     """ It provides a mixer for the Client and Server Configs """
 
     def __init__(self, sign_policy_default, sign_policies_add, auth_policies):
+        """ Initialize a new General Configuration for Server or Client.
+
+        Args:
+            sign_policy_default (:obj:`cfssl.PolicySign`): Default signing
+                policy for entity to use.
+            sign_policies_add (:type:`iter` of :obj:`cfssl.PolicySign`):
+                Additional signing policies to use for the entity.
+            auth_policies (:type:`iter` of :obj:`cfssl.PolicyAuth`): Auth
+                policies for the entity.
+        """
         self.sign_policy = sign_policy_default
         self.sign_policies = sign_policies_add
         self.auth_policies = auth_policies

cfssl/models/host.py

@@ -7,6 +7,14 @@ class Host(object):
     """ It provides a Host compatible with CFSSL. """
 
     def __init__(self, name, host, port=None):
+        """ Initialize a new Client Configuration.
+
+        Args:
+            name (:obj:`str`): Canonical name of host/remote.
+            host (:obj:`str`): Advertised host name or IP for host.
+            port (:obj:`int`, optional): Port number advertised by host, if
+                any.
+        """
         self.name = name
         self.host = host
         self.port = port

cfssl/models/policy_auth.py

@@ -7,6 +7,14 @@ class PolicyAuth(object):
     """ It provides a Certificate Auth policy compatible with CFSSL """
 
     def __init__(self, name, key, key_type='standard'):
+        """ Initialize a new Authentication Policy.
+
+        Args:
+            name (:obj:`str`): Canonical name for policy.
+            key (:obj:`str`): Key/password data.
+            key_type (:obj:`str`): Type of key. Currently only ``standard`` is
+                supported.
+        """
         self.name = name
         self.key = key
         self.key_type = key_type

cfssl/models/policy_sign.py

@@ -2,23 +2,34 @@
 # Copyright 2016 LasLabs Inc.
 # License MIT (https://opensource.org/licenses/MIT).
 
-from ..defaults import DEFAULT_EXPIRE_MINUTES
+from ..defaults import DEFAULT_EXPIRE_DELTA
 
 
 class PolicySign(object):
     """ It provides a Certificate Auth policy compatible with CFSSL """
 
     def __init__(self, name, usage_policies, auth_policy,
-                 expire_minutes=DEFAULT_EXPIRE_MINUTES):
+                 expire_delta=DEFAULT_EXPIRE_DELTA):
+        """ Initialize a new Signing Policy.
+
+        Args:
+            name (:obj:`str`): Canonical name for policy.
+            usage_policies (:type:`iter` of :obj:`cfssl.PolicyUse`): Usage
+                policies that should apply to this signing policy.
+            auth_policy (:obj:`obj.PolicyAuth`): Authentication policy that
+                should apply to this signing policy.
+            expire_delta  (:obj:`datetime.timedelta`): Delta representing when
+                the signature should expire.
+        """
         self.name = name
         self.usage_policies = usage_policies
         self.auth_policy = auth_policy
-        self.expire_minutes = expire_minutes
+        self.expire_delta = expire_delta
 
     def to_api(self):
         """ It returns an object compatible with the API. """
         return {
             'auth_key': self.auth_policy.name,
-            'expiry': '%dm' % self.expire_minutes,
+            'expiry': '%ds' % self.expire_delta.total_seconds(),
             'usages': [u.to_api() for u in self.usage_policies],
         }

cfssl/models/policy_use.py

@@ -7,6 +7,12 @@ class PolicyUse(object):
     """ It provides a Certificate Use policy compatible with CFSSL """
 
     def __init__(self, name, code):
+        """ Initialize a new Use Policy.
+
+        Args:
+            name (:obj:`str`): Canonical name for policy.
+            code (:obj:`str`): CFSSL use code that policy applies to.
+        """
         self.name = name
         self.code = code
 

cfssl/models/subject_info.py

@@ -7,6 +7,17 @@ class SubjectInfo(object):
     """ It provides a SubjectInfo (Name) compatible with CFSSL. """
 
     def __init__(self, org_name, org_unit, city, state, country):
+        """ Initialize a new Subject Information.
+
+        Args:
+            org_name (:obj:`str`): The full legal name of the organization. Do
+                not abbreviate.
+            org_unit (:obj:`str`): Section of the organization.
+            city (:obj:`str`): The city where the organization is legally
+                located.
+            country (:obj:`str`): The two letter ISO abbreviation for the
+                country.
+        """
         self.org_name = org_name
         self.org_unit = org_unit
         self.city = city

cfssl/tests/test_cfssl.py

@@ -86,13 +86,17 @@ def test_new_key(self, call):
         expect = {
             'hosts': [mock.MagicMock()],
             'names': [mock.MagicMock()],
-            'common_name': 'cn'
+            'common_name': 'cn',
+            'ca': mock.MagicMock(),
+            'key': mock.MagicMock(),
         }
         self.cfssl.new_key(**expect)
         expect['CN'] = 'cn'
         del expect['common_name']
         expect['hosts'][0]= expect['hosts'][0].to_api()
         expect['names'][0] = expect['names'][0].to_api()
+        expect['ca'] = expect['ca'].to_api()
+        expect['key'] = expect['key'].to_api()
         call.assert_called_once_with(
             'newkey', 'POST', data=expect
         )

cfssl/tests/test_policy_sign.py

@@ -5,6 +5,8 @@
 import mock
 import unittest
 
+from datetime import timedelta
+
 from ..models.policy_sign import PolicySign
 
 
@@ -16,7 +18,7 @@ def setUp(self):
             'name': 'name',
             'usage_policies': [mock.MagicMock()],
             'auth_policy': mock.MagicMock(),
-            'expire_minutes': 1234,
+            'expire_delta': timedelta(seconds=1234),
         }
         self.model = PolicySign(**self.vals)
 
@@ -25,7 +27,7 @@ def test_to_api(self):
         res = self.model.to_api()
         expect = {
             'auth_key': self.vals['auth_policy'].name,
-            'expiry': '1234m',
+            'expiry': '1234s',
             'usages': [self.vals['usage_policies'][0].to_api()],
         }
         self.assertDictEqual(res, expect)