|
| From: | shishi-commit |
| Subject: | Write shishid manual. [...] |
| Date: | Fri, 12 Dec 2003 01:54:40 +0100 |
| Commit from jas | 2003-12-12 01:54 CET |
Write shishid manual. Add. Fix.
| Module | File name | Revision | |||
|---|---|---|---|---|---|
| shishi | doc/shishi.texi | 1.107 | >>> | 1.108 | |
| shishi/doc/shishi.texi 1.107 >>> 1.108 |
|---|
| Line 981 |
|
(user name in the Kerberos realm) or realm is. In the example, I specify the client name @code{simon@@JOSEFSSON.ORG}. |
|
- @cartouche |
|
@example $ shishi simon@@JOSEFSSON.ORG Enter password for `simon@@JOSEFSSON.ORG': |
| Line 993 |
|
Ticket flags: INITIAL (512) $ @end example |
|
- @end cartouche |
|
As you can see, Shishi also prints a short description of the ticket received. |
| Line 1003 |
|
@file{~/.shishi/tickets}). This is achieved by typing @command{shishi --list}. |
|
- @cartouche |
|
@example $ shishi --list Tickets in `/home/jas/.shishi/tickets': |
| Line 1025 |
|
2 tickets found. $ @end example |
|
- @end cartouche |
|
As you can see, I had a ticket for the server @samp{host/latte.josefsson.org} which was generated by |
| Line 1037 |
|
getting a ticket for the appropriate server, so you normally wouldn't need this command. |
|
- @cartouche |
|
@example $ shishi --server-name=user/billg --encryption-type=des-cbc-md4 jas@@JOSEFSSON.ORG: |
| Line 1048 |
|
Ticket key: des-cbc-md4 (2) protected by des-cbc-md5 (3) $ @end example |
|
- @end cartouche |
|
As you can see, I acquired a ticket for @samp{user/billg} with a @samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key |
| Line 1063 |
|
file, you must contact your administrator and have them reset your account, simply using this parameter is not sufficient. |
|
- @cartouche |
|
@example $ shishi --server-name=imap/latte.josefsson.org --destroy 1 ticket removed. |
| Line 1073 |
|
3 tickets removed. $ @end example |
|
- @end cartouche |
|
Since the @samp{--server-name} parameter takes a long to type, it is possible to type the server name directly, after the client name. The |
| Line 1081 |
|
specific server (assuming you did not have any tickets from the start). |
|
- @cartouche |
|
@example $ src/shishi simon@@latte.josefsson.org imap/latte.josefsson.org Enter password for `simon@@latte.josefsson.org': |
| Line 1093 |
|
Ticket flags: FORWARDED PROXIABLE (12) $ @end example |
|
- @end cartouche |
|
Refer to the reference manual for all available parameters (@pxref{Parameters for shishi}). The rest of this section contains |
| Line 1142 |
|
Here is how you would acquire a PROXY ticket for the service @samp{imap/latte.josefsson.org}: |
|
- @cartouche |
|
@example $ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy Enter password for `jas@@JOSEFSSON.ORG': |
| Line 1156 |
|
Ticket flags: PROXY (16) $ @end example |
|
- @end cartouche |
|
As you noticed, this asked for your password. The reason is that proxy tickets must be acquired using a proxiable ticket granting |
| Line 1164 |
|
tickets, you may acquire a proxiable ticket granting ticket from the start: |
|
- @cartouche |
|
@example $ shishi --proxiable Enter password for `jas@@JOSEFSSON.ORG': |
| Line 1175 |
|
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16) Ticket flags: PROXIABLE INITIAL (520) @end example |
|
- @end cartouche |
|
Then you should be able to acquire proxy tickets based on that ticket granting ticket, as follows: |
|
- @cartouche |
|
@example $ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy libshishi: warning: KDC bug: Reply encrypted using wrong key. |
| Line 1193 |
|
Ticket flags: PROXY (16) $ @end example |
|
- @end cartouche |
|
@section Forwardable and Forwarded Tickets |
| Line 1231 |
|
Here is how you would acquire a FORWARDED ticket for the service @samp{host/latte.josefsson.org}: |
|
- @cartouche |
|
@example $ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded Enter password for `jas@@JOSEFSSON.ORG': |
| Line 1245 |
|
Ticket flags: FORWARDED (4) $ @end example |
|
- @end cartouche |
|
As you noticed, this asked for your password. The reason is that forwarded tickets must be acquired using a forwardable ticket granting |
| Line 1253 |
|
tickets, you may acquire a forwardable ticket granting ticket from the start: |
|
- @cartouche |
|
@example $ shishi --forwardable Enter password for `jas@@JOSEFSSON.ORG': |
| Line 1265 |
|
Ticket flags: FORWARDABLE INITIAL (514) $ @end example |
|
- @end cartouche |
|
Then you should be able to acquire forwarded tickets based on that ticket granting ticket, as follows: |
|
- @cartouche |
|
@example $ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded libshishi: warning: KDC bug: Reply encrypted using wrong key. |
| Line 1283 |
|
Ticket flags: FORWARDED (4) $ @end example |
|
- @end cartouche |
|
@c ********************************************************** |
| Line 1334 |
|
store the password in your customized database, in which case being able to change it via the Shisa interface can be useful. |
|
- Shisa is a small (a few thousand lines of C code) standalone library. - Shisa does not depend on the Shishi library. Because a user database - with passwords may be useful for other applications as well (e.g., - @acronym{GNU} @acronym{SASL}), it may be separated into its own |
|
+ Shisa is a small (a few thousand lines of @acronym{C} code) standalone + library. Shisa does not depend on the Shishi library. Because a user + database with passwords may be useful for other applications as well + (e.g., @acronym{GNU} @acronym{SASL}), it may be separated into its own |
|
project later on. You should keep this in mind, so that you don't consider writing a Shisa backend for your own database a purely Shishi specific project. You may, for example, chose to use the Shisa |
| Line 1413 |
|
krbtgt/latte Account is enabled. Current key version 0 (0x0). |
|
+ Key 0 (0x0). + Etype aes256-cts-hmac-sha1-96 (0x12, 18). + Salt lattekrbtgt/latte. |
|
host/latte Account is enabled. Current key version 0 (0x0). |
|
+ Key 0 (0x0). + Etype aes256-cts-hmac-sha1-96 (0x12, 18). + Salt lattehost/latte. |
|
jas@@latte:~/src/shishi$ @end example |
| Line 1514 |
|
Currently, there are no properties associated with entire realms. In the future, it may be possible to set a default realm-wide password |
|
- expiry policy or similar. |
|
+ expiry policy or similar. Each realm normally have one principal that + is used for authenticating against the ``ticket granting service'' on + the Kerberos server with a ticket instead of using the password. This + is used by the user when she acquire a ticket for servers. This + principal must look like @samp{krbtgt/REALM} (@pxref{krbtgt,,Name of + the TGS}). Let's create it. |
|
|
|
+ @example + jas@@latte:~/src/shishi/doc$ shisa -a EXAMPLE.ORG krbtgt/EXAMPLE.ORG + Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'... + Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...done + jas@@latte:~/src/shishi/doc$ + @end example |
|
|
|
+ Now that wasn't difficult, although not very satisfying either. What + does adding a principal mean? The name is created, obviously, but it + also mean setting a few values in the database. Let's view the entry + to find out which values. + + @example + jas@@latte:~/src/shishi/doc$ shisa -d + EXAMPLE.ORG + krbtgt/EXAMPLE.ORG + Account is enabled. + Current key version 0 (0x0). + Key 0 (0x0). + Etype aes256-cts-hmac-sha1-96 (0x12, 18). + Salt EXAMPLE.ORGkrbtgt/EXAMPLE.ORG. + jas@@latte:~/src/shishi/doc$ + @end example + + To use host based security services like @acronym{SSH} or Telnet with + Kerberos, each host must have a key shared between the host and the + KDC. The key is typically stored in + @file{/usr/local/etc/shishi/shishi.keys}. We assume your server is + called @samp{mail.example.org} and create the principal. To + illustrate a new parameter, we also set the specific algorithm to use + by using the @samp{--encryption-type} (short form @samp{-E}) + parameter. + + @example + jas@@latte:~/src/shishi/src$ shisa -a EXAMPLE.ORG host/mail.example.org -E des3 + Adding principal `host/mail.example.org@@EXAMPLE.ORG'... + Adding principal `host/mail.example.org@@EXAMPLE.ORG'...done + jas@@latte:~/src/shishi/src$ + @end example + + To export the key, there is another Shisa parameter @samp{--keys} that + will print the key in a format that is recognized by Shishi. Let's + use it to print the host key. + + @example + jas@@latte:~/src/shishi/doc$ shisa -d --keys EXAMPLE.ORG host/mail.example.org + EXAMPLE.ORG + host/mail.example.org + Account is enabled. + Current key version 0 (0x0). + Key 0 (0x0). + Etype des3-cbc-sha1-kd (0x10, 16). + -----BEGIN SHISHI KEY----- + Keytype: 16 (des3-cbc-sha1-kd) + Principal: host/mail.example.org + Realm: EXAMPLE.ORG + + iQdA8hxdvOUHZNliZJv7noM02rXHV8gq + -----END SHISHI KEY----- + Salt EXAMPLE.ORGhost/mail.example.org. + jas@@latte:~/src/shishi/doc$ + @end example + + So to set up the host, simply redirect output to the host key file. + + @example + jas@@latte:~/src/shishi/src$ shisa -d --keys EXAMPLE.ORG \ + host/mail.example.org > /usr/local/etc/shishi/shishi.keys + jas@@latte:~/src/shishi/src$ + @end example + + The next logical step is to create a principal for some user, so you + can use your password to get a Ticket Granting Ticket via the + Authentication Service (AS) from the KDC, and then use the Ticket + Granting Service (TGS) from the KDC to get a ticket for a specific + host, and then send that ticket to the host to authenticate yourself. + Creating this end-user principle is slightly different from the + earlier steps, because you want the key to be derived from a password + instead of being a random key. The @samp{--password} parameter + indicate this. This make the tool ask you for the password. + + @example + jas@@latte:~/src/shishi/doc$ shisa -a EXAMPLE.ORG simon --password + Password for `simon@@EXAMPLE.ORG': + Adding principal `simon@@EXAMPLE.ORG'... + Adding principal `simon@@EXAMPLE.ORG'...done + jas@@latte:~/src/shishi/doc$ + @end example + + The only special thing about this principal now is that it has a + @code{password} field set in the database. + + @example + jas@@latte:~/src/shishi/doc$ shisa -d EXAMPLE.ORG simon --keys + EXAMPLE.ORG + simon + Account is enabled. + Current key version 0 (0x0). + Key 0 (0x0). + Etype aes256-cts-hmac-sha1-96 (0x12, 18). + -----BEGIN SHISHI KEY----- + Keytype: 18 (aes256-cts-hmac-sha1-96) + Principal: simon + Realm: EXAMPLE.ORG + + Ja7ciNtrAI3gtodLaVDQ5zhcH58ffk0kS5tGAM7ILvM= + -----END SHISHI KEY----- + Salt EXAMPLE.ORGsimon. + Password foo. + jas@@latte:~/src/shishi/doc$ + @end example + + You should now be ready to start the KDC, which is explained in the + next section (@pxref{Starting Shishid}), and get tickets as explained + earlier (@pxref{User Manual}). |
|
@node Starting Shishid @section Starting Shishid |
|
- TBW |
|
+ The Shishi server, or Key Distribution Center (KDC), is called + Shishid. Shishid is responsible for listening on UDP and TCP ports + for Kerberos requests. Currently it can handle initial ticket + requests (Authentication Service, or AS), typically authenticated with + keys derived from passwords, and subsequent ticket requests (Ticket + Granting Service, or TGS), typically authenticated with the key + acquired during an AS exchange. + + Currently there is very little configuration available, the only + variables are which ports the server should listen on and an optional + user name to @code{setuid} into after successfully listening to the + ports. + + By default, Shishid listens on the @samp{kerberos} service port + (typically translated to 88 via @file{/etc/services}) on the UDP and + TCP protocols via IPv4 and (if your machine support it) IPv6 on all + interfaces on your machine. Here is a typical startup. + + @example + latte:/home/jas/src/shishi# /usr/local/sbin/shishid + Initializing GNUTLS... + Initializing GNUTLS...done + Listening on IPv4:*:kerberos/udp...done + Listening on IPv4:*:kerberos/tcp...done + Listening on IPv6:*:kerberos/udp...failed + socket: Address family not supported by protocol + Listening on IPv6:*:kerberos/tcp...failed + socket: Address family not supported by protocol + Listening on 2 ports... + @end example + + Running as root is not recommended. Any security problem in shishid + and your host may be compromised. Therefor, we recommend using the + @samp{--setuid} parameter, as follows. + + @example + latte:/home/jas/src/shishi# /usr/local/sbin/shishid --setuid=jas + Initializing GNUTLS... + Initializing GNUTLS...done + Listening on IPv4:*:kerberos/udp...done + Listening on IPv4:*:kerberos/tcp...done + Listening on IPv6:*:kerberos/udp...failed + socket: Address family not supported by protocol + Listening on IPv6:*:kerberos/tcp...failed + socket: Address family not supported by protocol + Listening on 2 ports... + User identity set to `jas' (22541)... + @end example + + An alternative is to run shishid on an alternative port as a + non-privileged user. To continue the example of setting up the + @code{EXAMPLE.ORG} realm as a non-privileged user from the preceding + section, we start the server listen on port 4711 via UDP on IPv4. + + @example + jas@@latte:~/src/shishi$ ~/sbin/shishid -l IPv4:*:4711/udp + Initializing GNUTLS... + Initializing GNUTLS...done + Listening on IPv4:*:4711/udp...done + Listening on 1 ports... + @end example + + If you have set up the Shisa database as in the previous example, you + can now acquire tickets as follows. + + @example + jas@@latte:~/src/shishi$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \ + simon@@EXAMPLE.ORG + Enter password for `simon@@EXAMPLE.ORG': + simon@@EXAMPLE.ORG: + Authtime: Fri Dec 12 01:41:01 2003 + Endtime: Fri Dec 12 01:57:41 2003 + Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18) + Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18) + Ticket flags: FORWARDED PROXIABLE RENEWABLE INITIAL (12) + jas@@latte:~/src/shishi$ + @end example + + The output from Shishid on a successful invocation would look like: + + @example + Has 131 bytes from IPv4:*:4711/udp + ASN.1 msg-type 10 (0xa)... + Processing AS-REQ... + servername krbtgt/EXAMPLE.ORG + client & server realm EXAMPLE.ORG + Found server krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG... + username simon + Found user simon@@EXAMPLE.ORG... + Found keys for server krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG... + Found keys for user simon@@EXAMPLE.ORG... + Trying etype 18... + Matching against server etype 18... + Matching against user etype 18... + @end example + + You may use the '-v' parameter for Shishid and Shishi to generate more + debugging information. + + To illustrate what an application, such as the Shishi patched versions + of @acronym{GNU} lsh or Telnet from @acronym{GNU} InetUtils, would do + when contacting the host @samp{mail.example.org} we illustrate using + the TGS service as well. + + @example + jas@@latte:~/src/shishi$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \ + simon@@EXAMPLE.ORG host/mail.example.org + simon@@EXAMPLE.ORG: + Authtime: Fri Dec 12 01:46:54 2003 + Endtime: Fri Dec 12 02:03:34 2003 + Server: host/mail.example.org key des3-cbc-sha1-kd (16) + Ticket key: des3-cbc-sha1-kd (16) protected by aes256-cts-hmac-sha1-96 (18) + Ticket flags: FORWARDED PROXIABLE (45398796) + jas@@latte:~/src/shishi$ + @end example + + This conclude our walk-through of setting up a new Kerberos realm + using Shishi. It is quite likely that one or more steps failed, and + if so we encourage you to debug it and submit a patch, or at least + report it as a problem. Heck, even letting us know if you got this + far would be of interest. @xref{Bug Reports}. |
|
@node Multiple servers @section Multiple servers |
| Line 2119 |
|
to lower case, without performing any other modifications or canonicalization. |
|
+ @subsection Principal Name Form + + Principal names consist of a sequence of strings, which is often + tedious to parse. Therefor, Shishi often uses a ``printed'' form of + principal which embed the entire principal name string sequence, and + optionally also the realm, into one string. The format is taken from + the Kerberos 5 @acronym{GSS-API} mechanism (@acronym{RFC} 1964). + + The elements included within this name representation are as follows, + proceeding from the beginning of the string: + + @enumerate + @item + One or more principal name components; if more than one + principal name component is included, the components are + separated by `/`. Arbitrary octets may be included within + principal name components, with the following constraints and + special considerations: + @enumerate a + @item + Any occurrence of the characters `@@` or `/` within a + name component must be immediately preceded by the `\` + quoting character, to prevent interpretation as a component + or realm separator. + @item + The ASCII newline, tab, backspace, and null characters + may occur directly within the component or may be + represented, respectively, by `\n`, `\t`, `\b`, or `\0`. + @item + If the `\` quoting character occurs outside the contexts + described in (1a) and (1b) above, the following character is + interpreted literally. As a special case, this allows the + doubled representation `\\` to represent a single occurrence + of the quoting character. + @item + An occurrence of the `\` quoting character as the last + character of a component is illegal. + @end enumerate + @item + Optionally, a `@@` character, signifying that a realm name + immediately follows. If no realm name element is included, the + local realm name is assumed. The `/` , `:`, and null characters + may not occur within a realm name; the `@@`, newline, tab, and + backspace characters may be included using the quoting + conventions described in (1a), (1b), and (1c) above. + @end enumerate + |
|
@node Shishi Configuration @section Shishi Configuration @cindex configuration file |
| [Prev in Thread] | Current Thread | [Next in Thread] |