Commit 0fc95ebc authored by kelsey's avatar kelsey
Browse files

Initial push of ETS support. See README.ETS.

parent 894da2fb
Loading
Loading
Loading
Loading
+13 −125
Original line number Diff line number Diff line

  LICENSE ISSUES
  ==============

  The OpenSSL toolkit stays under a double license, i.e. both the conditions of
  the OpenSSL License and the original SSLeay license apply to the toolkit.
  See below for the actual license texts.

  OpenSSL License
  ---------------

/* ====================================================================
 * Copyright (c) 1998-2019 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

 Original SSLeay License
 -----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
 * All rights reserved.
 *
 * This package is an SSL implementation written
 * by Eric Young (eay@cryptsoft.com).
 * The implementation was written so as to conform with Netscapes SSL.
 *
 * This library is free for commercial and non-commercial use as long as
 * the following conditions are aheared to.  The following conditions
 * apply to all code found in this distribution, be it the RC4, RSA,
 * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
 * included with this distribution is covered by the same copyright terms
 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
 *
 * Copyright remains Eric Young's, and as such any Copyright notices in
 * the code are not to be removed.
 * If this package is used in a product, Eric Young should be given attribution
 * as the author of the parts of the library used.
 * This can be in the form of a textual message at program startup or
 * in documentation (online or textual) provided with the package.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *    "This product includes cryptographic software written by
 *     Eric Young (eay@cryptsoft.com)"
 *    The word 'cryptographic' can be left out if the rouines from the library
 *    being used are not cryptographic related :-).
 * 4. If you include any Windows specific code (or a derivative thereof) from
 *    the apps directory (application code) you must include an acknowledgement:
 *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
 *
 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * The licence and distribution terms for any publically available version or
 * derivative of this code cannot be changed.  i.e. this code cannot simply be
 * copied and put under another distribution licence
 * [including the GNU Public Licence.]
 */
This repository contains a modified version of OpenSSL 1.1.1d and is
released under the OpenSSL license (see file LICENSE.OPENSSL in this
distribution).

These modifications are neither provided by nor endorsed by the
OpenSSL Project.

For the avoidance of doubt, ETSI and the contributors to this
repository disclaim all warranties and liability the same as if "ETSI
and the contributors to this repository" were substituted for all
occurrences of "THE OpenSSL PROJECT" in the disclaimer found in the
file LICENSE.OPENSSL in this distribution (or at
https://www.openssl.org/source/license-openssl-ssleay.txt).

LICENSE.OPENSSL

0 → 100644
+125 −0
Original line number Diff line number Diff line

  LICENSE ISSUES
  ==============

  The OpenSSL toolkit stays under a double license, i.e. both the conditions of
  the OpenSSL License and the original SSLeay license apply to the toolkit.
  See below for the actual license texts.

  OpenSSL License
  ---------------

/* ====================================================================
 * Copyright (c) 1998-2019 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

 Original SSLeay License
 -----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
 * All rights reserved.
 *
 * This package is an SSL implementation written
 * by Eric Young (eay@cryptsoft.com).
 * The implementation was written so as to conform with Netscapes SSL.
 *
 * This library is free for commercial and non-commercial use as long as
 * the following conditions are aheared to.  The following conditions
 * apply to all code found in this distribution, be it the RC4, RSA,
 * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
 * included with this distribution is covered by the same copyright terms
 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
 *
 * Copyright remains Eric Young's, and as such any Copyright notices in
 * the code are not to be removed.
 * If this package is used in a product, Eric Young should be given attribution
 * as the author of the parts of the library used.
 * This can be in the form of a textual message at program startup or
 * in documentation (online or textual) provided with the package.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *    "This product includes cryptographic software written by
 *     Eric Young (eay@cryptsoft.com)"
 *    The word 'cryptographic' can be left out if the rouines from the library
 *    being used are not cryptographic related :-).
 * 4. If you include any Windows specific code (or a derivative thereof) from
 *    the apps directory (application code) you must include an acknowledgement:
 *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
 *
 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * The licence and distribution terms for any publically available version or
 * derivative of this code cannot be changed.  i.e. this code cannot simply be
 * copied and put under another distribution licence
 * [including the GNU Public Licence.]
 */

README.ETS

0 → 100644
+173 −0
Original line number Diff line number Diff line
Overview and operation
======================

The technical specification ETSI TS 103 523-3 (Enterprise Transport
Security, or ETS) defines a variant of the TLS 1.3 protocol in which
the server uses static (EC)DH keys instead of ephemeral ones.  This
distribution provides an implementation of ETS to support the
evaluation and adoption of the mechanism.

The current support for ETS in this implementation does not consist of
extensions to the existing API, but rather relies on additional
keywords added to the OpenSSL config file format that enable ETS and
configure its operation.

To enable ETS for an existing OpenSSL-based application:

    1. Build and install this distribution.  (Subsequent system-wide
       or per-process configuration of the dynamic linker in the usual
       way may be required, but is beyond the scope of this document)

    2. Generate the static (EC)DH private key material that will be
       used with ETS, and optionally, generate a corresponding
       certificate. (See below)

    3. Prepare a suitable OpenSSL configuration file. (See below)

    4. Launch the application with the environment variable
       OPENSSL_CONF set to point to the OpenSSL configuration file
       prepared above.

Runtime behavior
----------------
When the application is launched, the configuration file pointed to by
the OPENSSL_CONF environment variable will be loaded, and the
ETS-related keywords will be processed.  Any configured key files are
loaded at this point.

During establishment of a TLS 1.3 connection, if ETS is enabled, the
certificate chosen for the connection (via the usual OpenSSL
machinery) is examined to see if it contains visibility information
(as defined in ETSI TS 103 523-3).  If it does, then (EC)DH key
selection is limited to the subset of ETS keys specified via the
OpenSSL configuration file that have corresponding visibility
information in the certificate.  Otherwise, if there is no visibility
information in the certificate, all ETS keys specified via the OpenSSL
configuration file are eligible for selection.

Then, if ETS is enabled and there is an ETS private (EC)DH key
available for the group selected as part of the TLS 1.3 handshake in
progress, that key is used for the connection.  Otherwise, if no ETS
key corresponding to the negotiated group is available, the behavior
depends on the ETS mode selected (see below).


Preparing the OpenSSL configuration file
========================================

This section describes a minimal OpenSSL configuration file suitable
for enabling ETS and configuring its operation.  More information on
the OpenSSL configuration file format in general is located at
https://www.openssl.org/docs/man1.1.1/man5/config.html.

The following contents can be placed in a separate file and customized
as required:

openssl_conf = openssl_init

[openssl_init]
ssl_conf = ssl_section

[ssl_section]
system_default = default_section

[default_section]
# ETSMode is off, optional, or required.
#  - off: normal TLS 1.3 operation (ephemeral (EC)DH keys always used)
#  - optional: use ETS static keys if available, otherwise generate
#              ephemeral ones
#  - required: must use ETS static keys, if no static key is suitable,
               connection will fail
ETSMode = required

# ETSKeyStore is a colon-separated list of file and directory path
# names.  Named directories will be processed recursively.  Files that
# cannot be correctly parsed as PEM files containing private keys will
# be ignored.  Colons appearing in path names can be escaped with '\'.
# ETSKeyStore = static-key-1.pem:static-key-2.pem:/some/dir/with/keys
ETSKeyStore = /etc/pki/ets/private/static


Generating a static (EC)DH key
==============================

The following commands can be used to generate an (EC)DH private key
for use with ETS.

DH groups (example is ffdhe3072)
--------------------------------
openssl genpkey -algorithm DH -pkeyopt dh_param:ffdhe3072 -out mykey.pem

ECDH groups (non-X, example is secp384r1)
-----------------------------------------
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp384r1 -out mykey.pem

ECDH groups (X, example is X25519)
----------------------------------
openssl genpkey -algorithm X25519 -out mykey.pem


Generating a certificate with visibility information
====================================================

This section describes how to generate the ETS key fingerprints
required to construct the visibility information certificate extension
contents as well as how to provide the visibility information to
include in a given certificate to the openssl command used to generate
that certificate.

Generating an ETS key fingerprint
---------------------------------
openssl pkey -pubout -in mykey.pem -out mykey-pub.pem
openssl pkey -pubin -in mykey-pub.pem -noout -ets_fingerprint

Constructing the extension configuration file
---------------------------------------------

This subsection describes how to include visibility information in a
certificate using the X.509 associatedInformation extension
representation.  In the following example, it is assumed that there
are two ETS keys to be included in the visibility information, with
their fingerprints determined as described above.

First, the following contents are placed in a separate file, assumed
to be named vi.conf.

[visibility_information_1]
fingerprint = FORMAT:HEX,OCTETSTRING:00010203040506070809
accessDescription = UTF8:User-supplied string 1
[visibility_information_2]
fingerprint = FORMAT:HEX,OCTETSTRING:0102030405060708090a
accessDescription = UTF8:User-supplied string 2
[visibility_information_attribute_values]
vi1 = SEQUENCE:visibility_information_1
vi2 = SEQUENCE:visibility_information_2
[visibility_information]
associatedInformation = attribute:etsVisibility;SET:visibility_information_attribute_values

Then, the file vi.conf is provided as the extension data specification
to the openssl command used to generate the certificate, using the
generation of a self-signed certificate as an example.

The following command sequence additionally requires a file named
myreq.conf with the contents:

[req]
distinguished_name = req_distinguished_name
prompt = no

[req_distinguished_name]
countryName = ZZ
organizationName = ETS Example
commonName = ets.example.org

The example command sequence is then:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out mycert.key
openssl req -new -batch -nodes -key mycert.key -out mycert.csr -sha256 -config myreq.conf
openssl x509 -req -in mycert.csr -out mycert.crt -signkey mycert.key -days 365 -sha256 \
    -extfile vi.conf -extensions visibility_information

The certificate contents can be examined with:

openssl x509 -text -noout -in mycert.crt
+31 −0
Original line number Diff line number Diff line
/*
 * Copyright (c) 2018-2019 Not for Radio, LLC
 *
 * See the file LICENSE in this distribution.
 *
 */
/*
 * Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 *
@@ -6,6 +12,7 @@
 * in the file LICENSE in the source distribution or at
 * https://www.openssl.org/source/license.html
 */
/* vim: set ts=4 sw=4 et: */

#include <stdio.h>
#include <string.h>
@@ -13,12 +20,14 @@
#include "progs.h"
#include <openssl/pem.h>
#include <openssl/err.h>
#include <openssl/ets_crypto.h>
#include <openssl/evp.h>

typedef enum OPTION_choice {
    OPT_ERR = -1, OPT_EOF = 0, OPT_HELP,
    OPT_INFORM, OPT_OUTFORM, OPT_PASSIN, OPT_PASSOUT, OPT_ENGINE,
    OPT_IN, OPT_OUT, OPT_PUBIN, OPT_PUBOUT, OPT_TEXT_PUB,
    OPT_ETS_FINGERPRINT,
    OPT_TEXT, OPT_NOOUT, OPT_MD, OPT_TRADITIONAL, OPT_CHECK, OPT_PUB_CHECK
} OPTION_CHOICE;

@@ -44,6 +53,7 @@ const OPTIONS pkey_options[] = {
#endif
    {"check", OPT_CHECK, '-', "Check key consistency"},
    {"pubcheck", OPT_PUB_CHECK, '-', "Check public key consistency"},
    {"ets_fingerprint", OPT_ETS_FINGERPRINT, '-', "Show ETS fingerprint"},
    {NULL}
};

@@ -59,6 +69,7 @@ int pkey_main(int argc, char **argv)
    int informat = FORMAT_PEM, outformat = FORMAT_PEM;
    int pubin = 0, pubout = 0, pubtext = 0, text = 0, noout = 0, ret = 1;
    int private = 0, traditional = 0, check = 0, pub_check = 0;
    int ets_fingerprint = 0;

    prog = opt_init(argc, argv, pkey_options);
    while ((o = opt_next()) != OPT_EOF) {
@@ -122,6 +133,10 @@ int pkey_main(int argc, char **argv)
        case OPT_MD:
            if (!opt_cipher(opt_unknown(), &cipher))
                goto opthelp;
	    break;
        case OPT_ETS_FINGERPRINT:
            ets_fingerprint = 1;
            break;
        }
    }
    argc = opt_num_rest();
@@ -216,6 +231,22 @@ int pkey_main(int argc, char **argv)
        }
    }

    if (ets_fingerprint) {
        unsigned char fp[ETS_FINGERPRINT_BITS / 8];
        unsigned i;

        if (!ETS_fingerprint_pkey(pkey, fp, sizeof fp)) {
            BIO_printf(bio_err, "Could not generate ETS fingerprint for key\n");
            ret = 1;
            goto end;
        }
        if (!noout || text)
            BIO_printf(out, "ETS fingerprint: ");
        for (i = 0; i < sizeof fp; i++)
            BIO_printf(out, "%02x", fp[i]);
        BIO_printf(out, "\n");
    }

    if (text) {
        if (pubtext) {
            if (EVP_PKEY_print_public(out, pkey, 0, NULL) <= 0)
+2 −4
Original line number Diff line number Diff line
@@ -350,7 +350,7 @@ int ssl_print_groups(BIO *out, SSL *s, int noshared)
    groups = app_malloc(ngroups * sizeof(int), "groups to print");
    SSL_get1_groups(s, groups);

    BIO_puts(out, "Supported Elliptic Groups: ");
    BIO_puts(out, "Supported Groups: ");
    for (i = 0; i < ngroups; i++) {
        if (i)
            BIO_puts(out, ":");
@@ -359,7 +359,6 @@ int ssl_print_groups(BIO *out, SSL *s, int noshared)
        if (nid & TLSEXT_nid_unknown) {
            BIO_printf(out, "0x%04X", nid & 0xFFFF);
        } else {
            /* TODO(TLS1.3): Get group name here */
            /* Use NIST name for curve if it exists */
            gname = EC_curve_nid2nist(nid);
            if (gname == NULL)
@@ -372,13 +371,12 @@ int ssl_print_groups(BIO *out, SSL *s, int noshared)
        BIO_puts(out, "\n");
        return 1;
    }
    BIO_puts(out, "\nShared Elliptic groups: ");
    BIO_puts(out, "\nShared groups: ");
    ngroups = SSL_get_shared_group(s, -1);
    for (i = 0; i < ngroups; i++) {
        if (i)
            BIO_puts(out, ":");
        nid = SSL_get_shared_group(s, i);
        /* TODO(TLS1.3): Convert for DH groups */
        gname = EC_curve_nid2nist(nid);
        if (gname == NULL)
            gname = OBJ_nid2sn(nid);
Loading