manual page
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@2967 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
Johan Danielsson
166
lib/krb5/krb5_425_conv_principal.3
Normal file
166
lib/krb5/krb5_425_conv_principal.3
Normal file
@@ -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
|
||||||
78
lib/krb5/krb5_build_principal.3
Normal file
78
lib/krb5/krb5_build_principal.3
Normal file
@@ -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
|
||||||
30
lib/krb5/krb5_free_principal.3
Normal file
30
lib/krb5/krb5_free_principal.3
Normal file
@@ -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
|
||||||
39
lib/krb5/krb5_parse_name.3
Normal file
39
lib/krb5/krb5_parse_name.3
Normal file
@@ -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
|
||||||
58
lib/krb5/krb5_sname_to_principal.3
Normal file
58
lib/krb5/krb5_sname_to_principal.3
Normal file
@@ -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
|
||||||
34
lib/krb5/krb5_unparse_name.3
Normal file
34
lib/krb5/krb5_unparse_name.3
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user