README.eap-tls - manifest_repos/ppp - Git at Google

 EAP-TLS authentication support for PPP
 ======================================

 1. Intro

     The Extensible Authentication Protocol (EAP; RFC 3748) is a
     security protocol that can be used with PPP.  It provides a means
     to plug in multiple optional authentication methods.

     Transport Level Security (TLS; RFC 5216) provides for mutual
     authentication, integrity-protected ciphersuite negotiation and
     key exchange between two endpoints.  It also provides for optional
     MPPE encryption.

     EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
     allowing TLS mutual authentication to be used as a generic EAP
     mechanism. It also provides optional encryption using the MPPE
     protocol.

     This patch provide EAP-TLS support to pppd.
     This authentication method can be used in both client or server
     mode.

 2. Building

     To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
     is required. Any version from 0.9.7 should work.

     Configure, compile, and install as usual.

 3. Configuration

     On the client side there are two ways to configure EAP-TLS:

     1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters

     2. edit the /etc/ppp/eaptls-client file.
     Insert a line for each system with which you use EAP-TLS.
     The line is composed of this fields separated by tab:

       - Client name
         The name used by the client for authentication, can be *
       - Server name
         The name of the server, can be *
       - Client certificate file
         The file containing the certificate chain for the
         client in PEM format
       - Server certificate file
         If you want to specify the certificate that the
         server is allowed to use, put the certificate file name.
         Else put a dash '-'.
       - CA certificate file
         The file containing the trusted CA certificates in PEM
         format.
       - Client private key file
         The file containing the client private key in PEM format.


     On the server side edit the /etc/ppp/eaptls-server file.
     Insert a line for each system with which you use EAP-TLS.
     The line is composed of this fields separated by tab:

       - Client name
         The name used by the client for authentication, can be *
       - Server name
         The name of the server, can be *
       - Client certificate file
         If you want to specify the certificate that the
         client is allowed to use, put the certificate file name.
         Else put a dash '-'.
       - Server certificate file
         The file containing the certificate chain for the
         server in PEM format
       - CA certificate file
         The file containing the trusted CA certificates in PEM format.
       - Client private key file
         The file containing the server private key in PEM format.
       - addresses
         A list of IP addresses the client is allowed to use.


     OpenSSL engine support is included starting with v0.95 of this patch.
     Currently the only engine tested is the 'pkcs11' engine (hardware token
     support). To use the 'pksc11' engine:
       - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
           <engine>:<identifier>
         e.g.
           pkcs11:123456

       - The certificate can also be loaded from the 'pkcs11' engine using
         a special client certificate filename in the /etc/ppp/eaptls-client file:
           <engine>:<identifier>
         e.g.
           pkcs11:123456

       - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
         to starting 'pppd'. A sample openssl.cnf file is

         openssl_conf = openssl_def

         [ openssl_def ]
         engines = engine_section

         [ engine_section ]
         pkcs11 = pkcs11_section

         [ pkcs11_section ]
         engine_id = pkcs11
         dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
         MODULE_PATH = /usr/lib64/libeTPkcs11.so
         init = 0

       - There are two ways to specify a password/PIN for the PKCS11 engine:
           - inside the openssl.cnf file using
               PIN = your-secret-pin
             Note The keyword 'PIN' is case sensitive!
           - Using the 'password' in the ppp options file.
         From v0.97 of the eap-tls patch the password can also be supplied
         using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
         for an example).


 4. Options

     These pppd options are available:

       ca <ca-file>
         Use the CA public certificate found in <ca-file> in PEM format
       ca-path <directory>
         Use the directory <directory> as the CA public certificate directory
       cert <cert-file>
         Use the client public certificate found in <cert-file> in PEM format
         or in engine:engine_id format
       key <key-file>
         Use the client private key found in <key-file> in PEM format
         or in engine:engine_id format
       crl <crl-file>
         Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
       crl-dir <dir>
         Use CRL files from directory <dir>. It contains CRL files in PEM
         format and each file contains a CRL. The files are looked up
         by the issuer name hash value. Use the c_rehash utility
         to create necessary links.
       need-peer-eap
         If the peer doesn't ask us to authenticate or doesn't use eap
         to authenticate us, disconnect.
       max-tls-version <1.0|1.1|1.2 (default)|1.3>
         Specify the maximum TLS protocol version to negotiate with peers. Defaults
         to TLSv1.2 as the TLSv1.3 code is experimental.

     Note:
       password-encrypted certificates can be used as of v0.94 of this
       patch. The password for the eap-tls.key file is specified using
       the regular
           password ....
       statement in the ppp options file, or by using the appropriate
       plugin which supplies a 'eaptls_passwd_hook' routine.

 5. Connecting

     If you're setting up a pppd server, edit the EAP-TLS configuration file
     as written above and then run pppd with the 'auth' option to authenticate
     the client. The EAP-TLS method will be used if the other eap methods can't
     be used (no secrets).

     If you're setting up a client, edit the configuration file and then run
     pppd with 'remotename' option to specify the server name. Add the
     'need-peer-eap' option if you want to be sure the peer ask you to
     authenticate (and to use eap) and to disconnect if it doesn't.

 6. Example

     The following example can be used to connect a Linux client with the 'pptp'
     package to a Linux server running the 'pptpd' (PoPToP) package. The server
     was configured with a certificate with name (CN) 'pptp-server', the client
     was configured with a certificate with name (CN) 'pptp-client', both
     signed by the same Certificate Authority (CA).

     Server side:
       - /etc/pptpd.conf file:
           option /etc/ppp/options-pptpd-eaptls
           localip 172.16.1.1
           remoteip 172.16.1.10-20
       - /etc/ppp/options-pptpd-eaptls file:
           name pptp-server
           lock
           mtu 1500
           mru 1450
           auth
           lcp-echo-failure 3
           lcp-echo-interval 5
           nodeflate
           nobsdcomp
           nopredictor1
           nopcomp
           noaccomp

           require-eap
           require-mppe-128

           crl /home/janjust/ppp/keys/crl.pem

           debug
           logfile /tmp/pppd.log

       - /etc/ppp/eaptls-server file:
            * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *

       - On the server, run
           pptdp --conf /etc/pptpd.conf

     Client side:
       - Run
           pppd noauth require-eap require-mppe-128 \
             ipcp-accept-local ipcp-accept-remote noipdefault \
             cert  /etc/ppp/keys/pptp-client.crt \
             key   /etc/ppp/keys/pptp-client.key \
             ca    /etc/ppp/keys/ca.crt \
             name pptp-client remotename pptp-server \
             debug logfile /tmp/pppd.log
             pty "pptp pptp-server.example.com --nolaunchpppd"

     Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.

 7. Notes

     This is experimental code.
     Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
	EAP-TLS authentication support for PPP
	======================================

	1. Intro

	The Extensible Authentication Protocol (EAP; RFC 3748) is a
	security protocol that can be used with PPP. It provides a means
	to plug in multiple optional authentication methods.

	Transport Level Security (TLS; RFC 5216) provides for mutual
	authentication, integrity-protected ciphersuite negotiation and
	key exchange between two endpoints. It also provides for optional
	MPPE encryption.

	EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
	allowing TLS mutual authentication to be used as a generic EAP
	mechanism. It also provides optional encryption using the MPPE
	protocol.

	This patch provide EAP-TLS support to pppd.
	This authentication method can be used in both client or server
	mode.

	2. Building

	To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
	is required. Any version from 0.9.7 should work.

	Configure, compile, and install as usual.

	3. Configuration

	On the client side there are two ways to configure EAP-TLS:

	1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters

	2. edit the /etc/ppp/eaptls-client file.
	Insert a line for each system with which you use EAP-TLS.
	The line is composed of this fields separated by tab:

	- Client name
	The name used by the client for authentication, can be *
	- Server name
	The name of the server, can be *
	- Client certificate file
	The file containing the certificate chain for the
	client in PEM format
	- Server certificate file
	If you want to specify the certificate that the
	server is allowed to use, put the certificate file name.
	Else put a dash '-'.
	- CA certificate file
	The file containing the trusted CA certificates in PEM
	format.
	- Client private key file
	The file containing the client private key in PEM format.


	On the server side edit the /etc/ppp/eaptls-server file.
	Insert a line for each system with which you use EAP-TLS.
	The line is composed of this fields separated by tab:

	- Client name
	The name used by the client for authentication, can be *
	- Server name
	The name of the server, can be *
	- Client certificate file
	If you want to specify the certificate that the
	client is allowed to use, put the certificate file name.
	Else put a dash '-'.
	- Server certificate file
	The file containing the certificate chain for the
	server in PEM format
	- CA certificate file
	The file containing the trusted CA certificates in PEM format.
	- Client private key file
	The file containing the server private key in PEM format.
	- addresses
	A list of IP addresses the client is allowed to use.


	OpenSSL engine support is included starting with v0.95 of this patch.
	Currently the only engine tested is the 'pkcs11' engine (hardware token
	support). To use the 'pksc11' engine:
	- Use a special private key fileiname in the /etc/ppp/eaptls-client file:
	<engine>:<identifier>
	e.g.
	pkcs11:123456

	- The certificate can also be loaded from the 'pkcs11' engine using
	a special client certificate filename in the /etc/ppp/eaptls-client file:
	<engine>:<identifier>
	e.g.
	pkcs11:123456

	- Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
	to starting 'pppd'. A sample openssl.cnf file is

	openssl_conf = openssl_def

	[ openssl_def ]
	engines = engine_section

	[ engine_section ]
	pkcs11 = pkcs11_section

	[ pkcs11_section ]
	engine_id = pkcs11
	dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
	MODULE_PATH = /usr/lib64/libeTPkcs11.so
	init = 0

	- There are two ways to specify a password/PIN for the PKCS11 engine:
	- inside the openssl.cnf file using
	PIN = your-secret-pin
	Note The keyword 'PIN' is case sensitive!
	- Using the 'password' in the ppp options file.
	From v0.97 of the eap-tls patch the password can also be supplied
	using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
	for an example).


	4. Options

	These pppd options are available:

	ca <ca-file>
	Use the CA public certificate found in <ca-file> in PEM format
	ca-path <directory>
	Use the directory <directory> as the CA public certificate directory
	cert <cert-file>
	Use the client public certificate found in <cert-file> in PEM format
	or in engine:engine_id format
	key <key-file>
	Use the client private key found in <key-file> in PEM format
	or in engine:engine_id format
	crl <crl-file>
	Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
	crl-dir <dir>
	Use CRL files from directory <dir>. It contains CRL files in PEM
	format and each file contains a CRL. The files are looked up
	by the issuer name hash value. Use the c_rehash utility
	to create necessary links.
	need-peer-eap
	If the peer doesn't ask us to authenticate or doesn't use eap
	to authenticate us, disconnect.
	max-tls-version <1.0\|1.1\|1.2 (default)\|1.3>
	Specify the maximum TLS protocol version to negotiate with peers. Defaults
	to TLSv1.2 as the TLSv1.3 code is experimental.

	Note:
	password-encrypted certificates can be used as of v0.94 of this
	patch. The password for the eap-tls.key file is specified using
	the regular
	password ....
	statement in the ppp options file, or by using the appropriate
	plugin which supplies a 'eaptls_passwd_hook' routine.

	5. Connecting

	If you're setting up a pppd server, edit the EAP-TLS configuration file
	as written above and then run pppd with the 'auth' option to authenticate
	the client. The EAP-TLS method will be used if the other eap methods can't
	be used (no secrets).

	If you're setting up a client, edit the configuration file and then run
	pppd with 'remotename' option to specify the server name. Add the
	'need-peer-eap' option if you want to be sure the peer ask you to
	authenticate (and to use eap) and to disconnect if it doesn't.

	6. Example

	The following example can be used to connect a Linux client with the 'pptp'
	package to a Linux server running the 'pptpd' (PoPToP) package. The server
	was configured with a certificate with name (CN) 'pptp-server', the client
	was configured with a certificate with name (CN) 'pptp-client', both
	signed by the same Certificate Authority (CA).

	Server side:
	- /etc/pptpd.conf file:
	option /etc/ppp/options-pptpd-eaptls
	localip 172.16.1.1
	remoteip 172.16.1.10-20
	- /etc/ppp/options-pptpd-eaptls file:
	name pptp-server
	lock
	mtu 1500
	mru 1450
	auth
	lcp-echo-failure 3
	lcp-echo-interval 5
	nodeflate
	nobsdcomp
	nopredictor1
	nopcomp
	noaccomp

	require-eap
	require-mppe-128

	crl /home/janjust/ppp/keys/crl.pem

	debug
	logfile /tmp/pppd.log

	- /etc/ppp/eaptls-server file:
	* pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *

	- On the server, run
	pptdp --conf /etc/pptpd.conf

	Client side:
	- Run
	pppd noauth require-eap require-mppe-128 \
	ipcp-accept-local ipcp-accept-remote noipdefault \
	cert /etc/ppp/keys/pptp-client.crt \
	key /etc/ppp/keys/pptp-client.key \
	ca /etc/ppp/keys/ca.crt \
	name pptp-client remotename pptp-server \
	debug logfile /tmp/pppd.log
	pty "pptp pptp-server.example.com --nolaunchpppd"

	Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.

	7. Notes

	This is experimental code.
	Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>