diff options
Diffstat (limited to 'client')
| -rw-r--r-- | client/file.c | 29 | ||||
| -rw-r--r-- | client/internal.h | 37 | ||||
| -rw-r--r-- | client/keytab.c | 48 | ||||
| -rw-r--r-- | client/krb5.c | 53 | ||||
| -rw-r--r-- | client/remctl.c | 61 | ||||
| -rw-r--r-- | client/srvtab.c | 28 | ||||
| -rw-r--r-- | client/wallet.1 | 513 | ||||
| -rw-r--r-- | client/wallet.c | 48 | ||||
| -rw-r--r-- | client/wallet.pod | 79 |
9 files changed, 709 insertions, 187 deletions
diff --git a/client/file.c b/client/file.c index c109bd5..66d5f63 100644 --- a/client/file.c +++ b/client/file.c @@ -1,9 +1,8 @@ -/* $Id$ - * +/* * File handling for the wallet client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ @@ -16,7 +15,9 @@ #include <sys/stat.h> #include <client/internal.h> -#include <util/util.h> +#include <util/concat.h> +#include <util/messages.h> +#include <util/xmalloc.h> /* * Given a filename, some data, and a length, write that data to the given @@ -114,14 +115,13 @@ get_file(struct remctl *r, const char *prefix, const char *type, /* - * Read all of a file into memory and return the contents as a newly allocated - * string. Handles a file name of "-" to mean standard input. Dies on any - * failure. - * - * This will need modification later when we want to handle nul characters. + * Read all of a file into memory and return the contents in newly allocated + * memory. Returns the size of the file contents in the second argument if + * it's not NULL. Handles a file name of "-" to mean standard input. Dies on + * any failure. */ -char * -read_file(const char *name) +void * +read_file(const char *name, size_t *length) { char *contents; size_t size, offset; @@ -139,7 +139,7 @@ read_file(const char *name) sysdie("cannot open file %s", name); if (fstat(fd, &st) < 0) sysdie("cannot stat file %s", name); - size = st.st_size + 1; + size = st.st_size; contents = xmalloc(size); } offset = 0; @@ -156,8 +156,7 @@ read_file(const char *name) offset += status; } while (status > 0); close(fd); - contents[offset] = '\0'; - if (memchr(contents, '\0', offset) != NULL) - die("cannot yet handle file data containing nul characters"); + if (length != NULL) + *length = offset; return contents; } diff --git a/client/internal.h b/client/internal.h index e55f2b8..d82196c 100644 --- a/client/internal.h +++ b/client/internal.h @@ -1,9 +1,8 @@ -/* $Id$ - * +/* * Internal support functions for the wallet client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ @@ -12,31 +11,37 @@ #define CLIENT_INTERNAL_H 1 #include <portable/macros.h> +#include <portable/krb5.h> -#include <krb5.h> #include <sys/types.h> /* Forward declarations to avoid unnecessary includes. */ struct remctl; +struct iovec; BEGIN_DECLS /* * Given a Kerberos context and a principal name, obtain Kerberos credentials - * for that principal and store them in a memory cache for use by later - * operations. + * for that principal and store them in a temporary ticket cache for use by + * later operations. kdestroy() then cleans up that cache. */ void kinit(krb5_context, const char *principal); +void kdestroy(void); /* - * Given a remctl object, run a remctl command. If data is non-NULL, saves - * the standard output from the command into data with the length in length. - * Otherwise, prints it to standard output. Either way, prints standard error - * output and errors to standard error and returns the exit status or 255 for - * a remctl internal error. + * Given a remctl object, either a NULL-terminated array of strings or an + * array of iovecs and the number of elements in the array, and optional data + * and size output variables, run a remctl command. If data is non-NULL, + * saves the standard output from the command into data with the length in + * length. Otherwise, prints it to standard output. Either way, prints + * standard error output and errors to standard error and returns the exit + * status or 255 for a remctl internal error. */ int run_command(struct remctl *, const char **command, char **data, size_t *length); +int run_commandv(struct remctl *, const struct iovec *command, size_t count, + char **data, size_t *length); /* * Check whether an object exists using the exists wallet interface. Returns @@ -91,12 +96,12 @@ void write_srvtab(krb5_context, const char *srvtab, const char *principal, const char *keytab); /* - * Read all of a file into memory and return the contents as a newly allocated - * string. Handles a file name of "-" to mean standard input. Dies on any - * failure. This will need modification later when we want to handle nul - * characters. + * Read all of a file into memory and return the contents in newly allocated + * memory. Handles a file name of "-" to mean standard input. Stores the + * length of the data in the second argument if it isn't NULL. Dies on any + * failure. */ -char *read_file(const char *); +void *read_file(const char *, size_t *); END_DECLS diff --git a/client/keytab.c b/client/keytab.c index eb37ec1..5f2076f 100644 --- a/client/keytab.c +++ b/client/keytab.c @@ -1,20 +1,22 @@ -/* $Id$ - * +/* * Implementation of keytab handling for the wallet client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ #include <config.h> +#include <portable/krb5.h> #include <portable/system.h> #include <remctl.h> #include <client/internal.h> -#include <util/util.h> +#include <util/concat.h> +#include <util/messages-krb5.h> +#include <util/messages.h> /* @@ -48,7 +50,7 @@ merge_keytab(krb5_context ctx, const char *newfile, const char *file) status = krb5_kt_add_entry(ctx, old, &entry); if (status != 0) die_krb5(ctx, status, "cannot write to keytab %s", file); - krb5_free_keytab_entry_contents(ctx, &entry); + krb5_kt_free_entry(ctx, &entry); } if (status != KRB5_KT_END) die_krb5(ctx, status, "error reading temporary keytab %s", newfile); @@ -61,39 +63,6 @@ merge_keytab(krb5_context ctx, const char *newfile, const char *file) /* - * Configure a given keytab to be synchronized with an AFS kaserver if it - * isn't already. Returns true on success, false on failure. - */ -static int -set_sync(struct remctl *r, const char *type, const char *name) -{ - const char *command[7]; - char *data = NULL; - size_t length = 0; - int status; - - command[0] = type; - command[1] = "getattr"; - command[2] = "keytab"; - command[3] = name; - command[4] = "sync"; - command[5] = NULL; - status = run_command(r, command, &data, &length); - if (status != 0) - return 0; - if (data == NULL || strstr(data, "kaserver\n") == NULL) { - command[1] = "setattr"; - command[5] = "kaserver"; - command[6] = NULL; - status = run_command(r, command, NULL, NULL); - if (status != 0) - return 0; - } - return 1; -} - - -/* * Given a remctl object, the Kerberos context, the name of a keytab object, * and a file name, call the correct wallet commands to download a keytab and * write it to that file. Returns the setatus or 255 on an internal error. @@ -108,9 +77,6 @@ get_keytab(struct remctl *r, krb5_context ctx, const char *type, size_t length = 0; int status; - if (srvtab != NULL) - if (!set_sync(r, type, name)) - return 255; command[0] = type; command[1] = "get"; command[2] = "keytab"; diff --git a/client/krb5.c b/client/krb5.c index fd600da..38172ae 100644 --- a/client/krb5.c +++ b/client/krb5.c @@ -1,5 +1,4 @@ -/* $Id$ - * +/* * Kerberos support functions for the wallet client. * * Currently, the only function here is one to obtain a ticket cache for a @@ -7,7 +6,7 @@ * client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University */ #include <config.h> @@ -16,10 +15,8 @@ #include <krb5.h> #include <client/internal.h> -#include <util/util.h> - -/* The memory cache used for wallet authentication. */ -#define CACHE_NAME "MEMORY:wallet" +#include <util/messages-krb5.h> +#include <util/messages.h> /* @@ -33,32 +30,58 @@ kinit(krb5_context ctx, const char *principal) krb5_principal princ; krb5_ccache ccache; krb5_creds creds; - krb5_get_init_creds_opt opts; + krb5_get_init_creds_opt *opts; krb5_error_code status; + char cache_name[] = "/tmp/krb5cc_wallet_XXXXXX"; + int fd; /* Obtain a TGT. */ status = krb5_parse_name(ctx, principal, &princ); if (status != 0) die_krb5(ctx, status, "invalid Kerberos principal %s", principal); - krb5_get_init_creds_opt_init(&opts); + status = krb5_get_init_creds_opt_alloc(ctx, &opts); + if (status != 0) + die_krb5(ctx, status, "cannot allocate credential options"); + krb5_get_init_creds_opt_set_default_flags(ctx, "wallet", princ->realm, + opts); memset(&creds, 0, sizeof(creds)); status = krb5_get_init_creds_password(ctx, &creds, princ, NULL, - krb5_prompter_posix, NULL, 0, NULL, &opts); + krb5_prompter_posix, NULL, 0, NULL, opts); if (status != 0) die_krb5(ctx, status, "authentication failed"); - /* Put the new credentials into a memory cache. */ - status = krb5_cc_resolve(ctx, CACHE_NAME, &ccache); + /* Put the new credentials into a ticket cache. */ + fd = mkstemp(cache_name); + if (fd < 0) + sysdie("cannot create temporary ticket cache %s", cache_name); + status = krb5_cc_resolve(ctx, cache_name, &ccache); if (status != 0) - die_krb5(ctx, status, "cannot create cache %s", CACHE_NAME); + die_krb5(ctx, status, "cannot create cache %s", cache_name); status = krb5_cc_initialize(ctx, ccache, princ); if (status != 0) - die_krb5(ctx, status, "cannot initialize cache %s", CACHE_NAME); + die_krb5(ctx, status, "cannot initialize cache %s", cache_name); krb5_free_principal(ctx, princ); status = krb5_cc_store_cred(ctx, ccache, &creds); if (status != 0) die_krb5(ctx, status, "cannot store credentials"); krb5_cc_close(ctx, ccache); - if (putenv((char *) "KRB5CCNAME=" CACHE_NAME) != 0) + close(fd); + if (setenv("KRB5CCNAME", cache_name, 1) < 0) sysdie("cannot set KRB5CCNAME"); } + + +/* + * Clean up the temporary ticket cache created by kinit(). + */ +void +kdestroy(void) +{ + const char *cache; + + cache = getenv("KRB5CCNAME"); + if (cache == NULL) + die("cannot destroy temporary ticket cache: KRB5CCNAME is not set"); + if (unlink(cache) < 0) + sysdie("cannot destroy temporary ticket cache"); +} diff --git a/client/remctl.c b/client/remctl.c index 8b9702a..5a541d5 100644 --- a/client/remctl.c +++ b/client/remctl.c @@ -1,9 +1,8 @@ -/* $Id$ - * +/* * remctl interface for the wallet client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2010 Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ @@ -14,19 +13,19 @@ #include <remctl.h> #include <client/internal.h> -#include <util/util.h> +#include <util/messages.h> +#include <util/xmalloc.h> /* - * Given a remctl connection and a command, run the command. - * - * If data is non-NULL, save the output in it and return the length in length. - * Otherwise, send any output to stdout. Either way, send error output to - * stderr, and return the exit status (or 255 if there is an error). + * Retrieve the results of a remctl command, which should be issued prior to + * calling this function. If data is non-NULL, save the output in it and + * return the length in length. Otherwise, send any output to stdout. Either + * way, send error output to stderr, and return the exit status (or 255 if + * there is an error). */ -int -run_command(struct remctl *r, const char **command, char **data, - size_t *length) +static int +command_results(struct remctl *r, char **data, size_t *length) { struct remctl_output *output; int status = 255; @@ -35,10 +34,6 @@ run_command(struct remctl *r, const char **command, char **data, *data = NULL; if (length != NULL) *length = 0; - if (!remctl_command(r, command)) { - warn("%s", remctl_error(r)); - return 255; - } do { output = remctl_output(r); switch (output->type) { @@ -74,6 +69,40 @@ run_command(struct remctl *r, const char **command, char **data, /* + * Given a remctl connection and a NULL-terminated array of strings, run the + * command and return the results using command_results, optionally putting + * output into the data variable. + */ +int +run_command(struct remctl *r, const char **command, char **data, + size_t *length) +{ + if (!remctl_command(r, command)) { + warn("%s", remctl_error(r)); + return 255; + } + return command_results(r, data, length); +} + + +/* + * Given a remctl connection, an array of iovecs, and the length of the array, + * run the command and return the results using command_results, optionally + * putting output into the data variable. + */ +int +run_commandv(struct remctl *r, const struct iovec *command, size_t count, + char **data, size_t *length) +{ + if (!remctl_commandv(r, command, count)) { + warn("%s", remctl_error(r)); + return 255; + } + return command_results(r, data, length); +} + + +/* * Check whether an object exists using the exists wallet interface. Returns * true if it does, false if it doesn't, and dies on remctl errors. */ diff --git a/client/srvtab.c b/client/srvtab.c index 2e4ea2d..b26e6fc 100644 --- a/client/srvtab.c +++ b/client/srvtab.c @@ -1,20 +1,19 @@ -/* $Id$ - * +/* * Implementation of srvtab handling for the wallet client. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University + * Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ #include <config.h> +#include <portable/krb5.h> #include <portable/system.h> -#include <krb5.h> - #include <client/internal.h> -#include <util/util.h> +#include <util/messages-krb5.h> +#include <util/messages.h> #ifndef KRB5_KRB4_COMPAT # define ANAME_SZ 40 @@ -29,10 +28,6 @@ * keytab and write it to the newly created srvtab file as a srvtab. Convert * the principal from Kerberos v5 form to Kerberos v4 form. * - * We always force the kvno to 0 for the srvtab. This works with how the - * wallet synchronizes keys with kasetkey, even though it's not particularly - * correct. - * * On any failure, print an error message to standard error and then exit. */ void @@ -59,8 +54,13 @@ write_srvtab(krb5_context ctx, const char *srvtab, const char *principal, ret = krb5_kt_get_entry(ctx, kt, princ, 0, ENCTYPE_DES_CBC_CRC, &entry); if (ret != 0) die_krb5(ctx, ret, "error reading DES key from keytab %s", keytab); +#ifdef HAVE_KRB5_KEYTAB_ENTRY_KEYBLOCK + if (entry.keyblock.keyvalue.length != 8) + die("invalid DES key length in keytab"); +#else if (entry.key.length != 8) die("invalid DES key length in keytab"); +#endif krb5_kt_close(ctx, kt); /* Convert the principal to a Kerberos v4 principal. */ @@ -80,10 +80,14 @@ write_srvtab(krb5_context ctx, const char *srvtab, const char *principal, strcpy(data + length, realm); length += strlen(realm); data[length++] = '\0'; - data[length++] = '\0'; + data[length++] = (unsigned char) entry.vno; +#ifdef HAVE_KRB5_KEYTAB_ENTRY_KEYBLOCK + memcpy(data + length, entry.keyblock.keyvalue.data, 8); +#else memcpy(data + length, entry.key.contents, 8); +#endif length += 8; - krb5_free_keytab_entry_contents(ctx, &entry); + krb5_kt_free_entry(ctx, &entry); /* Write out the srvtab file. */ write_file(srvtab, data, length); diff --git a/client/wallet.1 b/client/wallet.1 new file mode 100644 index 0000000..1b25ec9 --- /dev/null +++ b/client/wallet.1 @@ -0,0 +1,513 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "WALLET 1" +.TH WALLET 1 "2010-02-20" "0.10" "wallet" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +wallet \- Client for retrieving secure data from a central server +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBwallet\fR [\fB\-hv\fR] [\fB\-c\fR \fIcommand\fR] [\fB\-f\fR \fIfile\fR] + [\fB\-k\fR \fIprincipal\fR] [\fB\-p\fR \fIport\fR] [\fB\-s\fR\ \fIserver\fR] + [\fB\-S\fR \fIsrvtab\fR] [\fB\-u\fR \fIprincipal\fR] \fIcommand\fR [\fIarg\fR ...] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBwallet\fR is a client for the wallet system, which stores or creates +secure information such as Kerberos keytabs, associates them with ACLs and +other metadata, and allows clients to view and download them. This client +provides the user interface to the wallet system for both users and wallet +administrators. +.PP +The \fBwallet\fR command-line client takes a command and optional arguments +on the command line, authenticates to the wallet server using Kerberos, +and sends that command and arguments to server. It then reads the results +and displays them to the user or stores them in a file. The client itself +does not know which commands are valid and which aren't; apart from some +special handling of particular commands, it sends all commands to the +server to respond to appropriately. This allows additional commands to be +added to the wallet system without changing all of the clients. +.PP +The primary commands of the wallet system are \f(CW\*(C`get\*(C'\fR, which retrieves some +secure data from the wallet, \f(CW\*(C`store\*(C'\fR, which stores some secure data in +the wallet, and \f(CW\*(C`show\*(C'\fR, which stores the metadata about an object stored +in the wallet. Each object in the wallet has a type, which determines +what data the object represents and may determine special handling when +downloading or storing that object, and a name. For example, a wallet +object for the \f(CW\*(C`host/example.com\*(C'\fR Kerberos keytab would have a type of +\&\f(CW\*(C`keytab\*(C'\fR and a name of \f(CW\*(C`host/example.com\*(C'\fR. The meaning of the name is +specific to each type of object. +.PP +Most other wallet commands besides those three are only available to +wallet administrators. The exception is attribute commands; see +\&\s-1ATTRIBUTES\s0. The other commands allow setting ownership and ACLs on +objects, creating and destroying objects, creating and destroying ACLs, +and adding and removing entries from ACLs. An \s-1ACL\s0 consists of one or more +entries, each of which is a scheme and an identifier. A scheme specifies +a way of checking whether a user is authorized. An identifier is some +data specific to the scheme that specifies which users are authorized. +For example, for the \f(CW\*(C`krb5\*(C'\fR scheme, the identifier is a principal name +and only that principal is authorized by that \s-1ACL\s0 entry. +.PP +To run the wallet command-line client, you must either already have a +Kerberos ticket or use the \fB\-u\fR option. You can obtain a Kerberos ticket +with \fBkinit\fR and see your current Kerberos tickets with \fBklist\fR. The +wallet client uses the remctl protocol to talk to the wallet server. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-c\fR \fIcommand\fR" 4 +.IX Item "-c command" +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (\f(CW\*(C`wallet\*(C'\fR) should be fine. It may +sometimes be useful to use a different prefix for testing a different +version of the wallet code on the server. This option can also be set in +\&\fIkrb5.conf\fR; see \s-1CONFIGURATION\s0 below. +.IP "\fB\-f\fR \fIfile\fR" 4 +.IX Item "-f file" +This flag is only used in combination with the \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`store\*(C'\fR +commands. For \f(CW\*(C`get\*(C'\fR, rather than sending the secure data to standard +output (the default), the secure data will be stored in \fIfile\fR. For +\&\f(CW\*(C`store\*(C'\fR, the data to be stored will be read from \fIfile\fR. +.Sp +With \f(CW\*(C`get\*(C'\fR, if the object being retrieved is not a keytab object, any +current file named \fIoutput\fR is renamed to \fI\fIoutout\fI.bak\fR before the new +file is created. \fI\fIoutout\fI.new\fR is used as a temporary file and any +existing file with that name will be deleted. +.Sp +If the object being retrieved is a keytab object and the file \fIoutput\fR +already exists, the downloaded keys will be added to the existing keytab +file \fIoutput\fR. Old keys are not removed; you may wish to run \f(CW\*(C`kadmin +ktremove\*(C'\fR or an equivalent later to clean up old keys. \fI\fIoutput\fI.new\fR +is still used as a temporary file and any existing file with that name +will be deleted. +.IP "\fB\-k\fR \fIprincipal\fR" 4 +.IX Item "-k principal" +The service principal of the wallet server. The default is to use the +\&\f(CW\*(C`host\*(C'\fR principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by \fBremctld\fR on the wallet server. +This option can also be set in \fIkrb5.conf\fR; see \s-1CONFIGURATION\s0 below. +.IP "\fB\-h\fR" 4 +.IX Item "-h" +Display a brief summary of options and exit. All other valid options and +commands are ignored. +.IP "\fB\-p\fR \fIport\fR" 4 +.IX Item "-p port" +The port to connect to on the wallet server. The default is the default +remctl port. This option can also be set in \fIkrb5.conf\fR; see +\&\s-1CONFIGURATION\s0 below. +.IP "\fB\-S\fR \fIsrvtab\fR" 4 +.IX Item "-S srvtab" +This flag is only used in combination with the \f(CW\*(C`get\*(C'\fR command on a +\&\f(CW\*(C`keytab\*(C'\fR object, and must be used in conjunction with the \fB\-f\fR flag. +After the keytab is saved to the file specified by \fB\-f\fR, the \s-1DES\s0 key for +that principal will be extracted and written as a Kerberos v4 srvtab to +the file \fIsrvtab\fR. Any existing contents of \fIsrvtab\fR will be +destroyed. +.Sp +The Kerberos v4 principal name will be generated from the Kerberos v5 +principal name using the \fIkrb5_524_conv_principal()\fR function of the +Kerberos libraries. See its documentation for more information, but +briefly (and in the absence of special configuration), the Kerberos v4 +principal name will be the same as the Kerberos v5 principal name except +that the components are separated by \f(CW\*(C`.\*(C'\fR instead of \f(CW\*(C`/\*(C'\fR; the second +component is truncated after the first \f(CW\*(C`.\*(C'\fR if the first component is one +of the recognized host-based principals (generally \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`imap\*(C'\fR, +\&\f(CW\*(C`pop\*(C'\fR, or \f(CW\*(C`smtp\*(C'\fR); and the first component is \f(CW\*(C`rcmd\*(C'\fR if the Kerberos v5 +principal component is \f(CW\*(C`host\*(C'\fR. The principal name must not contain more +than two components. +.IP "\fB\-s\fR \fIserver\fR" 4 +.IX Item "-s server" +The wallet server to connect to. The default may be set when compiling +the wallet client. If it isn't, either \fB\-s\fR must be given or the server +must be set in \fIkrb5.conf\fR. See \s-1CONFIGURATION\s0 below. +.IP "\fB\-u\fR \fIprincipal\fR" 4 +.IX Item "-u principal" +Rather than using the user's existing ticket cache for authentication, +authenticate as \fIprincipal\fR first and use those credentials for +authentication to the wallet server. \fBwallet\fR will prompt for the +password for \fIprincipal\fR. Non-password authentication methods such as +\&\s-1PKINIT\s0 aren't supported; to use those, run \fBkinit\fR first and use an +existing ticket cache. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +Display the version of the \fBwallet\fR client and exit. All other valid +options and commands are ignored. +.SH "COMMANDS" +.IX Header "COMMANDS" +As mentioned above, most commands are only available to wallet +administrators. The exceptions are \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`destroy\*(C'\fR, +\&\f(CW\*(C`flag clear\*(C'\fR, \f(CW\*(C`flag set\*(C'\fR, \f(CW\*(C`getattr\*(C'\fR, \f(CW\*(C`setattr\*(C'\fR, and \f(CW\*(C`history\*(C'\fR. All +of those commands have their own ACLs except \f(CW\*(C`getattr\*(C'\fR and \f(CW\*(C`history\*(C'\fR, +which use the \f(CW\*(C`show\*(C'\fR \s-1ACL\s0, and \f(CW\*(C`setattr\*(C'\fR, which uses the \f(CW\*(C`store\*(C'\fR \s-1ACL\s0. +If the appropriate \s-1ACL\s0 is set, it alone is checked to see if the user has +access. Otherwise, \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`getattr\*(C'\fR, \f(CW\*(C`setattr\*(C'\fR, and +\&\f(CW\*(C`history\*(C'\fR access is permitted if the user is authorized by the owner \s-1ACL\s0 +of the object. +.PP +Administrators can run any command on any object or \s-1ACL\s0 except for \f(CW\*(C`get\*(C'\fR +and \f(CW\*(C`store\*(C'\fR. For \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`show\*(C'\fR, they must still be authorized by +either the appropriate specific \s-1ACL\s0 or the owner \s-1ACL\s0. +.PP +If the locked flag is set on an object, no commands can be run on that +object that change data except the \f(CW\*(C`flags\*(C'\fR commands, nor can the \f(CW\*(C`get\*(C'\fR +command be used on that object. \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`history\*(C'\fR, \f(CW\*(C`getacl\*(C'\fR, +\&\f(CW\*(C`getattr\*(C'\fR, and \f(CW\*(C`owner\*(C'\fR or \f(CW\*(C`expires\*(C'\fR without an argument can still be +used on that object. +.PP +For more information on attributes, see \s-1ATTRIBUTES\s0. +.IP "acl add <id> <scheme> <identifier>" 4 +.IX Item "acl add <id> <scheme> <identifier>" +Adds an entry with <scheme> and <identifier> to the \s-1ACL\s0 <id>. <id> may be +either the name of an \s-1ACL\s0 or its numeric identifier. +.IP "acl create <name>" 4 +.IX Item "acl create <name>" +Create a new, empty \s-1ACL\s0 with name <name>. When setting an \s-1ACL\s0 on an +object with a set of entries that don't match an existing \s-1ACL\s0, first +create a new \s-1ACL\s0 with \f(CW\*(C`acl create\*(C'\fR, add the appropriate entries to it +with \f(CW\*(C`acl add\*(C'\fR, and then set the \s-1ACL\s0 on an object with the \f(CW\*(C`owner\*(C'\fR or +\&\f(CW\*(C`setacl\*(C'\fR commands. +.IP "acl destroy <id>" 4 +.IX Item "acl destroy <id>" +Destroy the \s-1ACL\s0 <id>. This \s-1ACL\s0 must no longer be referenced by any object +or the \s-1ACL\s0 destruction will fail. The special \s-1ACL\s0 named \f(CW\*(C`ADMIN\*(C'\fR cannot +be destroyed. +.IP "acl history <id>" 4 +.IX Item "acl history <id>" +Display the history of the \s-1ACL\s0 <id>. Each change to the \s-1ACL\s0 (not +including changes to the name of the \s-1ACL\s0) will be represented by two +lines. The first line will have a timestamp of the change followed by a +description of the change, and the second line will give the user who made +the change and the host from which the change was made. +.IP "acl remove <id> <scheme> <identifier>" 4 +.IX Item "acl remove <id> <scheme> <identifier>" +Remove the entry with <scheme> and <identifier> from the \s-1ACL\s0 <id>. <id> +may be either the name of an \s-1ACL\s0 or its numeric identifier. The last +entry in the special \s-1ACL\s0 \f(CW\*(C`ADMIN\*(C'\fR cannot be removed to protect against +accidental lockout, but administrators can remove themselves from the +\&\f(CW\*(C`ADMIN\*(C'\fR \s-1ACL\s0 and can leave only a non-functioning entry on the \s-1ACL\s0. Use +caution when removing entries from the \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL\s0. +.IP "acl show <id>" 4 +.IX Item "acl show <id>" +Display the name, numeric \s-1ID\s0, and entries of the \s-1ACL\s0 <id>. +.IP "autocreate <type> <name>" 4 +.IX Item "autocreate <type> <name>" +Create a new object of type <type> with name <name>. The user must be +listed in the default \s-1ACL\s0 for an object with that type and name, and the +object will be created with that default \s-1ACL\s0 set as the object owner. +.Sp +Normally, there's no need to run this command directly. It's +automatically run when trying to get or store an object that doesn't +already exist. +.IP "check <type> <name>" 4 +.IX Item "check <type> <name>" +Check whether an object of type <type> and name <name> already exists. If +it does, prints \f(CW\*(C`yes\*(C'\fR; if not, prints \f(CW\*(C`no\*(C'\fR. +.IP "create <type> <name>" 4 +.IX Item "create <type> <name>" +Create a new object of type <type> with name <name>. With some backends, +this will trigger creation of an entry in an external system as well. +The new object will have no ACLs and no owner set, so usually the +administrator will want to then set an owner with \f(CW\*(C`owner\*(C'\fR so that the +object will be usable. +.IP "destroy <type> <name>" 4 +.IX Item "destroy <type> <name>" +Destroy the object identified by <type> and <name>. With some backends, +this will trigger destruction of an object in an external system as well. +.IP "expires <type> <name> [<expires>]" 4 +.IX Item "expires <type> <name> [<expires>]" +If <expires> is not given, displays the current expiration of the object +identified by <type> and <name>, or \f(CW\*(C`No expiration set\*(C'\fR if none is set. +The expiration will be displayed in seconds since epoch. +.Sp +If <date> is given, sets the expiration on the object identified by <type> +and <name> to <date> and (if given) <time>. <date> must be in the format +\&\f(CW\*(C`YYYY\-MM\-DD\*(C'\fR and <time> in the format \f(CW\*(C`HH:MM:SS\*(C'\fR. If <date> is the empty +string, clears the expiration of the object. +.Sp +Currently, the expiration of an object is not used. +.IP "flag clear <type> <name> <flag>" 4 +.IX Item "flag clear <type> <name> <flag>" +Clears the flag <flag> on the object identified by <type> and <name>. +.IP "flag set <type> <name> <flag>" 4 +.IX Item "flag set <type> <name> <flag>" +Sets the flag <flag> on the object identified by <type> and <name>. +Recognized flags are \f(CW\*(C`locked\*(C'\fR, which prevents all further actions on that +object until the flag is cleared, and \f(CW\*(C`unchanging\*(C'\fR, which tells the object +backend to not generate new data on get but instead return the same data as +previously returned. The \f(CW\*(C`unchanging\*(C'\fR flag is not meaningful for objects +that do not generate new data on the fly. +.IP "get <type> <name>" 4 +.IX Item "get <type> <name>" +Prints to standard output the data associated with the object identified +by <type> and <name>, or stores it in a file if the \fB\-f\fR option was +given. This may trigger generation of new data and invalidate old data +for that object depending on the object type. +.Sp +If an object with type <type> and name <name> does not already exist when +this command is issued (as checked with the check interface), \fBwallet\fR +will attempt to automatically create it (using autocreate). +.IP "getacl <type> <name> <acl>" 4 +.IX Item "getacl <type> <name> <acl>" +Prints the \s-1ACL\s0 <acl>, which must be one of \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, +\&\f(CW\*(C`destroy\*(C'\fR, or \f(CW\*(C`flags\*(C'\fR, for the object identified by <type> and <name>. +Prints \f(CW\*(C`No ACL set\*(C'\fR if that \s-1ACL\s0 isn't set on that object. Remember that +if the \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, or \f(CW\*(C`show\*(C'\fR ACLs aren't set, authorization falls +back to checking the owner \s-1ACL\s0. See the \f(CW\*(C`owner\*(C'\fR command for displaying +or setting it. +.IP "getattr <type> <name> <attr>" 4 +.IX Item "getattr <type> <name> <attr>" +Prints the object attribute <attr> for the object identified by <type> and +<name>. Attributes are used to store backend-specific information for a +particular object type, and <attr> must be an attribute type known to the +underlying object implementation. The attribute values, if any, are +printed one per line. If the attribute is not set on this object, nothing +is printed. +.IP "history <type> <name>" 4 +.IX Item "history <type> <name>" +Displays the history for the object identified by <type> and <name>. +This human-readable output will have two lines for each action that +changes the object, plus for any get action. The first line has the +timestamp of the action and the action, and the second line gives the user +who performed the action and the host from which they performed it. +.IP "owner <type> <name> [<owner>]" 4 +.IX Item "owner <type> <name> [<owner>]" +If <owner> is not given, displays the current owner \s-1ACL\s0 of the object +identified by <type> and <name>, or \f(CW\*(C`No owner set\*(C'\fR if none is set. The +result will be the name of an \s-1ACL\s0. +.Sp +If <owner> is given, sets the owner of the object identified by <type> and +<name> to <owner>. If <owner> is the empty string, clears the owner of +the object. +.IP "setacl <type> <name> <acl> <id>" 4 +.IX Item "setacl <type> <name> <acl> <id>" +Sets the \s-1ACL\s0 <acl>, which must be one of \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, +\&\f(CW\*(C`destroy\*(C'\fR, or \f(CW\*(C`flags\*(C'\fR, to <id> on the object identified by <type> and +<name>. If <id> is the empty string, clears that \s-1ACL\s0 on the object. +.IP "setattr <type> <name> <attr> <value> [<value> ...]" 4 +.IX Item "setattr <type> <name> <attr> <value> [<value> ...]" +Sets the object attribute <attr> for the object identified by <type> and +<name>. Attributes are used to store backend-specific information for a +particular object type, and <attr> must be an attribute type known to the +underlying object implementation. To clear the attribute for this object, +pass in a <value> of the empty string (\f(CW\*(Aq\*(Aq\fR). +.IP "show <type> <name>" 4 +.IX Item "show <type> <name>" +Displays the current object metadata for the object identified by <type> +and <name>. This human-readable output will show the object type and +name, the owner, any specific ACLs set on the object, the expiration if +any, and the user, remote host, and time when the object was created, last +stored, and last downloaded. +.IP "store <type> <name> [<data>]" 4 +.IX Item "store <type> <name> [<data>]" +Stores <data> for the object identified by <type> and <name> for later +retrieval with \f(CW\*(C`get\*(C'\fR. Not all object types support this. If <data> is +not specified on the command line, it will be read from the file specified +with \fB\-f\fR (if given) or from standard input. +.Sp +If an object with type <type> and name <name> does not already exist when +this command is issued (as checked with the check interface), \fBwallet\fR +will attempt to automatically create it (using autocreate). +.SH "ATTRIBUTES" +.IX Header "ATTRIBUTES" +Object attributes store additional properties and configuration +information for objects stored in the wallet. They are displayed as part +of the object data with \f(CW\*(C`show\*(C'\fR, retrieved with \f(CW\*(C`getattr\*(C'\fR, and set with +\&\f(CW\*(C`setattr\*(C'\fR. +.SS "Keytab Attributes" +.IX Subsection "Keytab Attributes" +Keytab objects support the following attributes: +.IP "enctypes" 4 +.IX Item "enctypes" +Restricts the generated keytab to a specific set of encryption types. The +values of this attribute must be enctype strings recognized by Kerberos +(strings like \f(CW\*(C`aes256\-cts\-hmac\-sha1\-96\*(C'\fR or \f(CW\*(C`des\-cbc\-crc\*(C'\fR). Note that +the salt should not be included; since the salt is irrelevant for keytab +keys, it will always be set to \f(CW\*(C`normal\*(C'\fR by the wallet. +.Sp +If this attribute is set, the specified enctype list will be passed to ktadd +when \fIget()\fR is called for that keytab. If it is not set, the default set in +the \s-1KDC\s0 will be used. +.Sp +This attribute is ignored if the \f(CW\*(C`unchanging\*(C'\fR flag is set on a keytab. +Keytabs retrieved with \f(CW\*(C`unchanging\*(C'\fR set will contain all keys present in +the \s-1KDC\s0 for that Kerberos principal and therefore may contain different +enctypes than those requested by this attribute. +.SH "CONFIGURATION" +.IX Header "CONFIGURATION" +\&\fBwallet\fR can optionally be configured in the system \fIkrb5.conf\fR. It +will read the default \fIkrb5.conf\fR file for the Kerberos libraries with +which it was compiled. To set an option, put the option in the +[appdefaults] section. \fBwallet\fR will look for options either at the top +level of the [appdefaults] section or in a subsection named \f(CW\*(C`wallet\*(C'\fR. +For example, the following fragment of a \fIkrb5.conf\fR file would set the +default port to 4373 and the default server to \f(CW\*(C`wallet.example.org\*(C'\fR. +.PP +.Vb 5 +\& [appdefaults] +\& wallet_port = 4373 +\& wallet = { +\& wallet_server = wallet.example.org +\& } +.Ve +.PP +The supported options are: +.IP "wallet_principal" 4 +.IX Item "wallet_principal" +The service principal of the wallet server. The default is to use the +\&\f(CW\*(C`host\*(C'\fR principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by \fBremctld\fR on the wallet server. +The \fB\-k\fR command-line option overrides this setting. +.IP "wallet_port" 4 +.IX Item "wallet_port" +The port to connect to on the wallet server. The default is the default +remctl port. The \fB\-p\fR command-line option overrides this setting. +.IP "wallet_server" 4 +.IX Item "wallet_server" +The wallet server to connect to. The \fB\-s\fR command-line option overrides +this setting. The default may be set when compiling the wallet client. +If it isn't, either \fB\-s\fR must be given or this parameter must be present +in in \fIkrb5.conf\fR. +.IP "wallet_type" 4 +.IX Item "wallet_type" +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (\f(CW\*(C`wallet\*(C'\fR) should be fine. It may +sometimes be useful to use a different prefix for testing a different +version of the wallet code on the server. The \fB\-c\fR command-line option +overrides this setting. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIkadmin\fR\|(8), \fIkinit\fR\|(1), \fIkrb5.conf\fR\|(5), \fIremctl\fR\|(1), \fIremctld\fR\|(8) +.PP +This program is part of the wallet system. The current version is available +from <http://www.eyrie.org/~eagle/software/wallet/>. +.PP +\&\fBwallet\fR uses the remctl protocol. For more information about remctl, +see <http://www.eyrie.org/~eagle/software/remctl/>. +.SH "AUTHOR" +.IX Header "AUTHOR" +Russ Allbery <rra@stanford.edu> diff --git a/client/wallet.c b/client/wallet.c index 5ee24f5..e6d8eb9 100644 --- a/client/wallet.c +++ b/client/wallet.c @@ -1,23 +1,25 @@ -/* $Id$ - * +/* * The client program for the wallet system. * * Written by Russ Allbery <rra@stanford.edu> - * Copyright 2006, 2007, 2008 + * Copyright 2006, 2007, 2008, 2010 * Board of Trustees, Leland Stanford Jr. University * * See LICENSE for licensing terms. */ #include <config.h> +#include <portable/krb5.h> #include <portable/system.h> +#include <portable/uio.h> #include <errno.h> -#include <krb5.h> #include <remctl.h> #include <client/internal.h> -#include <util/util.h> +#include <util/messages-krb5.h> +#include <util/messages.h> +#include <util/xmalloc.h> /* * Basic wallet behavior options set either on the command line or via @@ -134,7 +136,8 @@ main(int argc, char *argv[]) krb5_error_code retval; struct options options; int option, i, status; - const char **command; + struct iovec *command; + size_t count, length; const char *file = NULL; const char *srvtab = NULL; struct remctl *r; @@ -240,26 +243,31 @@ main(int argc, char *argv[]) status = get_file(r, options.type, argv[1], argv[2], file); } } else { + count = argc + 1; if (strcmp(argv[0], "store") == 0) { if (argc > 4) die("too many arguments"); - else if (argc == 4) - command = xmalloc(sizeof(char *) * (argc + 2)); - else - command = xmalloc(sizeof(char *) * (argc + 3)); - } else - command = xmalloc(sizeof(char *) * (argc + 2)); - command[0] = options.type; - for (i = 0; i < argc; i++) - command[i + 1] = argv[i]; + else if (argc < 4) + count++; + } + command = xmalloc(sizeof(struct iovec) * count); + command[0].iov_base = (char *) options.type; + command[0].iov_len = strlen(options.type); + for (i = 0; i < argc; i++) { + command[i + 1].iov_base = argv[i]; + command[i + 1].iov_len = strlen(argv[i]); + } if (strcmp(argv[0], "store") == 0 && argc < 4) { - command[argc + 1] = read_file(file == NULL ? "-" : file); - command[argc + 2] = NULL; - } else - command[argc + 1] = NULL; - status = run_command(r, command, NULL, NULL); + if (file == NULL) + file = "-"; + command[argc + 1].iov_base = read_file(file, &length); + command[argc + 1].iov_len = length; + } + status = run_commandv(r, command, count, NULL, NULL); } remctl_close(r); krb5_free_context(ctx); + if (options.user != NULL) + kdestroy(); exit(status); } diff --git a/client/wallet.pod b/client/wallet.pod index 657929b..db93700 100644 --- a/client/wallet.pod +++ b/client/wallet.pod @@ -2,6 +2,11 @@ wallet - Client for retrieving secure data from a central server +=for stopwords +-hv srvtab arg keytabs metadata keytab ACL PTS kinit klist remctl PKINIT +acl timestamp autocreate backend-specific setacl enctypes enctype ktadd +KDC appdefaults remctld Allbery uuencode getacl backend + =head1 SYNOPSIS B<wallet> [B<-hv>] [B<-c> I<command>] [B<-f> I<file>] @@ -44,14 +49,12 @@ entries, each of which is a scheme and an identifier. A scheme specifies a way of checking whether a user is authorized. An identifier is some data specific to the scheme that specifies which users are authorized. For example, for the C<krb5> scheme, the identifier is a principal name -and only that principal is authorized by that ACL entry. For the C<pts> -scheme, the identifier is a PTS group name, and all members of that PTS -group are authorized by that ACL entry. +and only that principal is authorized by that ACL entry. -To run the wallet command-line client, you must already have a Kerberos -ticket. You can obtain a Kerberos ticket with B<kinit> and see your -current Kerberos tickets with B<klist>. The wallet client uses the remctl -protocol to talk to the wallet server. +To run the wallet command-line client, you must either already have a +Kerberos ticket or use the B<-u> option. You can obtain a Kerberos ticket +with B<kinit> and see your current Kerberos tickets with B<klist>. The +wallet client uses the remctl protocol to talk to the wallet server. =head1 OPTIONS @@ -84,11 +87,6 @@ ktremove> or an equivalent later to clean up old keys. F<I<output>.new> is still used as a temporary file and any existing file with that name will be deleted. -C<store> does not yet support nul bytes in I<file> (or in any other way of -specifying the data to be stored). To store binary files in the wallet, -you will need to encode them with uuencode, base64, or some similar scheme -and then decode them after retrieval. - =item B<-k> I<principal> The service principal of the wallet server. The default is to use the @@ -114,9 +112,19 @@ C<keytab> object, and must be used in conjunction with the B<-f> flag. After the keytab is saved to the file specified by B<-f>, the DES key for that principal will be extracted and written as a Kerberos v4 srvtab to the file I<srvtab>. Any existing contents of I<srvtab> will be -destroyed. For more information on how the principal is converted to -Kerberos v4, see the description of the B<sync> attribute under -L<ATTRIBUTES>. +destroyed. + +The Kerberos v4 principal name will be generated from the Kerberos v5 +principal name using the krb5_524_conv_principal() function of the +Kerberos libraries. See its documentation for more information, but +briefly (and in the absence of special configuration), the Kerberos v4 +principal name will be the same as the Kerberos v5 principal name except +that the components are separated by C<.> instead of C</>; the second +component is truncated after the first C<.> if the first component is one +of the recognized host-based principals (generally C<host>, C<imap>, +C<pop>, or C<smtp>); and the first component is C<rcmd> if the Kerberos v5 +principal component is C<host>. The principal name must not contain more +than two components. =item B<-s> I<server> @@ -191,7 +199,7 @@ Display the history of the ACL <id>. Each change to the ACL (not including changes to the name of the ACL) will be represented by two lines. The first line will have a timestamp of the change followed by a description of the change, and the second line will give the user who made -the change and the host from which the change was mde. +the change and the host from which the change was made. =item acl remove <id> <scheme> <identifier> @@ -336,11 +344,6 @@ retrieval with C<get>. Not all object types support this. If <data> is not specified on the command line, it will be read from the file specified with B<-f> (if given) or from standard input. -Currently, the stored data must not contain nul characters and may -therefore not be binary data. Its length is also limited by the maximum -command line length of the operating system of the wallet server. These -restrictions will be lifted in the future. - If an object with type <type> and name <name> does not already exist when this command is issued (as checked with the check interface), B<wallet> will attempt to automatically create it (using autocreate). @@ -364,9 +367,9 @@ Keytab objects support the following attributes: Restricts the generated keytab to a specific set of encryption types. The values of this attribute must be enctype strings recognized by Kerberos -(strings like C<aes256-cts> or C<des-cbc-crc>). Note that the salt should -not be included; since the salt is irrelevant for keytab keys, it will -always be set to C<normal> by the wallet. +(strings like C<aes256-cts-hmac-sha1-96> or C<des-cbc-crc>). Note that +the salt should not be included; since the salt is irrelevant for keytab +keys, it will always be set to C<normal> by the wallet. If this attribute is set, the specified enctype list will be passed to ktadd when get() is called for that keytab. If it is not set, the default set in @@ -377,34 +380,6 @@ Keytabs retrieved with C<unchanging> set will contain all keys present in the KDC for that Kerberos principal and therefore may contain different enctypes than those requested by this attribute. -=item sync - -Sets the external systems to which the key of a given principal is -synchronized. The only supported value for this attribute is C<kaserver>, -which says to synchronize the key with an AFS Kerberos v4 kaserver. - -If this attribute is set on a keytab, whenever the C<get> command is run -for that keytab, the DES key will be extracted from that keytab and set in -the configured AFS kaserver. If the B<-S> option is given to the -B<wallet> client, the srvtab corresponding to the keytab will be written -to the file specified with that option. The Kerberos v4 principal name -will be the same as the Kerberos v5 principal name except that the -components are separated by C<.> instead of C</>; the second component is -truncated after the first C<.> if the first component is one of C<host>, -C<ident>, C<imap>, C<pop>, or C<smtp>; and the first component is C<rcmd> -if the Kerberos v5 principal component is C<host>. The principal name -must not contain more than two components. - -If this attribute is set, calling C<destroy> will also destroy the -principal from the AFS kaserver, with a principal mapping determined as -above. - -The realm of the srvtab defaults to the same realm as the keytab. You can -change this by setting the v4_realm configuration option in the [realms] -section of krb5.conf for the local realm. The keytab must be for a -principal in the default local realm for the B<-S> option to work -correctly. - =back =head1 CONFIGURATION |