protocol.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

    by recontacting the server if it doesn't want to terminate itself.
    Closing the connection is also advisable if an unrecognizable message type
    is received, since this probably indicates loss of message-boundary sync.
   </para>

   <para>
    For either normal or abnormal termination, any open transaction is
    rolled back, not committed.  One should note however that if a
    frontend disconnects while a non-<command>SELECT</command> query
    is being processed, the backend will probably finish the query
    before noticing the disconnection.  If the query is outside any
    transaction block (<command>BEGIN</> ... <command>COMMIT</>
    sequence) then its results may be committed before the
    disconnection is recognized.
   </para>
  </sect2>

  <sect2>
   <title><acronym>SSL</acronym> Session Encryption</title>

   <para>
    If <productname>PostgreSQL</> was built with
    <acronym>SSL</acronym> support, frontend/backend communications
    can be encrypted using <acronym>SSL</acronym>.  This provides
    communication security in environments where attackers might be
    able to capture the session traffic. For more information on
    encrypting <productname>PostgreSQL</productname> sessions with
    <acronym>SSL</acronym>, see <xref linkend="ssl-tcp">.
   </para>

   <para>
    To initiate an <acronym>SSL</acronym>-encrypted connection, the
    frontend initially sends an SSLRequest message rather than a
    StartupMessage.  The server then responds with a single byte
    containing <literal>S</> or <literal>N</>, indicating that it is
    willing or unwilling to perform <acronym>SSL</acronym>,
    respectively.  The frontend may close the connection at this point
    if it is dissatisfied with the response.  To continue after
    <literal>S</>, perform an <acronym>SSL</acronym> startup handshake
    (not described here, part of the <acronym>SSL</acronym>
    specification) with the server.  If this is successful, continue
    with sending the usual StartupMessage.  In this case the
    StartupMessage and all subsequent data will be
    <acronym>SSL</acronym>-encrypted.  To continue after
    <literal>N</>, send the usual StartupMessage and proceed without
    encryption.
   </para>

   <para>
    The frontend should also be prepared to handle an ErrorMessage
    response to SSLRequest from the server.  This would only occur if
    the server predates the addition of <acronym>SSL</acronym> support
    to <productname>PostgreSQL</>.  In this case the connection must
    be closed, but the frontend may choose to open a fresh connection
    and proceed without requesting <acronym>SSL</acronym>.
   </para>

   <para>
    An initial SSLRequest may also be used in a connection that is being
    opened to send a CancelRequest message.
   </para>

   <para>
    While the protocol itself does not provide a way for the server to
    force <acronym>SSL</acronym> encryption, the administrator may
    configure the server to reject unencrypted sessions as a byproduct
    of authentication checking.
   </para>
  </sect2>
 </sect1>

<sect1 id="protocol-message-types">
<title>Message Data Types</title>

<para>
This section describes the base data types used in messages.

<variablelist>

<varlistentry>
<term>
        Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)
</term>
<listitem>
<para>
                An <replaceable>n</replaceable>-bit integer in network byte
                order (most significant byte first).
                If <replaceable>i</replaceable> is specified it
                is the exact value that will appear, otherwise the value
                is variable.  Eg. Int16, Int32(42).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
        Int<replaceable>n</replaceable>[<replaceable>k</replaceable>]
</term>
<listitem>
<para>
                An array of <replaceable>k</replaceable>
                <replaceable>n</replaceable>-bit integers, each in network
                byte order.  The array length <replaceable>k</replaceable>
                is always determined by an earlier field in the message.
                Eg. Int16[M].
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
        String(<replaceable>s</replaceable>)
</term>
<listitem>
<para>
                A null-terminated string (C-style string).  There is no
                specific length limitation on strings.
                If <replaceable>s</replaceable> is specified it is the exact
                value that will appear, otherwise the value is variable.
                Eg. String, String("user").
</para>
                
<note>
<para>
<emphasis>There is no predefined limit</emphasis> on the length of a string
that can be returned by the backend.  Good coding strategy for a frontend
is to use an expandable buffer so that anything that fits in memory can be
accepted.  If that's not feasible, read the full string and discard trailing
characters that don't fit into your fixed-size buffer.
</para>
</note>
</listitem>
</varlistentry>

<varlistentry>
<term>
        Byte<replaceable>n</replaceable>(<replaceable>c</replaceable>)
</term>
<listitem>
<para>
                Exactly <replaceable>n</replaceable> bytes.  If the field
                width <replaceable>n</replaceable> is not a constant, it is
                always determinable from an earlier field in the message.
                If <replaceable>c</replaceable> is specified it is the exact
                value.  Eg. Byte2, Byte1('\n').
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</sect1>

<sect1 id="protocol-message-formats">
<title>Message Formats</title>

<para>
This section describes the detailed format of each message.  Each is marked to
indicate that it may be sent by a frontend (F), a backend (B), or both
(F &amp; B).
Notice that although each message includes a byte count at the beginning,
the message format is defined so that the message end can be found without
reference to the byte count.  This aids validity checking.  (The CopyData
message is an exception, because it forms part of a data stream; the contents
of any individual CopyData message may not be interpretable on their own.)
</para>

<variablelist>


<varlistentry>
<term>
AuthenticationOk (B)
</term>
<listitem>
<para>

<variablelist>
<varlistentry>
<term>
        Byte1('R')
</term>
<listitem>
<para>
                Identifies the message as an authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(8)
</term>
<listitem>
<para>
                Length of message contents in bytes, including self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(0)
</term>
<listitem>
<para>
                Specifies that the authentication was successful.
</para>
</listitem>
</varlistentry>
</variablelist>

</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
AuthenticationKerberosV5 (B)
</term>
<listitem>
<para>

<variablelist>
<varlistentry>
<term>
        Byte1('R')
</term>
<listitem>
<para>
                Identifies the message as an authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(8)
</term>
<listitem>
<para>
                Length of message contents in bytes, including self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(2)
</term>
<listitem>
<para>
                Specifies that Kerberos V5 authentication is required.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
AuthenticationCleartextPassword (B)
</term>
<listitem>
<para>

<variablelist>
<varlistentry>
<term>
        Byte1('R')
</term>
<listitem>
<para>
                Identifies the message as an authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(8)
</term>
<listitem>
<para>
                Length of message contents in bytes, including self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(3)
</term>
<listitem>
<para>
                Specifies that a clear-text password is required.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
AuthenticationCryptPassword (B)
</term>
<listitem>
<para>

<variablelist>
<varlistentry>
<term>
        Byte1('R')
</term>
<listitem>
<para>
                Identifies the message as an authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(10)
</term>
<listitem>
<para>
                Length of message contents in bytes, including self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(4)
</term>
<listitem>
<para>
                Specifies that a crypt()-encrypted password is required.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Byte2
</term>
<listitem>
<para>
                The salt to use when encrypting the password.
</para>
</listitem>
</varlistentry>
</variablelist>

</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
AuthenticationMD5Password (B)
</term>
<listitem>
<para>

<variablelist>
<varlistentry>
<term>
        Byte1('R')
</term>
<listitem>
<para>
                Identifies the message as an authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(12)
</term>
<listitem>
<para>
                Length of message contents in bytes, including self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
        Int32(5)
</term>
<listitem>
<para>
                Specifies that an MD5-encrypted password is required.
</para>
</listitem>