1 files changed, 93 insertions, 0 deletions
diff --git a/man/2/security-login b/man/2/security-login
new file mode 100644
index 00000000..cc831319
--- /dev/null
+++ b/man/2/security-login
@@ -0,0 +1,93 @@
+.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 sys-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).