.TH SECURITY-LOGIN 2
.SH NAME
login \- verify credentials
.SH SYNOPSIS
.EX
include "keyring.m";
include "security.m";
login := load Login Login->PATH;

login: fn(name, password, addr: string):
	(string, ref Keyring->Authinfo);
.EE
.SH DESCRIPTION
The
.BR Login
module is provided for use by a client of
a certifying authority (CA) or `signer'.
The
.B login
function communicates
with a certifying authority (CA)
in order to create a
.B Keyring->Authinfo
adt
which contains a public/private key pair and a certificate
signed by the CA
(see
.IR keyring-intro (2)).
The public/private key pair is generated by
.B login
using the same parameters as those in the signer's key
(eg, algorithm and key length);
see
.IR keyring-gensk (2).
The procedure assumes a secret, i.e. a
password, has already been established
between the user and the CA.
See
.IR changelogin (8)
and
.IR keyfs (4)
for how this password is managed at the
CA.
.PP
.B Login
connects, using
.IR dial (2),
to the signer at network address
.IR addr ,
which is any form accepted by
.IR cs (8),
including the special address
.BR $SIGNER ,
which
.IR cs
will translate to the client's default signer (if there is one).
Normally the incoming call will be given to
.IR logind (8)
by
.IR svc (8).
.PP
.B Login
sends the user
.I name
and
.IR password ,
using the protocol described in
.IR login (6),
to justify the server's
issuing a certificate, which is returned in a
.B Keyring->Authinfo
adt on success.
The certificate can if desired be stored by
.BR Keyring->writeauthinfo ;
see
.IR keyring-auth (2).
The password is used by the encrypted
key exchange protocol to establish
a secure channel between user and CA.
.SH SOURCE
.B /appl/lib/login.b
.SH SEE ALSO
.IR getauthinfo (8),
.IR keyring-auth (2),
.IR login (6),
.IR createsignerkey (8),
.IR logind (8)
.SH DIAGNOSTICS
.B Login
returns nil in the string component
on success and a diagnostic string on error (with a nil
.B Keyring->Authinfo
reference).
