xsumsa01_tls_interoperability-30-prilohy-appendices.tex

\chapter{CD Contents}
    The attached CD contains the source code of all components implemented by
    this thesis -- the SSL/TLS test suite, the auxiliary scripts of the
    continuous integration system, and the text part of the thesis itself.

% RFC5246 - TLS alert messages
\chapter{TLS Alerts}
    \noindent\begin{tabularx}{\linewidth}{@{}l l X}
    \caption{TLS Alerts}\label{tab:tls-alerts} \\
    \toprule
    \textbf{Alert} & \textbf{ID} & \textbf{Description} \\
    \midrule
    \endhead
    \texttt{close\_notify}                & 0   & The sender notifies the recipient that it will not send any more messages
                                                  on this connection. \\
    \texttt{unexpected\_message}          & 10  & An inappropriate message was received. This alert is always fatal. \\
    \texttt{bad\_record\_mac}             & 20  & The sender received a record with an incorrect MAC. This alert is always fatal. \\
    \texttt{decryption\_failed\_RESERVED} & 21  & Used in some earlier versions of TLS, must not be sent by compliant implementations. \\
    \texttt{record\_overflow}             & 22  & A \texttt{TLSCiphertext} record was received that had a length more than $2^{14}+2048$ bytes or
                                                  a record decrypted to a \texttt{TLSCompressed} record with more than $2^{14}+1024$ bytes. This alert
                                                  is always fatal. \\
    \texttt{decompression\_failure}       & 30  & The decompression function received improper input. This alert is always fatal. \\
    \texttt{handshake\_failure}           & 40  & The sender was unable to negotiate an acceptable set of security parameters given
                                                  the options available. This alert is always fatal. \\
    \texttt{no\_certificate\_RESERVED}    & 41  & This alert was used in SSLv3 but it no longer used in any TLS version. \\
    \texttt{bad\_certificate}             & 42  & The sender notifies the recipient that the provided certificate is corrupt. \\
    \texttt{unsupported\_certificate}     & 43  & The sender notifies the recipient that the provided certificate is of an unsupported type. \\
    \texttt{certificate\_revoked}         & 44  & The sender notifies the recipient that the provided certificate was revoked by the issuing authority. \\
    \texttt{certificate\_expired}         & 45  & The sender notifies the recipient that the provided certificate has expired or is no longer valid. \\
    \texttt{certificate\_unknown}         & 46  & The sender notifies the recipient that some unspecified issue occured during the certificate processing,
                                                  rendering it unacceptable. \\
    \texttt{illegal\_parameter}           & 47  & A field in the handshake was out of range or inconsistent with other fields. This alert is always fatal. \\
    \texttt{unknown\_ca}                  & 48  & The received certificate could not be validated, because the CA certificate could not be located or could
                                                  not be matched with a known, trusted CA. This alert is always fatal. \\
    \texttt{access\_denied}               & 49  & A valid certificate was received, but when access control was applied, the sender decided not to proceed
                                                  with negotiation. This alert is always fatal. \\
    \texttt{decode\_error}                & 50  & The received message could not be decoded because some field was out of the specified range or length of
                                                  the message was incorrect. This alert is always fatal. \\
    \texttt{decrypt\_error}               & 51  & A handshake cryptographic operation failed. This alert is always fatal. \\
    \texttt{export\_restriction\_RESERVED}& 60  & Used in some earlier versions of TLS, must not be sent by compliant implementations. \\
    \texttt{protocol\_version}            & 70  & The protocol version the client has attempted to negotiate is recognized but not supported.
                                                  This alert is always fatal. \\
    \texttt{insufficient\_security}       & 71  & The server requires more secure ciphers than those supported by the client. This alert is always fatal. \\
    \texttt{internal\_error}              & 80  & An internal error occured, unrelated to the peer or corectness of the protocol. This alert is always fatal. \\
    \texttt{user\_canceled}               & 90  & This handshake is being canceled for some reason unrelated to a protocol failure. This alert should be followed
                                                  by a \texttt{close\_notify}. \\
    \texttt{no\_renegotiation}            & 100 & The peer should respond with this alert when renegotiation is not appropriate regarding the current connection
                                                  state. This alert is always a warning. \\
    \texttt{unsupported\_extension}       & 110 & Sent by the client when the received \texttt{ServerHello} message contains an extension not sent by the client
                                                  in its \texttt{ClientHello} message. This alert is always fatal.
    \end{tabularx}


\chapter{Test Plan} \label{ref:test-plan}
\section{Test Plan Identifier}
    TLS/SSL Interoperability Test Plan v0.1

\section{References}
    \begin{itemize}
        \item IEEE 829-2008 Standard for Software Test
        Documentation~\footnote{http://standards.ieee.org/findstds/standard/829-2008.html}
        \item Common Criteria \@ access.redhat.com~\footnote{https://access.redhat.com/blogs/766093/posts/1976523}
    \end{itemize}

\section{Introduction}
    The main goal of this test plan is to ensure interoperability of supported
    SSL/TLS libraries on CentOS/RHEL and Fedora systems. The testing itself involves
    verification of ability to comunicate between two libraries using various
    combination of cipher suites, connection settings and extensions.

\section{Test Items}
\subsection{Components}
    \begin{itemize}
        \item OpenSSL
        \item NSS
        \item GnuTLS
    \end{itemize}

\subsection{Environments: Releases and Architectures}
    Due to limitations of the current CI all tests are run on x86\_64 architeture
    only. Nevertheless, they should work on all architectures supported by
    the underlying operating system.

    \begin{itemize}
        \item CentOS 6 and 7 (latest releases)
        \item Fedora (latest release)
    \end{itemize}

\section{Software Risk Issues}
    \begin{itemize}
        \item Package rebases can cause unexpected behavior and/or regressions
              -- thorough test results analysis is necessary
    \end{itemize}

\section{Features to be Tested}
    All features are tested using TLSv1.1 and TLSv1.2 protocols with all supported
    cipher suites by the involved parties.

    \begin{itemize}
        \item Basic interoperability
        \item Inteoperability with client certificates
        \item Session renegotiation
        \item Session renegotiation with client certificates
        \item Session resumption using Session ID
        \item Session resumption using Session ID with client certificates
        \item Session resumption using TLS SessionTicket Extension
        \item Session resumption using TLS SessionTicket Extension with client certificates
        \item SignatureAlgorithms TLS Extension
    \end{itemize}

\section{Features not to be Tested}
    \begin{itemize}
        \item Sanity of the available options
        \item Regressions
        \item Security of the implementation
    \end{itemize}

\section{Approach}
    All testing is done by Bash scripts using
    Beakerlib~\footnote{https://github.com/beakerlib/beakerlib} testing framework.
    This framework manages log collection and results reporting and automatizes
    the entire testing process.

    Each library has a set of utilites, which are used for the interoperability
    testing itself:

    \begin{itemize}
        \item \textbf{OpenSSL} -- \texttt{openssl} utility (package \textit{openssl})
        \item \textbf{NSS} -- utilities \texttt{selfserv}, \texttt{tstclnt},
              \texttt{strsclnt}, etc. (package \textit{nss-tools})
        \item \textbf{GnuTLS} -- utilities \texttt{gnutls-cli} and
              \texttt{gnutls-serv} (package \textit{gnutls-utils})
    \end{itemize}

    All libraries are tested in pairs in a client-server fashion, where each
    phase tests a specific combination of parameters (specific cipher suite,
    protocol, extension, etc.).

    Each failure is investigated and if it is a library issue, it is reported
    to the upstream and/or to a respective downstream bug tracker.

\section{Item Pass/Fail Criteria}
    A handshake is completed successfully in all cases with all requested
    settings set, i.e.:
    \begin{itemize}
        \item Expected cipher suite is used
        \item Expected protocol is used
        \item A specific extension requested in Client/Server Hello is used
        \item Session is correctly resumed when session resumption is requested
        \item Session renegotiation is successful
    \end{itemize}

\section{Test Cases}
    \noindent\begin{tabularx}{\linewidth}{@{}X c c c }
    \caption{Test case matrix}\label{tab:test-plan-matrix} \\
    \toprule
    \textbf{Test case} & \textbf{CentOS 6} & \textbf{CentOS 7} & \textbf{Fedora} \\
    \midrule
    \endhead
    gnutls/renegotiation-with-NSS                 &   & x & x \\
    gnutls/renegotiation-with-OpenSSL             &   & x & x \\
    gnutls/resumption-with-NSS                    &   & x & x \\
    gnutls/resumption-with-OpenSSL                &   & x & x \\
    gnutls/signature\_algorithms-with-OpenSSL     &   & x & x \\
    gnutls/softhsm-integration                    &   & x & x \\
    gnutls/TLSv1-2-with-NSS                       & x & x & x \\
    gnutls/TLSv1-2-with-OpenSSL                   & x & x & x \\
    \hline
    nss/CC-nss-with-gnutls                        &   & x & x \\
    nss/CC-nss-with-openssl                       &   & x & x \\
    nss/Interoperability-with-OpenSSL             & x & x & x \\
    nss/renego-and-resumption-NSS-with-OpenSSL    & x & x & x \\
    \hline
    openssl/CC-openssl-with-gnutls                &   & x & x \\
    \end{tabularx}

    \noindent Brief description of all test cases can be found
    in Appendix~\ref{ref:test-case-description}.

\section{Suspension Criteria and Resumption Requirements}
    Testing will be suspended if any of the following criteria are met:
    \begin{itemize}
        \item Underlying operating system is not installable
        \item Existing issues may prevent execution of the test suite
    \end{itemize}

    Testing will be resumed when all mentioned issues are resolved.

\section{Test Deliverables}
    The test results generated by Beakerlib will be stored in the CI and
    all failures will be analysed. The analysis itself can yield following
    results:

    \begin{itemize}
        \item Failure caused by the tested component -- a new bug will be reported
        \item Failure caused by the test -- the test case will be fixed
        \item Failure caused by an error in the infrastructure/environment --
              the test case will be run again
    \end{itemize}

\section{Remaining Test Tasks}
    Extend test coverage to other TLS extensions:
    \begin{itemize}
        \item extended\_master\_secret extension
        \item encrypt\_then\_mac extension
        \item etc.
    \end{itemize}

    Implementation of tests for these extension is currently blocked on the
    limited support of these extensions by the utilities of SSL/TLS libraries.

    Testing of some recent algorithms for TLS should be considered as well
    (e.g. \textit{ChaCha20-Poly1305}~\footnote{https://www.rfc-editor.org/rfc/rfc7905.txt}).
    This will have to wait until the SSL/TLS libraries provide support for
    these algorithms.

\section{Environmental Needs}
\subsection{Hardware}
    Testing will be performed on x86\_64 architecture as it is the only architecture
    supported by the current CI. Particular hardware configuration is not important
    for the testing itself.

\subsection{Software}
    No special configuration of the operating system is needed. All packages
    necessary for the testing will be installed by the CI system.

\section{Staffing and Training needs}
    N/A

\section{Responsibilities}
    \begin{itemize}
        \item František Šumšal
        \item Stanislav Židek
        \item Hubert Kario
    \end{itemize}

\section{Schedule}
    Currently all tests are being executed when a new PR or commit is pushed
    to the test repository, periodically every week on the latest versions
    of supported systems, and on-demand on a user-specified library repository.

    Long term plans include delivering all test cases to both downstream and
    upstream, so possible failures can be detected before the library itself
    is released.

\section{Approvals}
    \begin{itemize}
        \item Stanislav Židek
    \end{itemize}

\chapter{Test Cases Description} \label{ref:test-case-description}
    Note: the term "various cipher suites" used in following sections describes
    cipher suites using different key exchange algorithms (RSA, DHE, ECDHE),
    authentication algorithms (RSA, DSA, ECDSA), block cipher algorithms
    (3DES, AES) and message authentication algorithms (SHA). Mentioned
    algorithms may also differ in modes (AES-GCM, AES-CBC, \dots) and sizes
    (AES-128, AES-256, SHA-1, SHA-256, \dots).
\section{GnuTLS}
    \begin{description}
        \item[renegotiation-with-NSS] \hfill \\
            Test session renegotiation between GnuTLS and NSS libraries using
            various cipher suites, TLSv1.1 and TLSv1.2 protocols, and
            client certificates.
        \item[renegotiation-with-OpenSSL] \hfill \\
            Test session renegotiation between GnuTLS and OpenSSL libraries using
            various cipher suites, TLSv1.1 and TLSv1.2 protocols, and
            client certificates.
        \item[resumption-with-NSS] \hfill \\
            Test session resumption between GnuTLS and NSS libraries using
            various cipher suites, TLSv1.1 and TLSv1.2 protocols, and
            client certificates. The resumption itself is tested using both
            Session IDs and SessionTicket extension.
        \item[resumption-with-OpenSSL] \hfill \\
            Test session resumption between GnuTLS and OpenSSL libraries using
            various cipher suites, TLSv1.1 and TLSv1.2 protocols, and
            client certificates. The resumption itself is tested using both
            Session IDs and SessionTicket extension.
        \item[signature\_algorithms-with-OpenSSL] \hfill \\
            Test signature\_algorithms extension in communication between
            GnuTLS and OpenSSL libraries with and without client certificates.
            This extension is present only in TLSv1.2 and higher.
            As this extension
            has to be explicitly enabled, it is currently tested only in
            this combination of libraries, due to lack of support in testing
            utilities provided by the libraries.
        \item[TLSv1-2-with-NSS] \hfill \\
            Verify interoperability of GnuTLS with NSS using TLSv1.2 protocol
            with various cipher suites.
        \item[TLSv1-2-with-OpenSSL] \hfill \\
            Verify interoperability of GnuTLS with OpenSSL using TLSv1.2 protocol
            with various cipher suites.
    \end{description}
\section{NSS}
    \begin{description}
        \item[CC-nss-with-gnutls] \hfill  \\
            Test interoperability of cipher suites relevant for Common Criteria
            certification between NSS and GnuTLS libraries with and without
            client certificates.
        \item[CC-nss-with-openssl] \hfill  \\
            Test interoperability of cipher suites relevant for Common Criteria
            certification between NSS and OpenSSL libraries with and without
            client certificates.
        \item[Interoperability-with-OpenSSL] \hfill  \\
            Test interoperability between NSS and OpenSSL libraries using
            certificates generated by NSS (all other tests use certificates
            generated by OpenSSL). This test is currently under heavy
            refactoring as it was originally developed for RHEL 6.
        \item[renego-and-resumption-NSS-with-OpenSSL] \hfill  \\
            Test session renegotiaton and session resumption between NSS and
            OpenSSL libraries. Both methods are tested using various cipher
            suites, TLSv1.1 and TLSv1.2 protocols, and client certificates.
            Moreover, session resumption is testes using both Session IDs and
            SessionTicket extension.
    \end{description}
\section{OpenSSL}
    \begin{description}
        \item[CC-openssl-with-gnutls] \hfill \\
            Test interoperability of cipher suites relevant for Common Criteria
            certification between OpenSSL and GnuTLS libraries with and without
            client certificates.
    \end{description}