<para>

<firstterm>SASL</firstterm> is a framework for authentication in connection-oriented

protocols. At the moment, <productname>PostgreSQL</productname> implements only one SASL

authentication mechanism, SCRAM-SHA-256, but more might be added in the

future. The below steps illustrate how SASL authentication is performed in

general, while the next subsection gives more details on SCRAM-SHA-256.

protocols. At the moment, <productname>PostgreSQL</productname> implements two SASL

authentication mechanisms, SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. More

might be added in the future. The below steps illustrate how SASL

authentication is performed in general, while the next subsection gives

more details on SCRAM-SHA-256 and SCRAM-SHA-256-PLUS.

</para>

<procedure>

<title>SCRAM-SHA-256 authentication</title>

<para>

<firstterm>SCRAM-SHA-256</firstterm> (called just <firstterm>SCRAM</firstterm> from now on) is

the only implemented SASL mechanism, at the moment. It is described in detail

in RFC 7677 and RFC 5802.

The implemented SASL mechanisms at the moment

are <literal>SCRAM-SHA-256</literal> and its variant with channel

binding <literal>SCRAM-SHA-256-PLUS</literal>. They are described in

detail in RFC 7677 and RFC 5802.

</para>

<para>

</para>

<para>

<firstterm>Channel binding</firstterm> has not been implemented yet.

<firstterm>Channel binding</firstterm> is supported in PostgreSQL builds with

SSL support. The SASL mechanism name for SCRAM with channel binding

is <literal>SCRAM-SHA-256-PLUS</literal>. The only channel binding type

supported at the moment is <literal>tls-unique</literal>, defined in RFC 5929.

</para>

<procedure>

<para>

The server sends an AuthenticationSASL message. It includes a list of

SASL authentication mechanisms that the server can accept.

This will be <literal>SCRAM-SHA-256-PLUS</literal>

and <literal>SCRAM-SHA-256</literal> if the server is built with SSL

support, or else just the latter.

</para>

</step>

<step id="scram-client-first">

<para>

The client responds by sending a SASLInitialResponse message, which

indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal>. In the Initial

Client response field, the message contains the SCRAM

indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal> or

<literal>SCRAM-SHA-256-PLUS</literal>. (A client is free to choose either

mechanism, but for better security it should choose the channel-binding

variant if it can support it.) In the Initial Client response field,

the message contains the SCRAM

<structname>client-first-message</structname>.

</para>

</step>

constchar*username;/* username from startup packet */

boolssl_in_use;

constchar*tls_finished_message;

size_ttls_finished_len;

char*channel_binding_type;

intiterations;

char*salt;/* base64-encoded */

uint8StoredKey[SCRAM_KEY_LEN];

pg_be_scram_init(constchar*username,constchar*shadow_pass)

pg_be_scram_init(constchar*username,

constchar*shadow_pass,

boolssl_in_use,

constchar*tls_finished_message,

size_ttls_finished_len)

{

scram_state*state;

boolgot_verifier;

state= (scram_state*)palloc0(sizeof(scram_state));

state->state=SCRAM_AUTH_INIT;

state->username=username;

state->ssl_in_use=ssl_in_use;

state->tls_finished_message=tls_finished_message;

state->tls_finished_len=tls_finished_len;

state->channel_binding_type=NULL;

switch (*input)

{

case'n':

input++;

if (*input!=',')

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

errmsg("malformed SCRAM message"),

errdetail("Comma expected, but found character \"%s\".",

sanitize_char(*input))));

input++;

break;

case'y':

if (state->ssl_in_use)

ereport(ERROR,

(errcode(ERRCODE_INVALID_AUTHORIZATION_SPECIFICATION),

errmsg("SCRAM channel binding negotiation error"),

errdetail("The client supports SCRAM channel binding but thinks the server does not. "

"However, this server does support channel binding.")));

input++;

if (*input!=',')

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

errmsg("malformed SCRAM message"),

errdetail("Comma expected, but found character \"%s\".",

sanitize_char(*input))));

input++;

break;

case'p':

ereport(ERROR,

(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

errmsg("client requires SCRAM channel binding, but it is not supported")));

{

char*channel_binding_type;

if (!state->ssl_in_use)

{

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

errmsg("client requires SCRAM channel binding, but it is not supported")));

}

channel_binding_type=read_attr_value(&input,'p');

if (strcmp(channel_binding_type,SCRAM_CHANNEL_BINDING_TLS_UNIQUE)!=0)

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

(errmsg("unsupported SCRAM channel-binding type"))));

state->channel_binding_type=pstrdup(channel_binding_type);

}

break;

default:

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

errmsg("malformed SCRAM message"),

errdetail("Unexpected channel-binding flag \"%s\".",

sanitize_char(*input))));

}

if (*input!=',')

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

errmsg("malformed SCRAM message"),

errdetail("Comma expected, but found character \"%s\".",

sanitize_char(*input))));

input++;

channel_binding=read_attr_value(&p,'c');

if (strcmp(channel_binding,"biws")!=0)

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

(errmsg("unexpected SCRAM channel-binding attribute in client-final-message"))));

if (state->channel_binding_type)

{

constchar*cbind_data=NULL;

size_tcbind_data_len=0;

size_tcbind_header_len;

char*cbind_input;

size_tcbind_input_len;

char*b64_message;

intb64_message_len;

if (strcmp(state->channel_binding_type,SCRAM_CHANNEL_BINDING_TLS_UNIQUE)==0)

{

cbind_data=state->tls_finished_message;

cbind_data_len=state->tls_finished_len;

}

{

elog(ERROR,"invalid channel binding type");

}

if (cbind_data==NULL||cbind_data_len==0)

elog(ERROR,"empty channel binding data for channel binding type \"%s\"",

state->channel_binding_type);

cbind_header_len=4+strlen(state->channel_binding_type);/* p=type,, */

cbind_input_len=cbind_header_len+cbind_data_len;

cbind_input=palloc(cbind_input_len);

snprintf(cbind_input,cbind_input_len,"p=%s,,",state->channel_binding_type);

memcpy(cbind_input+cbind_header_len,cbind_data,cbind_data_len);

b64_message=palloc(pg_b64_enc_len(cbind_input_len)+1);

b64_message_len=pg_b64_encode(cbind_input,cbind_input_len,

b64_message);

b64_message[b64_message_len]='\0';

if (strcmp(channel_binding,b64_message)!=0)

ereport(ERROR,

(errcode(ERRCODE_INVALID_AUTHORIZATION_SPECIFICATION),

(errmsg("SCRAM channel binding check failed"))));

}

{

if (strcmp(channel_binding,"biws")!=0&&

strcmp(channel_binding,"eSws")!=0)

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),

(errmsg("unexpected SCRAM channel-binding attribute in client-final-message"))));

}

state->client_final_nonce=read_attr_value(&p,'r');

CheckSCRAMAuth(Port*port,char*shadow_pass,char**logdetail)

{

char*sasl_mechs;

char*p;

intmtype;

StringInfoDatabuf;

void*scram_opaq;

intinputlen;

intresult;

boolinitial;

char*tls_finished=NULL;

size_ttls_finished_len=0;

sendAuthRequest(port,AUTH_REQ_SASL,SCRAM_SHA256_NAME"\0",

strlen(SCRAM_SHA256_NAME)+2);

sasl_mechs=palloc(strlen(SCRAM_SHA256_PLUS_NAME)+

strlen(SCRAM_SHA256_NAME)+3);

p=sasl_mechs;

if (port->ssl_in_use)

{

strcpy(p,SCRAM_SHA256_PLUS_NAME);

p+=strlen(SCRAM_SHA256_PLUS_NAME)+1;

}

strcpy(p,SCRAM_SHA256_NAME);

p+=strlen(SCRAM_SHA256_NAME)+1;

p[0]='\0';

sendAuthRequest(port,AUTH_REQ_SASL,sasl_mechs,p-sasl_mechs+1);

pfree(sasl_mechs);

if (port->ssl_in_use)

{

tls_finished=be_tls_get_peer_finished(port,&tls_finished_len);

}

scram_opaq=pg_be_scram_init(port->user_name,shadow_pass);

scram_opaq=pg_be_scram_init(port->user_name,

shadow_pass,

port->ssl_in_use,

tls_finished,

tls_finished_len);

{

constchar*selected_mech;

selected_mech=pq_getmsgrawstring(&buf);

if (strcmp(selected_mech,SCRAM_SHA256_NAME)!=0)

if (strcmp(selected_mech,SCRAM_SHA256_NAME)!=0&&

strcmp(selected_mech,SCRAM_SHA256_PLUS_NAME)!=0)

{

ereport(ERROR,

(errcode(ERRCODE_PROTOCOL_VIOLATION),