Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SSL(8)			FreeBSD	System Manager's Manual			SSL(8)

NAME
     ssl -- details for	libssl and libcrypto

DESCRIPTION
     This document describes some of the issues	relating to the	use of the
     OpenSSL libssl and	libcrypto libraries.  This document is intended	as an
     overview of what the libraries do,	and what uses them.

     The libssl	and libcrypto libraries	implement the TLS version 1 protocol.
     It	is most	commonly used by the HTTPS protocol for	encrypted web transac-
     tions, as can be done with	httpd(8).  The libcrypto library is also used
     by	various	programs such as ssh(1), sshd(8), and isakmpd(8).

SERVER CERTIFICATES
     The most common uses of TLS will require you to generate a	server cer-
     tificate, which is	provided by your host as evidence of its identity when
     clients make new connections.  The	certificates reside in the /etc/ssl
     directory,	with the keys in the /etc/ssl/private directory.

     Private keys can be encrypted using AES and a passphrase to protect their
     integrity should the encrypted file be disclosed.	However, it is impor-
     tant to note that encrypted server	keys mean that the passphrase needs to
     be	typed in every time the	server is started.  If a passphrase is not
     used, you will need to be absolutely sure your key	file is	kept secure.

GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS
     To	support	HTTPS transactions in httpd(8) you will	need to	generate an
     RSA certificate.

	   # openssl genrsa -out /etc/ssl/private/server.key 4096

     Or, if you	wish the key to	be encrypted with a passphrase that you	will
     have to type in when starting servers

	   # openssl genrsa -aes256 -out /etc/ssl/private/server.key 4096

     The next step is to generate a Certificate	Signing	Request	(CSR) which is
     used to get a Certificate Authority (CA) to sign your certificate.	 To do
     this use the command:

	   # openssl req -new -key /etc/ssl/private/server.key \
	     -out /etc/ssl/private/server.csr

     This server.csr file can then be given to a Certificate Authority who
     will sign the key.

     You can also sign the key yourself, using the command:

	   # openssl x509 -sha256 -req -days 365 \
	     -in /etc/ssl/private/server.csr \
	     -signkey /etc/ssl/private/server.key \
	     -out /etc/ssl/server.crt

     Note that standard	web browsers do	not use	the common name	of a subject,
     but instead require that subject alt names	are provided.  This requires
     the use of	-extfile server.ext when self-signing.

	   # this is an	example	server.ext file
	   subjectAltName=DNS:example.com,DNS:www.example.com

     With /etc/ssl/server.crt and /etc/ssl/private/server.key in place,	you
     should be able to start httpd(8) with SSL configured, enabling HTTPS
     transactions with your machine on port 443.

     You will most likely want to generate a self-signed certificate in	the
     manner above along	with your certificate signing request to test your
     server's functionality even if you	are going to have the certificate
     signed by another Certificate Authority.  Once your Certificate Authority
     returns the signed	certificate to you, you	can switch to using the	new
     certificate by replacing the self-signed /etc/ssl/server.crt with the
     certificate signed	by your	Certificate Authority, and then	restarting
     httpd(8).

GENERATING ECDSA SERVER	CERTIFICATES
     First, generate parameters	for ECDSA keys.	 The following command will
     use a NIST/SECG curve over	a 384-bit prime	field:

	   # openssl ecparam -out ec-secp384r1.pem -name secp384r1

     Once you have the ECDSA parameters	generated, you can generate a CSR and
     unencrypted private key using the command:

	   # openssl req -nodes	-newkey	ec:ec-secp384r1.pem \
	     -keyout /etc/ssl/private/eccert.key -new \
	     -out /etc/ssl/private/eccert.csr

     To	generate an encrypted private key, you would use:

	   # openssl req -newkey ec:ec-secp384r1.pem \
	     -keyout /etc/ssl/private/eccert.key -new \
	     -out /etc/ssl/private/eccert.csr

     This eccert.csr file can then be given to a CA who	will sign the key.

     You can also sign the key yourself, using the command:

	   # openssl x509 -sha256 -req -days 365 \
	     -in /etc/ssl/private/eccert.csr \
	     -signkey /etc/ssl/private/eccert.key \
	     -out /etc/ssl/eccert.crt

SEE ALSO
     openssl(1), ssh(1), ssl(3), httpd(8), isakmpd(8), rc(8), smtpd(8),
     sshd(8), starttls(8)

HISTORY
     Prior to Sept 21, 2000, there were	problems shipping fully	functional im-
     plementations of these protocols, as such shipment	would include shipping
     into the United States.  RSA Data Security	Inc (RSADSI) held the patent
     on	the RSA	algorithm in the United	States,	and because of this, free im-
     plementations of RSA were difficult to distribute and propagate.  (The
     RSA patent	was probably more effective at preventing the adoption of
     widespread	international integrated crypto	than the much maligned ITAR
     restrictions were.)  Prior	to OpenBSD 2.8,	these libraries	shipped	with-
     out the RSA algorithm -- all such functions were stubbed to fail.	Since
     RSA is a key component of SSL version 2, this meant that SSL version 2
     would not work at all.  SSL version 3 and TLS version 1 allow for the ex-
     change of keys via	mechanisms that	do not involve RSA, and	would work
     with the shipped version of the libraries,	assuming both ends could agree
     to	a cipher suite and key exchange	that did not involve RSA.  Likewise,
     the SSH1 protocol in ssh(1) uses RSA, so it was similarly encumbered.

     For instance, another typical alternative is DSA, which is	not encumbered
     by	commercial patents (and	lawyers).

     The HTTPS protocol	used by	web browsers (in modern	incarnations) allows
     for the use of SSL	version	3 and TLS version 1, which in theory allows
     for encrypted web transactions without using RSA.	Unfortunately, all the
     popular web browsers buy their cryptographic code from RSADSI.  Pre-
     dictably, RSADSI would prefer that	web browsers used their	patented algo-
     rithm, and	thus their libraries do	not implement any non-RSA cipher and
     keying combination.  The result of	this was that while the	HTTPS protocol
     allowed for many cipher suites that did not require the use of patented
     algorithms, it was	very difficult to use these with the popular commer-
     cially available software.	 Prior to version 2.8, OpenBSD allowed users
     to	download RSA enabled versions of the shared libssl and libcrypto li-
     braries which allowed users to enable full	functionality without recom-
     piling the	applications.  This method is now no longer needed, as the
     fully functional libraries	ship with the system.  However,	this entire
     debacle is	worth remembering when choosing	software and vendors.

     Due to multiple flaws in the protocols, SSL version 2 was removed in
     OpenBSD 5.2 and SSL version 3 was disabled	in OpenBSD 5.7.	 Users and
     programs should use TLS version 1.2 instead.

     This document first appeared in OpenBSD 2.5.

FreeBSD	13.0			 May 10, 2019			  FreeBSD 13.0

NAME | DESCRIPTION | SERVER CERTIFICATES | GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS | GENERATING ECDSA SERVER CERTIFICATES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ssl&sektion=8&manpath=OpenBSD+6.8>

home | help