From 11b00cd32d895d4bf9d57ab21e040586282774ca Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 13 Jul 2015 21:12:39 -0400 Subject: Fixed #2091 -- describe how to generate a CSR. --- docs/x509/tutorial.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/x509/tutorial.rst (limited to 'docs/x509/tutorial.rst') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst new file mode 100644 index 00000000..565b6d3f --- /dev/null +++ b/docs/x509/tutorial.rst @@ -0,0 +1,77 @@ +Tutorial +======== + +X.509 certificates are used to authenticate clients on servers. The most common +use case is for webservers using HTTPS. + +Creating a Certificate Signing Request (CSR) +-------------------------------------------- + +When obtaining a certificate from a certificate authority (CA), the usual +workflow is: + +1. You generate a private/public key pair. +2. You create a request for a certificate, which is signed by your key (to prove + that you own that key). +3. You give your CSR to a CA (but *not* the private key). +4. The CA validates that you own the resource (e.g. domain) you want a + certificate for. +5. The CA gives you a certificate, signed by them. Which identifies your public + key, and the resource you are authenticated for. + +If you want to obtain a certificate from a typical commercial CA, here's how. +First, you'll need to generate a private key, we'll generate an RSA key (these +are the most common types of keys on the web right now): + +.. code-block:: pycon + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import serialization + >>> from cryptography.hazmat.primitives.asymmetric import rsa + >>> # Generate our key + >>> key = rsa.generate_private_key( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> # Write our key to disk for safe keeping + >>> with open("path/to/store/key.pem") as f: + ... f.write(key.private_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.PrivateFormat.TraditionalOpenSSL, + ... encryption_algorithm=serialization.BestAvailableEncryption(b"passphrase"), + ... )) + +If you've already generated a key you can load it with +:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`. + +Next we need to generate a certificate signing request. A typical CSR contains a +few details: + +* Information about our public key (including a signature of the entire body). +* Information about who *we* are. +* Information about what domains this certificate is for. + +.. code-block:: pycon + + >>> from cryptography import x509 + >>> # Generate a CSR + >>> csr = x509.CertificateSigningRequestBuilder().subject_name(x509.Name([ + ... # Provide various details about who we are. + ... x509.NameAttribute(x509.OID_COUNTRY_NAME, u"US"), + ... x509.NameAttribute(x509.OID_STATE_OR_PROVINCE_NAME, u"CA"), + ... x509.NameAttribute(x509.OID_LOCALITY_NAME, u"San Francisco"), + ... x509.NameAttribute(x509.OID_ORGANIZATION_NAME, u"My Company"), + ... x509.NameAttribute(x509.COMMON_NAME, u"mysite.com"), + ... ])).add_extension(x509.SubjectAlternativeName([ + ... # Describe what sites we want this certificate for. + ... x509.DNSName(u"mysite.com"), + ... x509.DNSName(u"www.mysite.com"), + ... x509.DNSName(u"subdomain.mysite.com"), + ... # Sign the CSR with our private key. + ... ])).sign(key, hashes.SHA256(), default_backend()) + >>> # Write our CSR out to disk. + >>> with open("path/to/csr.pem") as f: + ... f.write(csr.public_bytes(serialization.Encoding.PEM)) + +Now we can give our CSR to a CA, who will give a certificate to us in return. -- cgit v1.2.3 From 0c91ddc5141ee56633397f1c3b7878f31524f90f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 13 Jul 2015 21:15:03 -0400 Subject: spelling --- docs/x509/tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/x509/tutorial.rst') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 565b6d3f..e2b64175 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -2,13 +2,13 @@ Tutorial ======== X.509 certificates are used to authenticate clients on servers. The most common -use case is for webservers using HTTPS. +use case is for web servers using HTTPS. Creating a Certificate Signing Request (CSR) -------------------------------------------- When obtaining a certificate from a certificate authority (CA), the usual -workflow is: +flow is: 1. You generate a private/public key pair. 2. You create a request for a certificate, which is signed by your key (to prove -- cgit v1.2.3 From 5bcd8e88c4e81d1a1581213118fea6a8ff416cfb Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 13 Jul 2015 21:17:31 -0400 Subject: line length and grammar --- docs/x509/tutorial.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/x509/tutorial.rst') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index e2b64175..69cc5be0 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -11,13 +11,15 @@ When obtaining a certificate from a certificate authority (CA), the usual flow is: 1. You generate a private/public key pair. -2. You create a request for a certificate, which is signed by your key (to prove - that you own that key). +2. You create a request for a certificate, which is signed by your key (to + prove that you own that key). 3. You give your CSR to a CA (but *not* the private key). 4. The CA validates that you own the resource (e.g. domain) you want a certificate for. -5. The CA gives you a certificate, signed by them. Which identifies your public +5. The CA gives you a certificate, signed by them, which identifies your public key, and the resource you are authenticated for. +6. You configure your server to use that certificate, combined with your + private key, to server traffic. If you want to obtain a certificate from a typical commercial CA, here's how. First, you'll need to generate a private key, we'll generate an RSA key (these @@ -45,8 +47,8 @@ are the most common types of keys on the web right now): If you've already generated a key you can load it with :func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`. -Next we need to generate a certificate signing request. A typical CSR contains a -few details: +Next we need to generate a certificate signing request. A typical CSR contains +a few details: * Information about our public key (including a signature of the entire body). * Information about who *we* are. -- cgit v1.2.3 From d02bc12c7e688363a378ae6fe7598a446f27d082 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 13 Jul 2015 21:18:56 -0400 Subject: fixed indent --- docs/x509/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/x509/tutorial.rst') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 69cc5be0..54a692d2 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -42,7 +42,7 @@ are the most common types of keys on the web right now): ... encoding=serialization.Encoding.PEM, ... format=serialization.PrivateFormat.TraditionalOpenSSL, ... encryption_algorithm=serialization.BestAvailableEncryption(b"passphrase"), - ... )) + ... )) If you've already generated a key you can load it with :func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`. -- cgit v1.2.3 From 9ca4851c33cbe7790b280bcafc0c89b96883f48b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 16 Jul 2015 07:03:40 -0400 Subject: fix --- docs/x509/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/x509/tutorial.rst') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 54a692d2..bcaec809 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -45,7 +45,7 @@ are the most common types of keys on the web right now): ... )) If you've already generated a key you can load it with -:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`. +:func:`~cryptography.hazmat.primitives.serialization.load_pem_private_key`. Next we need to generate a certificate signing request. A typical CSR contains a few details: -- cgit v1.2.3