% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{article}
\usepackage{amsmath,amssymb}
\usepackage{iftex}
\ifPDFTeX
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math} % this also loads fontspec
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
\usepackage{lmodern}
\ifPDFTeX\else
  % xetex/luatex font selection
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
\ifLuaTeX
  \usepackage{selnolig}  % disable illegal ligatures
\fi
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\urlstyle{same}
\hypersetup{
  pdftitle={ssl-certificates},
  hidelinks,
  pdfcreator={LaTeX via pandoc}}

\title{ssl-certificates}
\author{}
\date{}

\begin{document}
\maketitle

\hypertarget{ssl-certificates}{%
\section{ssl-certificates}\label{ssl-certificates}}

SSL Certificates \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#

We use certificates to certify some of our domain names. The certificate
is used to build trust and prove an identity.

A certificate builds trust because of the ``background check'' involved
during procurement.

The integrity of our identity is proven because only we have the private
key. The private key may be used to generate a CSR (Certificate Signing
Request). The CSR may be provided to a 3rd party to generate and sign us
a certificate.

The sole ownership of a private key prevents both man-in-the-middle
attacks and domain-name identity spoofing in regards to SSL.

.. contents::

\hypertarget{create-a-snakeoil-cert-for-testing}{%
\section{Create a snakeoil cert for
testing}\label{create-a-snakeoil-cert-for-testing}}

Even the `minimal' flavour of Ubuntu has \emph{ssl-cert} package
pre-installed.

The files are auto-generated and installed here:

\begin{itemize}
\tightlist
\item
  /etc/ssl/certs/ssl-cert-snakeoil.pem
\item
  /etc/ssl/private/ssl-cert-snakeoil.key
\end{itemize}

Regenerate snakeoil certs, if needed, with the following command:

.. code-block:: bash

sudo make-ssl-cert generate-default-snakeoil --force-overwrite

\hypertarget{request-an-internally-signed-cert}{%
\section{Request an internally signed
cert}\label{request-an-internally-signed-cert}}

\begin{enumerate}
\item
  \texttt{Generate\ a\ private\ key\ and\ CSR}\_
\item
  send an email to Netadmins:

  \begin{itemize}
  \tightlist
  \item
    attach the CSR (NOT THE PRIVATE KEY)
  \item
    provide the domain name desired for certification
  \item
    ask for an \emph{internally} signed CV CA certificate
  \end{itemize}
\end{enumerate}

Netadmins will respond back with the certificate.

\hypertarget{request-an-externally-signed-cert}{%
\section{Request an externally signed
cert}\label{request-an-externally-signed-cert}}

\begin{enumerate}
\item
  \texttt{Generate\ a\ private\ key\ and\ CSR}\_
\item
  send an email to Netadmins:

  \begin{itemize}
  \tightlist
  \item
    attach the CSR (NOT THE PRIVATE KEY)
  \item
    provide the domain name desired for certification
  \item
    ask for an \emph{externally} signed GoDaddy CA certificate
  \end{itemize}
\end{enumerate}

Netadmins will respond back after procurement with the certificate.

\hypertarget{generate-a-private-key-and-csr}{%
\section{Generate a private key and
CSR}\label{generate-a-private-key-and-csr}}

\begin{enumerate}
\item
  Verify or install openssl package on host

  Is openssl in your path?

  .. code-block:: bash

  which openssl

  Install openssl if missing:

  .. code-block:: bash

  sudo apt-get install openssl
\item
  Create a file using the following template.

  Only the first line in the file (siteName = ) should be altered to
  match the domain name intended for certification. The filename should
  be the domain.to.be.certified.tmpl, for example:
  secure.foxhop.net.tmpl

  .. code-block:: ini

\begin{verbatim}
siteName = secure.foxhop.net
r = .

[ req ]
default_bits = 2048
default_keyfile = ${siteName}.key
distinguished_name = req_distinguished_name
prompt = no

[ req_distinguished_name ]
C = US
ST = CT
L = New London
O = Foxhop.net
OU = Foxhop.net, New London
CN = ${siteName}
\end{verbatim}
\item
  Generate a private key and a CSR for the host to be certified by using
  the template that we generated above; For example (secure.foxhop.net):

  .. code-block:: bash

  openssl req -new -config secure.foxhop.net.tmpl -out
  secure.foxhop.net.csr
\end{enumerate}

This process will prompt for a passphrase to protect the private key.

\begin{enumerate}
\item
  Verify that the following files were created:

  \begin{itemize}
  \tightlist
  \item
    .csr
  \item
    .key
  \end{itemize}
\item
  Store these details in a pass or keepass entry:

  \begin{itemize}
  \tightlist
  \item
    document the private key's passphrase in the password field
  \item
    on the ``Advanced'' attach the tmpl, csr, key, and crt files
  \end{itemize}
\end{enumerate}

\hypertarget{view-the-csr-data}{%
\section{View the CSR data}\label{view-the-csr-data}}

We may want to validate the data in a CSR before submission for
certification. To display a CSR's data to standard out, run the
following command:

.. code-block:: bash

\begin{verbatim}
openssl req -in secure.foxhop.net.csr -noout -text
\end{verbatim}

\hypertarget{remove-passphrase-from-a-private-key}{%
\section{Remove passphrase from a private
key}\label{remove-passphrase-from-a-private-key}}

We need to remove the passphrase from the openSSL private key for use in
deployment; Otherwise everytime the webserver is restarted it will
prompt for the keys password.

Example command:

.. code-block:: bash

\begin{verbatim}
# make a copy
cp secure.foxhop.net.key secure.foxhop.net.key.orig
# strip passphrase
openssl rsa -in secure.foxhop.net.key.orig -out secure.foxhop.net.key
# clean up orig after testing
rm secure.foxhop.net.key.orig
\end{verbatim}

\hypertarget{ssl-offloading}{%
\section{SSL Offloading}\label{ssl-offloading}}

SSL Offloading is the practice of using a proxy or load balancer to
manage the SSL certificates, keys, and sessions for none or many
upstream nodes.

The BigIP is capable of SSL Offloading. For SSL Offloading to occur we
must load our domain's SSL certificate \emph{AND} private key into the
BigIP certificate store.

BigIP would then gain responsibility of creating an SSL tunnel or
session between the Internet user and the edge of our corporate network.
the VIP.

Optionally the traffic between the VIP and it's upstream nodes (internal
network) may also be wrapped by SSL.

\textbf{when should it be used?}

If we want a central place to configure SSL for a pool of many nodes.
Netadmins create a BigIP irule to manage SSL communications. The
upstream nodes could run just plain HTTP (port 80). Less complicated
configuration on each of the webserver nodes.

\textbf{example}

An example closer to home deploying Pyramid behind nginx proxy. Nginx in
this case does the SSL Offloading for upstream waitress/paster nodes.
The communication between users and Nginx could be SSL wrapped while the
communication between nginx and the upstream waitress/paster nodes could
remain plain http. Many times we can get away with this because the
paster nodes are bound and listening only to localhost, thus
``firewalled'' from the rest of the network.

\hypertarget{verify-ssl-chain}{%
\section{Verify SSL chain}\label{verify-ssl-chain}}

Run this command and paste in your signed certificate for your host.

.. code-block:: bash

openssl x509 -noout -issuer\_hash

Document the resulting hash.

Then make sure that hash exist somewhere in the certificate chain, by
running this command on each cert in the chain until you find a match.
If you don't find a match you are using the wrong chain!

.. code-block:: bash

openssl x509 -noout -hash

You can also use this command to get information about the SSL chain:

.. code-block:: bash

openssl s\_client -connect :443

\hypertarget{definitions}{%
\section{Definitions}\label{definitions}}

Transitive Trust A trusts B, B trusts C, therefore A may trust C

Self-signed Certificate This certificate was signed by the organization
who created it.

Snakeoil Certificate A ``snakeoil'' self-signed cert is a great example
of a singular identity certifying itself. Outsiders may not trust a
snakeoil cert because it lacks is not attached to a domain name.
Snakeoil certs are excellent for testing! ``\,````I Trust myself''``\,''

Internally Signed Certificate An ``internal'' certificate signed by the
Classified Ventures (CV) Certificate Authority (CA) provides trust
within the company. Employees of CV may trust an internal cert because
it has meta-data and is attached to a domain name. The Internet will not
trust an internal cert because the CV CA itself was not certified by a
trusted outside identity. From inside the organization, this is a signed
cert. From outside the organization this is a self-signed cert. Internal
certs are excellent for internal only servers and services!
``\,````Employees trust the CV CA, CV CA trusts my-server, therefore
employees may trust my-server.''``\,''

externally signed certificate An ``external'' certificate is signed by a
trusted identity outside of the requesting organization. There are many
trusted identities who perform this service. This is a popular choice
among Internet websites because many of the trusted external Certificate
Authorities have their keys pre-loaded into web browsers. The pre-loaded
key relieves friction on the end-users, they do not need to manually
review or install anything.\\
``\,````You trust XYZ org, XYZ org trusts my-server, therefore you may
trust my-server.''``\,''

private key This is the very sensitive and private portion of the
certificate that must remain a secret in order for the SSL wrapped
service to remain secure.

\end{document}
