# Copyright (C) 2002-2026 Simon Josefsson
#
# This file is part of GNU SASL.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

purpose "Authenticate user to a server using Simple Authentication and
Security Layer.  Currently IMAP and SMTP servers are supported.  This
is a command line interface for the GNU SASL library."

section "Commands"
option "client" c "Act as client." flag on
option "server" s "Act as server." flag off
option "client-mechanisms" - "Write name of supported client mechanisms separated by space to stdout." flag off
option "server-mechanisms" - "Write name of supported server mechanisms separated by space to stdout." flag off
option "mkpasswd" k "Derive password. Provide --mechanism as SCRAM-SHA-1 or SCRAM-SHA-256.  The required inputs are password (through --password or read from terminal) and optional inputs are iteration count (through --iteration-count, or defaulting to 65536) and salt (through --salt, or generated randomly).  The output is a string of the form \"{mech}count,salt,stored-key,server-key[,salted-password]\" where \"mech\" is the mechanism, \"count\" is the number of times password was hashed, \"salt\" is the provided/generated base64-encoded salt, \"stored-key\" and \"server-key\" are the two derived and base64-encoded server-side keys.  When --verbose is provided, \"salted-password\" will be included as the hex-encoded PBKDF2-derived password." flag off

section "Network options"
option "connect" - "Connect to TCP server and negotiate on stream instead of stdin/stdout. PORT is the protocol service, or an integer denoting the port, and defaults to 143 (imap) if not specified. Also sets the --hostname default." string typestr="HOST[:PORT]" no
#option "listen" - "Listen on network socket and provide authentication services following the supported protocols.  This implies --server and defaults to IMAP mode." string typestr="HOST:[PORT]" no argoptional default="localhost:143"

section "Generic options"
option "application-data" d "After authentication, read data from stdin and run it through the mechanism's security layer and print it base64 encoded to stdout. The default is to terminate after authentication." flag on
option "imap" - "Use a IMAP-like logon procedure (client only). Also sets the --service default to 'imap'." flag off
option "smtp" - "Use a SMTP-like logon procedure (client only). Also sets the --service default to 'smtp'." flag off
option "mechanism" m "Mechanism to use." string no
option "no-client-first" - "Disallow client to send data first (client only)." flag off

section "SASL mechanism options (they are prompted for when required)"
option "anonymous-token" n "Token for anonymous authentication, usually mail address (ANONYMOUS only)." string no
option "authentication-id" a "Identity of credential owner." string no
option "authorization-id" z "Identity to request service for." string no
option "password" p "Password for authentication (insecure for non-testing purposes)." string no
option "realm" r "Realm. Defaults to hostname." string no
option "passcode" - "Passcode for authentication (SECURID only)." string typestr="NUMBER" no
option "service" - "Set the requested service name (should be a registered GSSAPI host based service name)." string no
option "hostname" - "Set the name of the server with the requested service." string no
option "service-name" - "Set the generic server name in case of a replicated server (DIGEST-MD5 only)." string no
option "enable-cram-md5-validate" - "Validate CRAM-MD5 challenge and response interactively." flag off
option "disable-cleartext-validate" - "Disable cleartext validate hook, forcing server to prompt for password." flag off
option "quality-of-protection" - "How application payload will be protected. 'qop-auth' means no protection, 'qop-int' means integrity protection, 'qop-conf' means integrity and confidentialiy protection.  Currently only used by DIGEST-MD5, where the default is 'qop-int'." string typestr="TYPE" no
option "iteration-count" - "Indicate PBKDF2 hash iteration count (SCRAM only)." int typestr="NUMBER" no default="65536"
option "salt" - "Indicate PBKDF2 salt as base64-encoded string (SCRAM only)." string typestr="B64DATA" no
option "scram-salted-password" - "Salted SCRAM password for authentication (SCRAM only; 40 hex characters for SCRAM-SHA-1 and 64 characters for SCRAM-SHA-256)." string no

section "STARTTLS options"
option "starttls" - "Force use of STARTTLS.  The default is to use STARTTLS when available." flag off
option "no-starttls" - "Unconditionally disable STARTTLS." flag off
option "no-cb" - "Don't use channel bindings from TLS." flag off
option "x509-ca-file" - "File containing one or more X.509 Certificate Authorities certificates in PEM format, used to verify the certificate received from the server.  If not specified, verification uses system trust settings.  If FILE is the empty string, don't fail on X.509 server certificates verification errors." string typestr="FILE" no
option "x509-cert-file" - "File containing client X.509 certificate in PEM format.  Used together with --x509-key-file to specify the certificate/key pair." string typestr="FILE" no
option "x509-key-file" - "Private key for the client X.509 certificate in PEM format.  Used together with --x509-key-file to specify the certificate/key pair." string typestr="FILE" no
option "priority" - "Cipher priority string." string no

section "Other options"
option "verbose" - "Produce verbose output." flag off
option "quiet" - "Don't produce any diagnostic output." flag off
