From c50c15a4a54bd758eee02a5949064c23eb281fb7 Mon Sep 17 00:00:00 2001 From: Johan Danielsson Date: Thu, 14 Aug 1997 00:03:19 +0000 Subject: [PATCH] manual page git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@2967 ec53bebd-3082-4978-b11e-865c3cabbd6b --- lib/krb5/krb5_425_conv_principal.3 | 166 +++++++++++++++++++++++++++++ lib/krb5/krb5_build_principal.3 | 78 ++++++++++++++ lib/krb5/krb5_free_principal.3 | 30 ++++++ lib/krb5/krb5_parse_name.3 | 39 +++++++ lib/krb5/krb5_sname_to_principal.3 | 58 ++++++++++ lib/krb5/krb5_unparse_name.3 | 34 ++++++ 6 files changed, 405 insertions(+) create mode 100644 lib/krb5/krb5_425_conv_principal.3 create mode 100644 lib/krb5/krb5_build_principal.3 create mode 100644 lib/krb5/krb5_free_principal.3 create mode 100644 lib/krb5/krb5_parse_name.3 create mode 100644 lib/krb5/krb5_sname_to_principal.3 create mode 100644 lib/krb5/krb5_unparse_name.3 diff --git a/lib/krb5/krb5_425_conv_principal.3 b/lib/krb5/krb5_425_conv_principal.3 new file mode 100644 index 000000000..7e39ca433 --- /dev/null +++ b/lib/krb5/krb5_425_conv_principal.3 @@ -0,0 +1,166 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_425_CONV_PRINCIPAL 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_425_conv_principal , +.Nm krb5_524_conv_principal +.Nd Converts to and from version 4 principals + +.Sh SYNOPSIS +.Fd #include + +.Ft krb5_error_code +.Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *princ" + +.Ft krb5_error_code +.Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm" + +.Sh DESCRIPTION + +Converting between version 4 and version 5 principals can at best be +described as a mess. +.Pp +A version 4 principal consists of a name, an instance, and a realm. A +version 5 principal consists of one or more components, and a +realm. In some cases also the first component/name will differ between +version 4 and version 5. Furthermore the second component of a host +principal will be the fully qualified domain name of the host in +question, while the instance of a version 4 principal will only +contain the first component. Because of these problems the conversion +between principals will have to be site customized. +.Pp +.Fn krb5_425_conv_principal +will try to convert a version 4 principal, given by +.Fa name , +.Fa instance , +and +.Fa realm , +to a version 5 principal. To do this it will look up the name in +.Pa krb5.conf . +It first looks in the +.Li v4_name_convert/host +binding, which should contain a list of version 4 names whose instance +should be treated as a hostname. This list can be specified for each +realm (in the +.Li realms +section), or in the +.Li libdefaults +section. If the name is found the first component of the principal +will be value of this binding. The instance is then first looked up in +.Li v4_instance_convert +for the specified realm. If found the resulting value will be used as +instance (this can be used for special cases). If not found you can +optionally have the instance looked up (with +.Fn gethostbyname ) . +This is a time consuming, error prone, and unsafe operation, and it is +not turned on by default. You can turn on this feature by setting +.Li v4_instance_resolve +to true in the +.Li libdefaults +section. As a final fallback you can, for each realm, include a +.Li default_realm +that will be appended to the instance without further checks. +.Pp +On the other hand, if the name is not found in a +.Li host +section, it is looked up in a +.Li v4_name_convert/plain +binding. If found here the name will be converted, but the instance +will be untouched. +.Pp +.Fn krb5_524_conv_principal +basically does the opposite of +.Fn krb5_425_conv_principal , +it just doesn't have to look up any names, but will instead truncate +instances found to belong to a host principal. The +.Fa name , +.Fa instance , +and +.Fa realm +should be at least 40 characters long. + +.Sh EXAMPLES + +Since this is confusing an example is in place. +.Pp +Assume that we have the +.Dq foo.com , +and +.Dq bar.com +domains that have shared a single version 4 realm, FOO.COM. The version 4 +.Pa krb.realms +file looked like: +.Bd -literal -offset indent +foo.com FOO.COM +\&.foo.com FOO.COM +\&.bar.com FOO.COM +.Ed +.Pp +A +.Pa krb5.conf +file that covers this case might look like: +.Bd -literal -offset indent +[libdefaults] + v4_name_convert = { + host = { + rcmd = host + ftp = ftp + pop = pop + } + } + v4_instance_resolve = yes +[realms] + FOO.COM = { + kdc = kerberos.foo.com + v4_instance_convert = { + foo = foo.com + } + default_domain = foo.com + } +.Ed +.Pp +With this setup and the following host table: +.Bd -literal -offset indent +foo.com +a-host.foo.com +b-host.bar.com +.Ed +the following conversions will be made: +.Bd -literal -offset indent +rcmd.a-host \(-> host/a-host.foo.com +ftp.b-host \(-> ftp/b-host.bar.com +pop.foo \(-> pop/foo.com +ftp.other \(-> ftp/other.foo.com +other.a-host \(-> other/a-host +.Ed +.Pp +The first three are what you expect. If you remove the +.Dq default_domain , +the fourth entry will result in an error (since the host +.Dq other +can't be found). Even if +.Dq a-host +is a valid host name, the last entry will not be converted, since the +.Dq other +name is not known to represent a host-type principal. +If you turn off +.Dq v4_instance_resolve +the second example will result in +.Dq ftp/b-host.foo.com +(because of the default domain). And all of this is of course only +valid if you have working name resolving. + +.Sh BUGS +You have to set up your +.Pa krb5.conf +correctly to have any of this work. + +.Sh SEE ALSO +.Xr krb5_build_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_sname_to_principal 3 , +.Xr krb5_unparse_name 3 , +.Xr krb5.conf 5 diff --git a/lib/krb5/krb5_build_principal.3 b/lib/krb5/krb5_build_principal.3 new file mode 100644 index 000000000..9848017bb --- /dev/null +++ b/lib/krb5/krb5_build_principal.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_BUILD_PRINCIPAL 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_build_principal , +.Nm krb5_build_principal_ext , +.Nm krb5_build_principal_va , +.Nm krb5_build_principal_va_ext , +.Nm krb5_make_principal +.Nd Principal creation functions + +.Sh SYNOPSIS +.Fd #include + +.Ft krb5_error_code +.Fn krb5_build_principal "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "..." + +.Ft krb5_error_code +.Fn krb5_build_principal_ext "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "..." + +.Ft krb5_error_code +.Fn krb5_build_principal_va "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "va_list ap" + +.Ft krb5_error_code +.Fn krb5_build_principal_va_ext "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "va_list ap" + +.Ft krb5_error_code +.Fn krb5_make_principal "krb5_context context" "krb5_principal *principal" "krb5_const_realm realm" "..." + + +.Sh DESCRIPTION + +These functions create a Kerberos 5 principal from a realm and a list +of components. +All of these functions return an allocated principal in the +.Fa principal +parameter, this should be freed with +.Fn krb5_free_principal +after use. +.Pp +The +.Dq build +functions take a +.Fa realm +and the length of the realm. The +.Fn krb5_build_principal +and +.Fn krb5_build_principal_va +also takes a list of components (zero-terminated strings), terminated +with +.Dv NULL . +The +.Fn krb5_build_principal_ext +and +.Fn krb5_build_principal_va_ext +takes a list of length-value pairs, the list is terminated with a zero +length. +.Pp +The +.Fn krb5_make_principal +is a wrapper around +.Fn krb5_build_principal . +If the realm is +.Dv NULL , +the default realm will be used. + +.Sh BUGS +You can not have a NUL in a component. Until someone can give a good +example of where it would be a good idea to have NUL's in a component, +this will not be fixed. +.Sh SEE ALSO +.Xr krb5_425_conv_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_sname_to_principal 3 , +.Xr krb5_unparse_name 3 diff --git a/lib/krb5/krb5_free_principal.3 b/lib/krb5/krb5_free_principal.3 new file mode 100644 index 000000000..53fcf16c8 --- /dev/null +++ b/lib/krb5/krb5_free_principal.3 @@ -0,0 +1,30 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_FREE_PRINCIPAL 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_free_principal +.Nd Principal free function + +.Sh SYNOPSIS +.Fd #include + +.Ft void +.Fn krb5_free_principal "krb5_context context" "krb5_principal principal" + +.Sh DESCRIPTION + +The +.Fn krb5_free_principal +will free a principal that has been created with +.Fn krb5_build_principal , +.Fn krb5_parse_name , +or with some other function. + +.Sh SEE ALSO +.Xr krb5_425_conv_principal 3 , +.Xr krb5_build_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_sname_to_principal 3 , +.Xr krb5_unparse_name 3 diff --git a/lib/krb5/krb5_parse_name.3 b/lib/krb5/krb5_parse_name.3 new file mode 100644 index 000000000..a58b1268d --- /dev/null +++ b/lib/krb5/krb5_parse_name.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_PARSE_NAME 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_parse_name +.Nd String to principal conversion + +.Sh SYNOPSIS +.Fd #include + +.Ft krb5_error_code +.Fn krb5_parse_name "krb5_context context" "const char *name" "krb5_principal *principal" + +.Sh DESCRIPTION + +.Fn krb5_parse_name +converts a string representation of a princpal name to +.Nm krb5_principal . +The +.Fa principal +will point to allocated data that should be freed with +.Fn krb5_free_principal . +.Pp +The string should consist of one or more name components separated with slashes +.Pq Dq / , +optionally followed with an +.Dq @ +and a realm name. A slash or @ may be contained in a name component by +quoting it with a back-slash +.Pq Dq \ . +A realm should not contain slashes or colons. +.Sh SEE ALSO +.Xr krb5_425_conv_principal 3 , +.Xr krb5_build_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_sname_to_principal 3 , +.Xr krb5_unparse_name 3 diff --git a/lib/krb5/krb5_sname_to_principal.3 b/lib/krb5/krb5_sname_to_principal.3 new file mode 100644 index 000000000..f4d264ce1 --- /dev/null +++ b/lib/krb5/krb5_sname_to_principal.3 @@ -0,0 +1,58 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_PRINCIPAL 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_sname_to_principal , +.Nm krb5_sock_to_principal +.Nd Create a service principal + +.Sh SYNOPSIS +.Fd #include + +.Ft krb5_error_code +.Fn krb5_sname_to_principal "krb5_context context" "const char *hostname" "const char *sname" "int32_t type" "krb5_principal *principal" + +.Ft krb5_error_code +.Fn krb5_sock_to_principal "krb5_context context" "int socket" "const char *sname" "int32_t type" "krb5_principal *principal" + +.Sh DESCRIPTION + +These functions create a +.Dq service +principal that can, for instance, be used to lookup a key in a keytab. For both these function the +.Fa sname +parameter will be used for the first component of the created principal. If +.Fa sname +is +.Dv NULL , +.Dq host +will be used instead. +.Fn krb5_sname_to_principal +will use the passed +.Fa hostname +for the second component. If type +.Dv KRB5_NT_SRV_HST +this name will be looked up with +.Fn gethostbyname . +If +.Fa hostname is +.Dv NULL , +the local hostname will be used. +.Pp +.Fn krb5_sock_to_principal +will use the +.Dq sockname +of the passed +.Fa socket , +which should be a bound +.Dv AF_INET +socket. + +.Sh SEE ALSO +.Xr krb5_425_conv_principal 3 , +.Xr krb5_build_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_unparse_name 3 diff --git a/lib/krb5/krb5_unparse_name.3 b/lib/krb5/krb5_unparse_name.3 new file mode 100644 index 000000000..f86cd3b5a --- /dev/null +++ b/lib/krb5/krb5_unparse_name.3 @@ -0,0 +1,34 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd August 8, 1997 +.Dt KRB5_UNPARSE_NAME 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_unparse_name +.\" .Nm krb5_unparse_name_ext +.Nd Principal to string conversion + +.Sh SYNOPSIS +.Fd #include + +.Ft krb5_error_code +.Fn krb5_unparse_name "krb5_context context" "krb5_principal principal" "char **name" + +.\" .Ft krb5_error_code +.\" .Fn krb5_unparse_name_ext "krb5_context context" "krb5_const_principal principal" "char **name" "size_t *size" + +.Sh DESCRIPTION + +This function takes a +.Fa principal , +and will convert in to a printable representation with the same syntax as decribed in +.Xr krb5_parse_name 3 . +.Fa *name +will point to allocated data and should be freed by the caller. + +.Sh SEE ALSO +.Xr krb5_425_conv_principal 3 , +.Xr krb5_build_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_sname_to_principal 3