Bug 255137

Summary: Wiki LibreSSL- Outdated: missing instructions for new process in V11/V12 and upcoming V13. Some current instructions unclear
Product: Documentation Reporter: buzcom
Component: WikiAssignee: FreeBSD Wiki Admin <wiki-admin>
Status: New ---    
Severity: Affects Some People CC: brnrd, lwhsu
Priority: ---    
Version: Latest   
Hardware: Any   
OS: Any   
URL: https://wiki.freebsd.org/LibreSSL

Description buzcom 2021-04-17 00:22:32 UTC
Currently, the webpage makes reference to FreeBSD version 10 with statements regarding the "future" version 11.  As FreeBSD is approaching the release of stable 13, this information essentially has skipped a version.  The time stamp indicate the page was last edited on 05-02-2019.  There are also mention of changes which should have occurred in the 2 versions this documentation has missed.

In "Problems you'll run into", 
After switching this will most likely hit you with cURL 

     What does the above sentence mean? 
     It is not clear as to what curls' involvement will be  nor able to comprehend how it will be problematic with GSS-API.

In "How to use LibreSSL",
You can use LibreSSL with all of your ports, or to replace OpenSSL in base.
After switching the OpenSSL provider you MUST rebuild all ports. 

     Would it be possible to add a link to "rebuild all ports" (https://docs.freebsd.org/en/books/handbook/ports/#ports-using assuming this is the recommended method)

In the paragraph "Ports" it states,  

Using LibreSSL instead of OpenSSL has been integrated in the FreeBSD ports framework. Simply set one of the following in your /etc/make.conf (or corresponding make.conf for poudriere)
For the current stable branch
DEFAULT_VERSIONS+= ssl=libressl
For the current next branch
DEFAULT_VERSIONS+= ssl=libressl-devel
after setting this, rebuild all your ports. 

     However, this file does not exist in a basic installation of FreeBSD version 12. 
     After some searching, I have found this file can be created.  
     Can a note or link (perhaps https://www.freebsd.org/cig/man.cgi:make.conf(5)) be placed to make mentions of this fact.

In "Base"
There are several ways to get a base system without OpenSSL, currently only from source, but soon using binary distributions as well! 

In "Other sources",
Currently there are no binary distributions for LibreSSL-in-base but this is to change with the release of FreeBSD 11. 

     As this functionality should have been integrated with the previous version (11 and possibly remained in 12), I.E. what are the steps necessary to use to the binary distribution?

In "Build world/kernel from source",
The files and an svn-diff can be found on LibreBSD. You can use the files as an overlay to the /usr/src directory or apply the patch-set. The 11-stable patches are being maintained, the 10-stable patch is no longer maintained (as of 11.0-RC1). You will have to add the LibreSSL sources yourself.
The procedure is documented in the Github Repo so we'll not repeat that here. 

     Where is the github repo?  This is the first mention of it in this site.  To avoid confusion and/or an incorrect repository, could a the link provided to the specific repository.
     There is a mention of github further down in "Types of Failures"; however, that is a repository for SP1| and information relating to examples of fixes for the failure mention in that section. 

In "Building world",
When you build world when you have LibreSSL installed, some base utilities will link to LibreSSL. These you will have to update every time there are shared library versions are bumped 

     "When you build world when you have LibreSSL installed" is confusing. 
     Am I building world and installing LibreSSL at the same time?  
     Does this mean, If I have LibreSSL installed and then build world?

     "These you will have to update every time there are shared library versions are bumped"  I do not understand.  
     When stating "these", does that mean some base utilities? 
     And what does bumped mean?  
     Will the shared libraries be superseded, removed, or perhaps something else?
     Can a link to https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld be added?