Add alias for Certificate serial as serial number (#2950)

* Add alias for Certificate serial as serial number

* Adding deprecation to utils

* Now with catch warnings and proper vers

5 files changed, 53 insertions, 11 deletions

diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index e8ce1d84..1d521e34 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -125,7 +125,7 @@ Loading Certificates
         >>> from cryptography import x509
         >>> from cryptography.hazmat.backends import default_backend
         >>> cert = x509.load_pem_x509_certificate(pem_data, default_backend())
-        >>> cert.serial
+        >>> cert.serial_number
         2
 
 .. function:: load_der_x509_certificate(data, backend)
@@ -273,7 +273,7 @@ X.509 Certificate Object
             >>> cert.fingerprint(hashes.SHA256())
             '\x86\xd2\x187Gc\xfc\xe7}[+E9\x8d\xb4\x8f\x10\xe5S\xda\x18u\xbe}a\x03\x08[\xac\xa04?'
 
-    .. attribute:: serial
+    .. attribute:: serial_number
 
         :type: int
 
@@ -281,7 +281,7 @@ X.509 Certificate Object
 
         .. doctest::
 
-            >>> cert.serial
+            >>> cert.serial_number
             2
 
     .. method:: public_key()
@@ -2197,7 +2197,7 @@ instances. The following common OIDs are available as constants.
 
         Corresponds to the dotted string ``"2.5.4.5"``. This is distinct from
         the serial number of the certificate itself (which can be obtained with
-        :func:`~cryptography.x509.Certificate.serial`).
+        :func:`~cryptography.x509.Certificate.serial_number`).
 
     .. attribute:: SURNAME
 
diff --git a/src/cryptography/hazmat/backends/openssl/x509.py b/src/cryptography/hazmat/backends/openssl/x509.py
index 71a2fb78..94a81ce6 100644
--- a/src/cryptography/hazmat/backends/openssl/x509.py
+++ b/src/cryptography/hazmat/backends/openssl/x509.py
@@ -5,6 +5,7 @@
 from __future__ import absolute_import, division, print_function
 
 import operator
+import warnings
 
 from cryptography import utils, x509
 from cryptography.exceptions import UnsupportedAlgorithm
@@ -58,6 +59,14 @@ class _Certificate(object):
 
     @property
     def serial(self):
+        warnings.warn(
+            "Certificate serial is deprecated, use serial_number instead.",
+            utils.DeprecatedIn10
+        )
+        return self.serial_number
+
+    @property
+    def serial_number(self):
         asn1_int = self._backend._lib.X509_get_serialNumber(self._x509)
         self._backend.openssl_assert(asn1_int != self._backend._ffi.NULL)
         return _asn1_integer_to_int(self._backend, asn1_int)
diff --git a/src/cryptography/utils.py b/src/cryptography/utils.py
index 4c006278..d3e845ab 100644
--- a/src/cryptography/utils.py
+++ b/src/cryptography/utils.py
@@ -12,9 +12,11 @@ import sys
 import warnings
 
 
-# the functions deprecated in 1.0 are on an arbitrarily extended deprecation
-# cycle and should not be removed until we agree on when that cycle ends.
+# the functions deprecated in 1.0 and 1.4 are on an arbitrarily extended
+# deprecation cycle and should not be removed until we agree on when that cycle
+# ends.
 DeprecatedIn10 = DeprecationWarning
+DeprecatedIn14 = DeprecationWarning
 
 
 def read_only_property(name):
diff --git a/src/cryptography/x509/base.py b/src/cryptography/x509/base.py
index 4a22ed02..8e3f9668 100644
--- a/src/cryptography/x509/base.py
+++ b/src/cryptography/x509/base.py
@@ -69,6 +69,12 @@ class Certificate(object):
         """
 
     @abc.abstractproperty
+    def serial_number(self):
+        """
+        Returns certificate serial number
+        """
+
+    @abc.abstractproperty
     def version(self):
         """
         Returns the certificate version
diff --git a/tests/test_x509.py b/tests/test_x509.py
index aaeefae9..ebe6dc50 100644
--- a/tests/test_x509.py
+++ b/tests/test_x509.py
@@ -8,6 +8,7 @@ import binascii
 import datetime
 import ipaddress
 import os
+import warnings
 
 from pyasn1.codec.der import decoder
 
@@ -486,11 +487,35 @@ class TestRSACertificate(object):
             backend
         )
         assert isinstance(cert, x509.Certificate)
-        assert cert.serial == 11559813051657483483
+        assert cert.serial_number == 11559813051657483483
         fingerprint = binascii.hexlify(cert.fingerprint(hashes.SHA1()))
         assert fingerprint == b"2b619ed04bfc9c3b08eb677d272192286a0947a8"
         assert isinstance(cert.signature_hash_algorithm, hashes.SHA1)
 
+    def test_cert_serial_number(self, backend):
+        cert = _load_cert(
+            os.path.join("x509", "PKITS_data", "certs", "GoodCACert.crt"),
+            x509.load_der_x509_certificate,
+            backend
+        )
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always", utils.DeprecatedIn10)
+            assert cert.serial == 2
+            assert cert.serial_number == 2
+
+    def test_cert_serial_warning(self, backend):
+        cert = _load_cert(
+            os.path.join("x509", "PKITS_data", "certs", "GoodCACert.crt"),
+            x509.load_der_x509_certificate,
+            backend
+        )
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always", utils.DeprecatedIn10)
+            with pytest.deprecated_call():
+                cert.serial
+
     def test_load_der_cert(self, backend):
         cert = _load_cert(
             os.path.join("x509", "PKITS_data", "certs", "GoodCACert.crt"),
@@ -498,7 +523,7 @@ class TestRSACertificate(object):
             backend
         )
         assert isinstance(cert, x509.Certificate)
-        assert cert.serial == 2
+        assert cert.serial_number == 2
         fingerprint = binascii.hexlify(cert.fingerprint(hashes.SHA1()))
         assert fingerprint == b"6f49779533d565e8b7c1062503eab41492c38e4d"
         assert isinstance(cert.signature_hash_algorithm, hashes.SHA256)
@@ -734,7 +759,7 @@ class TestRSACertificate(object):
 
         assert cert.not_valid_before == datetime.datetime(2010, 1, 1, 8, 30)
         assert cert.not_valid_after == datetime.datetime(2030, 12, 31, 8, 30)
-        assert cert.serial == 2
+        assert cert.serial_number == 2
         public_key = cert.public_key()
         assert isinstance(public_key, rsa.RSAPublicKey)
         assert cert.version is x509.Version.v3
@@ -909,7 +934,7 @@ class TestRSACertificate(object):
         # We should recover what we had to start with.
         assert cert.not_valid_before == datetime.datetime(2010, 1, 1, 8, 30)
         assert cert.not_valid_after == datetime.datetime(2030, 12, 31, 8, 30)
-        assert cert.serial == 2
+        assert cert.serial_number == 2
         public_key = cert.public_key()
         assert isinstance(public_key, rsa.RSAPublicKey)
         assert cert.version is x509.Version.v3
@@ -932,7 +957,7 @@ class TestRSACertificate(object):
         # We should recover what we had to start with.
         assert cert.not_valid_before == datetime.datetime(2010, 1, 1, 8, 30)
         assert cert.not_valid_after == datetime.datetime(2030, 12, 31, 8, 30)
-        assert cert.serial == 2
+        assert cert.serial_number == 2
         public_key = cert.public_key()
         assert isinstance(public_key, rsa.RSAPublicKey)
         assert cert.version is x509.Version.v3