codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.3. SASL Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-flow.html" title="55.2. Message Flow" /><link rel="next" href="protocol-replication.html" title="55.4. Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.3. SASL Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-flow.html" title="55.2. Message Flow">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="SASL-AUTHENTICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.3. SASL Authentication <a href="#SASL-AUTHENTICATION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sasl-authentication.html#SASL-SCRAM-SHA-256">55.3.1. SCRAM-SHA-256 Authentication</a></span></dt></dl></div><p>3   <em class="firstterm">SASL</em> is a framework for authentication in connection-oriented4   protocols. At the moment, <span class="productname">PostgreSQL</span> implements two SASL5   authentication mechanisms, SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. More6   might be added in the future. The below steps illustrate how SASL7   authentication is performed in general, while the next subsection gives8   more details on SCRAM-SHA-256 and SCRAM-SHA-256-PLUS.9  </p><div class="procedure" id="id-1.10.6.8.3"><p class="title"><strong>SASL Authentication Message Flow</strong></p><ol class="procedure" type="1"><li class="step" id="SASL-AUTH-BEGIN"><p>10     To begin a SASL authentication exchange, the server sends an11     AuthenticationSASL message. It includes a list of SASL authentication12     mechanisms that the server can accept, in the server's preferred order.13    </p></li><li class="step" id="SASL-AUTH-INITIAL-RESPONSE"><p>14     The client selects one of the supported mechanisms from the list, and sends15     a SASLInitialResponse message to the server. The message includes the name16     of the selected mechanism, and an optional Initial Client Response, if the17     selected mechanism uses that.18    </p></li><li class="step" id="SASL-AUTH-CONTINUE"><p>19     One or more server-challenge and client-response message will follow. Each20     server-challenge is sent in an AuthenticationSASLContinue message, followed21     by a response from client in a SASLResponse message. The particulars of22     the messages are mechanism specific.23    </p></li><li class="step" id="SASL-AUTH-END"><p>24     Finally, when the authentication exchange is completed successfully, the25     server sends an AuthenticationSASLFinal message, followed26     immediately by an AuthenticationOk message. The AuthenticationSASLFinal27     contains additional server-to-client data, whose content is particular to the28     selected authentication mechanism. If the authentication mechanism doesn't29     use additional data that's sent at completion, the AuthenticationSASLFinal30     message is not sent.31    </p></li></ol></div><p>32   On error, the server can abort the authentication at any stage, and send an33   ErrorMessage.34  </p><div class="sect2" id="SASL-SCRAM-SHA-256"><div class="titlepage"><div><div><h3 class="title">55.3.1. SCRAM-SHA-256 Authentication <a href="#SASL-SCRAM-SHA-256" class="id_link">#</a></h3></div></div></div><p>35    The implemented SASL mechanisms at the moment36    are <code class="literal">SCRAM-SHA-256</code> and its variant with channel37    binding <code class="literal">SCRAM-SHA-256-PLUS</code>. They are described in38    detail in <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc7677" target="_top">RFC 7677</a>39    and <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc5802" target="_top">RFC 5802</a>.40   </p><p>41    When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name42    that the client sends in the <code class="structname">client-first-message</code>. The user name43    that was already sent in the startup message is used instead.44    <span class="productname">PostgreSQL</span> supports multiple character encodings, while SCRAM45    dictates UTF-8 to be used for the user name, so it might be impossible to46    represent the PostgreSQL user name in UTF-8.47   </p><p>48    The SCRAM specification dictates that the password is also in UTF-8, and is49    processed with the <em class="firstterm">SASLprep</em> algorithm.50    <span class="productname">PostgreSQL</span>, however, does not require UTF-8 to be used for51    the password. When a user's password is set, it is processed with SASLprep52    as if it was in UTF-8, regardless of the actual encoding used. However, if53    it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences54    that are prohibited by the SASLprep algorithm, the raw password will be used55    without SASLprep processing, instead of throwing an error. This allows the56    password to be normalized when it is in UTF-8, but still allows a non-UTF-857    password to be used, and doesn't require the system to know which encoding58    the password is in.59   </p><p>60    <em class="firstterm">Channel binding</em> is supported in PostgreSQL builds with61    SSL support. The SASL mechanism name for SCRAM with channel binding is62    <code class="literal">SCRAM-SHA-256-PLUS</code>.  The channel binding type used by63    PostgreSQL is <code class="literal">tls-server-end-point</code>.64   </p><p>65    In <acronym class="acronym">SCRAM</acronym> without channel binding, the server chooses66    a random number that is transmitted to the client to be mixed with the67    user-supplied password in the transmitted password hash.  While this68    prevents the password hash from being successfully retransmitted in69    a later session, it does not prevent a fake server between the real70    server and client from passing through the server's random value71    and successfully authenticating.72   </p><p>73    <acronym class="acronym">SCRAM</acronym> with channel binding prevents such74    man-in-the-middle attacks by mixing the signature of the server's75    certificate into the transmitted password hash. While a fake server can76    retransmit the real server's certificate, it doesn't have access to the77    private key matching that certificate, and therefore cannot prove it is78    the owner, causing SSL connection failure.79   </p><div class="procedure" id="id-1.10.6.8.5.8"><p class="title"><strong>Example</strong></p><ol class="procedure" type="1"><li class="step" id="SCRAM-BEGIN"><p>80      The server sends an AuthenticationSASL message. It includes a list of81      SASL authentication mechanisms that the server can accept.82      This will be <code class="literal">SCRAM-SHA-256-PLUS</code>83      and <code class="literal">SCRAM-SHA-256</code> if the server is built with SSL84      support, or else just the latter.85     </p></li><li class="step" id="SCRAM-CLIENT-FIRST"><p>86      The client responds by sending a SASLInitialResponse message, which87      indicates the chosen mechanism, <code class="literal">SCRAM-SHA-256</code> or88      <code class="literal">SCRAM-SHA-256-PLUS</code>. (A client is free to choose either89      mechanism, but for better security it should choose the channel-binding90      variant if it can support it.) In the Initial Client response field, the91      message contains the SCRAM <code class="structname">client-first-message</code>.92      The <code class="structname">client-first-message</code> also contains the channel93      binding type chosen by the client.94     </p></li><li class="step" id="SCRAM-SERVER-FIRST"><p>95      Server sends an AuthenticationSASLContinue message, with a SCRAM96      <code class="structname">server-first-message</code> as the content.97     </p></li><li class="step" id="SCRAM-CLIENT-FINAL"><p>98      Client sends a SASLResponse message, with SCRAM99      <code class="structname">client-final-message</code> as the content.100     </p></li><li class="step" id="SCRAM-SERVER-FINAL"><p>101      Server sends an AuthenticationSASLFinal message, with the SCRAM102      <code class="structname">server-final-message</code>, followed immediately by103      an AuthenticationOk message.104     </p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-flow.html" title="55.2. Message Flow">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.2. Message Flow </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.4. Streaming Replication Protocol</td></tr></table></div></body></html>