guile-ssh/doc/api-auth.texi

@c -*-texinfo-*-
@c This file is part of Guile-SSH Reference Manual.
@c Copyright (C) 2014 Artyom V. Poptsov
@c See the file guile-ssh.texi for copying conditions.

@node Auth
@section Auth

@cindex authentication

The @code{(ssh auth)} module provides authentication procedures for a
Guile-SSH client.

Please note that you must specify a username either on creation of a
session or by @code{session-set!} call (@pxref{Sessions}) before
calling of procedures from this section.

Also @strong{note} that the session must be connected before calling to these
procedures, otherwise the @code{wrong-type-arg} exception will be thrown.

@deffn {Scheme Procedure} userauth-public-key! session private-key
Try to authenticate with a public/private key.

Return one of the following symbols:

@table @samp
@item success
Authentication success.
@item partial
You've been partially authenticated, you still have to use another
method.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-public-key/auto! session
@cindex authentication with a SSH agent
Try to automatically authenticate with @code{none} method first and
then with public keys.  The procedure will try to get a cached private
key from a @acronym{SSH} agent and if it fails it will try to read a
key from a file.  If the key is encrypted the user will be asked for a
passphrase.

Return one of the following symbols:

@table @samp
@item success
Authentication success.
@item partial
You've been partially authenticated, you still have to use another
method.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-public-key/try session public-key
Try to authenticate with the given @var{public-key}.

To avoid unnecessary processing and user interaction, the following
method is provided for querying whether authentication using the
@var{public-key} would be possible.

Return one of the following symbols:

@table @samp
@item success
The public key is accepted, you want now to use
@code{userauth-public-key!}.
@item partial
You've been partially authenticated, you still have to use another
method.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-agent! session
Try to do public key authentication with ssh agent.

Return one of the following symbols:

@table @samp
@item success
Authentication success.
@item partial
You've been partially authenticated, you still have to use another
method.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-password! session password
Try to authenticate by @var{password}.

Return one of the following symbols:

@table @samp
@item success
Authentication success.
@item partial
You've been partially authenticated, you still have to use another
method.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@item again
In nonblocking mode, you've got to call this again later.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-none! session
Try to authenticate through the @code{none} method.

Return one of the following symbols: 

@table @samp
@item success
Authentication success.
@item partial
You've been partially authenticated, you still have to use another method.
@item again
In nonblocking mode, you've got to call this again later.
@item denied
Authentication failed: use another method.
@item error
A serious error happened.
@end table

@end deffn

@deffn {Scheme Procedure} userauth-get-list session
Get available authentication methods for a @var{session}.  Return list
of available methods.

This call will block, even in nonblocking mode, if run for the first
time before a (complete) call to @code{userauth-none!}.

Possible methods are: @code{password}, @code{public-key},
@code{host-based}, @code{interactive}.

@end deffn

@c Local Variables:
@c TeX-master: "guile-ssh.texi"
@c End: