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

@@ -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 <krb5.h>
+
+.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

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 <krb5.h>
+
+.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

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 <krb5.h>
+
+.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

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 <krb5.h>
+
+.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

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 <krb5.h>
+
+.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

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 <krb5.h>
+
+.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