Project

General

Profile

Bug #58083

Clarify TLS and SSL descriptions in Guide

Added by Sean McBride 4 months ago. Updated about 1 month ago.

Status:
Done
Priority:
No priority
Assignee:
Aaron St. John
Category:
Documentation
Target version:
Seen in:
Severity:
New
Reason for Closing:
Reason for Blocked:
Needs QA:
No
Needs Doc:
No
Needs Merging:
No
Needs Automation:
No
Support Suite Ticket:
n/a
Hardware Configuration:
ChangeLog Required:
No

Description

In Directory Service > LDAP there is an option:

"Encryption Mode:" with 3 choices: Off, SSL, TLS.

This is rather confusing as TLS is basically the new name for SSL.

Does "SSL" mean SSLv3 and older I wondered? Does "TLS" mean TLSv1.0 and newer I wondered? To the docs! They say here:

http://doc.freenas.org/11/directoryservice.html#ldap

"Choices are Off, SSL, or TLS. Note that either SSL or TLS and a Certificate must be selected in order for authentication to work."

So no answer there.

The little question mark button in the GUI helps more, saying: "This parameter specifies whether to use SSL/TLS, e.g. on/off/start_tls"

So I suspect it's the exact same confusion as often happens with email, specifically:
https://www.fastmail.com/help/technical/ssltlsstarttls.html

I still don't know what the 3 choices mean, but I really think they need to be renamed, and for the help text and docs to also elaborate more.


Related issues

Related to FreeNAS - Feature #71939: Add port numbers to entries in Directory Services -> Encryption Mode drop-down menuDone

History

#1 Updated by Dru Lavigne 4 months ago

  • Category changed from GUI (new) to Documentation
  • Assignee changed from Release Council to Warren Block
  • Target version changed from Backlog to 11.2-U2

#2 Updated by Sean McBride 4 months ago

After reading this:
https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol#StartTLS

My best guess of what FreeNAS actually means is:
SSL -> LDAPS aka "LDAP over SSL", port 636
TLS -> StartTLS, port 389

Can anyone confirm?

#3 Updated by Warren Block 4 months ago

  • Assignee changed from Warren Block to Aaron St. John

#4 Updated by Aaron St. John 3 months ago

  • Status changed from Unscreened to In Progress
  • Needs Doc changed from Yes to No

#5 Updated by Sean McBride 3 months ago

Originally, I asked which is true: A or B:

(A) When the FreeNAS UI refers to "SSL" does it mean SSLv3? And when it refers to "TLS" does it mean TLSv1.x?

or

(B) Is it referring to this: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol#StartTLS

i.e.:
"SSL" means: LDAPS aka "LDAP over SSL", port 636
"TLS" means: StartTLS, port 389

Those 2 PRs just add a link to https://www.globalsign.com/en/blog/ssl-vs-tls-difference/ which suggests you are answering (A). Is that so? I was pretty sure it's (B).

#6 Updated by Dru Lavigne 2 months ago

  • Subject changed from LDAP "Encryption Mode:" docs & UI unclear on "SSL" vs "TLS" choice to Add link to Guide that explains TLS and SSL encryption
  • Status changed from In Progress to Ready for Testing
  • Needs Merging changed from Yes to No

#7 Updated by Sean McBride 2 months ago

Well, I see you merged those commits. So you're saying it's (A) and not (B)? Do I need a wireshark capture to prove you wrong?

#8 Updated by Dru Lavigne 2 months ago

  • Status changed from Ready for Testing to In Progress
  • Needs Doc changed from No to Yes
  • Needs Merging changed from No to Yes

#9 Updated by Aaron St. John 2 months ago

  • Status changed from In Progress to Ready for Testing
  • Needs Doc changed from Yes to No
  • Needs Merging changed from Yes to No

Hello, Sean. Sorry for the confusion. I'm still working on clarifying your questions with another subject matter expert.

#10 Updated by Aaron St. John 2 months ago

  • Status changed from Ready for Testing to In Progress
  • Needs Doc changed from No to Yes
  • Needs Merging changed from No to Yes

#11 Updated by Sean McBride 2 months ago

OK, thanks. Because if I'm right, the recent commits make it even worse IMHO.

#12 Updated by Aaron St. John about 2 months ago

Sean McBride wrote:

OK, thanks. Because if I'm right, the recent commits make it even worse IMHO.

Hello, Sean. I've just confirmed with two others about your questions. You are correct.

In short, we have

if self.ssl in (FREENAS_LDAP_NOSSL, FREENAS_LDAP_USETLS):
           proto = "ldap" 

       elif self.ssl == FREENAS_LDAP_USESSL:
           proto = "ldaps" 

Thus, if you chose SSL, it's ldaps protocol (over port 636). Otherwise, choosing TLS it's ldap protocol using the TLS protocol over port 389.

I will be adding this to the docs shortly.

#13 Updated by Sean McBride about 2 months ago

OK, cool. I suggest reverting your previous change, since it misleadingly refers to SSLv3 vs TLSv1.x.

#14 Updated by Aaron St. John about 2 months ago

  • Needs Doc changed from Yes to No

#15 Updated by Sean McBride about 2 months ago

That's much better, thanks!

Could we not go further and change the actual UI from:

Encryption Mode: Off, SSL, TLS.

to something like:

Encryption Mode: Off, LDAPS, StartTLS.

?

#16 Updated by Aaron St. John about 2 months ago

Sean McBride wrote:

That's much better, thanks!

Could we not go further and change the actual UI from:

Encryption Mode: Off, SSL, TLS.

to something like:

Encryption Mode: Off, LDAPS, StartTLS.

?

Thanks for the suggestion. Due to that being a feature request I will open a separate ticket and relate this one to it.

#17 Updated by Aaron St. John about 2 months ago

  • Related to Feature #71939: Add port numbers to entries in Directory Services -> Encryption Mode drop-down menu added

#18 Updated by Dru Lavigne about 2 months ago

  • Subject changed from Add link to Guide that explains TLS and SSL encryption to Clarify TLS and SSL descriptions in Guide
  • Status changed from In Progress to Ready for Testing
  • Needs Merging changed from Yes to No

#20 Updated by Jeff Ervin about 1 month ago

52843

Test Passed for both versions of Guide

#21 Updated by Dru Lavigne about 1 month ago

  • Status changed from Passed Testing to Done

Also available in: Atom PDF