xref: /freebsd/lib/libgssapi/gss_inquire_cred_by_mech.3 (revision aa12cea2ccc6e686d6d31cf67d6bc69cbc1ba744)
1c0b9f4feSDoug Rabson.\" -*- nroff -*-
2c0b9f4feSDoug Rabson.\"
3c0b9f4feSDoug Rabson.\" Copyright (c) 2005 Doug Rabson
4c0b9f4feSDoug Rabson.\" All rights reserved.
5c0b9f4feSDoug Rabson.\"
6c0b9f4feSDoug Rabson.\" Redistribution and use in source and binary forms, with or without
7c0b9f4feSDoug Rabson.\" modification, are permitted provided that the following conditions
8c0b9f4feSDoug Rabson.\" are met:
9c0b9f4feSDoug Rabson.\" 1. Redistributions of source code must retain the above copyright
10c0b9f4feSDoug Rabson.\"    notice, this list of conditions and the following disclaimer.
11c0b9f4feSDoug Rabson.\" 2. Redistributions in binary form must reproduce the above copyright
12c0b9f4feSDoug Rabson.\"    notice, this list of conditions and the following disclaimer in the
13c0b9f4feSDoug Rabson.\"    documentation and/or other materials provided with the distribution.
14c0b9f4feSDoug Rabson.\"
15c0b9f4feSDoug Rabson.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16c0b9f4feSDoug Rabson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17c0b9f4feSDoug Rabson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18c0b9f4feSDoug Rabson.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19c0b9f4feSDoug Rabson.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20c0b9f4feSDoug Rabson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21c0b9f4feSDoug Rabson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22c0b9f4feSDoug Rabson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23c0b9f4feSDoug Rabson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24c0b9f4feSDoug Rabson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25c0b9f4feSDoug Rabson.\" SUCH DAMAGE.
26c0b9f4feSDoug Rabson.\"
27c0b9f4feSDoug Rabson.\"	$FreeBSD$
28c0b9f4feSDoug Rabson.\"
29c0b9f4feSDoug Rabson.\" The following commands are required for all man pages.
30d76ba3efSGavin Atkinson.Dd January 26, 2010
31c0b9f4feSDoug Rabson.Dt GSS_INQUIRE_CRED_BY_MECH 3 PRM
32*aa12cea2SUlrich Spörlein.Os
33c0b9f4feSDoug Rabson.Sh NAME
34c0b9f4feSDoug Rabson.Nm gss_inquire_cred_by_mech
35c0b9f4feSDoug Rabson.Nd Obtain per-mechanism information about a credential
36c0b9f4feSDoug Rabson.\" This next command is for sections 2 and 3 only.
37c0b9f4feSDoug Rabson.\" .Sh LIBRARY
38c0b9f4feSDoug Rabson.Sh SYNOPSIS
39c0b9f4feSDoug Rabson.In "gssapi/gssapi.h"
40c0b9f4feSDoug Rabson.Ft OM_uint32
41c0b9f4feSDoug Rabson.Fo gss_inquire_cred_by_mech
42c0b9f4feSDoug Rabson.Fa "OM_uint32 *minor_status"
43c0b9f4feSDoug Rabson.Fa "const gss_cred_id_t cred_handle"
44c0b9f4feSDoug Rabson.Fa "const gss_OID mech_type"
45c0b9f4feSDoug Rabson.Fa "gss_name_t *name"
46c0b9f4feSDoug Rabson.Fa "OM_uint32 *initiator_lifetime"
47c0b9f4feSDoug Rabson.Fa "OM_uint32 *acceptor_lifetime"
48c0b9f4feSDoug Rabson.Fa "gss_cred_usage_t *cred_usage"
49c0b9f4feSDoug Rabson.Fc
50c0b9f4feSDoug Rabson.Sh DESCRIPTION
51c0b9f4feSDoug RabsonObtains per-mechanism information about a credential.
52c0b9f4feSDoug Rabson.Sh PARAMETERS
53c0b9f4feSDoug Rabson.Bl -tag
54c0b9f4feSDoug Rabson.It minor_status
55c0b9f4feSDoug RabsonMechanism specific status code.
56c0b9f4feSDoug Rabson.It cred_handle
57c0b9f4feSDoug RabsonA handle that refers to the target credential.
58c0b9f4feSDoug RabsonSpecify
59c0b9f4feSDoug Rabson.Dv GSS_C_NO_CREDENTIAL
60c0b9f4feSDoug Rabsonto inquire about the default initiator principal.
61c0b9f4feSDoug Rabson.It mech_type
62c0b9f4feSDoug RabsonThe mechanism for which information should be returned.
63c0b9f4feSDoug Rabson.It name
64c0b9f4feSDoug RabsonThe name whose identity the credential asserts.
65c0b9f4feSDoug RabsonStorage associated with this name must be freed by the application
66c0b9f4feSDoug Rabsonafter use with a call to
67c0b9f4feSDoug Rabson.Fn gss_release_name .
68c0b9f4feSDoug RabsonSpecify
69c0b9f4feSDoug Rabson.Dv NULL
70c0b9f4feSDoug Rabsonif not required.
71c0b9f4feSDoug Rabson.It initiator_lifetime
72c0b9f4feSDoug RabsonThe number of seconds for which the credential will remain capable of
73c0b9f4feSDoug Rabsoninitiating security contexts under the specified mechanism.
74c0b9f4feSDoug RabsonIf the credential can no longer be used to initiate contexts,
75c0b9f4feSDoug Rabsonor if the credential usage for this mechanism is
76c0b9f4feSDoug Rabson.Dv GSS_C_ACCEPT ,
77c0b9f4feSDoug Rabsonthis parameter will be set to zero.
78c0b9f4feSDoug RabsonIf the implementation does not support expiration of initiator
79c0b9f4feSDoug Rabsoncredentials,
80c0b9f4feSDoug Rabsonthe value
81c0b9f4feSDoug Rabson.Dv GSS_C_INDEFINITE
82c0b9f4feSDoug Rabsonwill be returned.
83c0b9f4feSDoug RabsonSpecify
84c0b9f4feSDoug Rabson.Dv NULL
85c0b9f4feSDoug Rabsonif not required.
86c0b9f4feSDoug Rabson.It acceptor_lifetime
87c0b9f4feSDoug RabsonThe number of seconds for which the credential will remain capable of
88c0b9f4feSDoug Rabsonaccepting security contexts under the specified mechanism.
89c0b9f4feSDoug RabsonIf the credential can no longer be used to accept contexts,
90c0b9f4feSDoug Rabsonor if the credential usage for this mechanism is
91c0b9f4feSDoug Rabson.Dv GSS_C_INITIATE ,
92c0b9f4feSDoug Rabsonthis parameter will be set to zero.
93c0b9f4feSDoug RabsonIf the implementation does not support expiration of acceptor
94c0b9f4feSDoug Rabsoncredentials,
95c0b9f4feSDoug Rabsonthe value
96c0b9f4feSDoug Rabson.Dv GSS_C_INDEFINITE
97c0b9f4feSDoug Rabsonwill be returned.
98c0b9f4feSDoug RabsonSpecify
99c0b9f4feSDoug Rabson.Dv NULL
100c0b9f4feSDoug Rabsonif not required.
101c0b9f4feSDoug Rabson.It cred_usage
102c0b9f4feSDoug RabsonHow the credential may be used with the specified mechanism.
103c0b9f4feSDoug RabsonOne of the following:
104c0b9f4feSDoug Rabson.Bl -item -offset indent -compact
105c0b9f4feSDoug Rabson.It
106c0b9f4feSDoug Rabson.Dv GSS_C_INITIATE
107c0b9f4feSDoug Rabson.It
108c0b9f4feSDoug Rabson.Dv GSS_C_ACCEPT
109c0b9f4feSDoug Rabson.It
110c0b9f4feSDoug Rabson.Dv GSS_C_BOTH
111c0b9f4feSDoug Rabson.El
112c0b9f4feSDoug RabsonSpecify
113c0b9f4feSDoug Rabson.Dv NULL
114c0b9f4feSDoug Rabsonif not required.
115c0b9f4feSDoug Rabson.El
116c0b9f4feSDoug Rabson.Sh RETURN VALUES
117c0b9f4feSDoug Rabson.Bl -tag
118c0b9f4feSDoug Rabson.It GSS_S_COMPLETE
119c0b9f4feSDoug RabsonSuccessful completion
120c0b9f4feSDoug Rabson.It GSS_S_NO_CRED
121c0b9f4feSDoug RabsonThe referenced credentials could not be accessed
122c0b9f4feSDoug Rabson.It GSS_S_DEFECTIVE_CREDENTIAL
123c0b9f4feSDoug RabsonThe referenced credentials were invalid
124c0b9f4feSDoug Rabson.It GSS_S_CREDENTIALS_EXPIRED
125c0b9f4feSDoug RabsonThe referenced credentials have expired.
126c0b9f4feSDoug RabsonIf the lifetime parameter was not passed as
127c0b9f4feSDoug Rabson.Dv NULL ,
128c0b9f4feSDoug Rabsonit will be set to 0.
129c0b9f4feSDoug Rabson.El
130c0b9f4feSDoug Rabson.Sh SEE ALSO
131c0b9f4feSDoug Rabson.Xr gss_release_name 3
132c0b9f4feSDoug Rabson.Sh STANDARDS
133c0b9f4feSDoug Rabson.Bl -tag
134c0b9f4feSDoug Rabson.It RFC 2743
135c0b9f4feSDoug RabsonGeneric Security Service Application Program Interface Version 2, Update 1
136c0b9f4feSDoug Rabson.It RFC 2744
137c0b9f4feSDoug RabsonGeneric Security Service API Version 2 : C-bindings
138c0b9f4feSDoug Rabson.El
139c0b9f4feSDoug Rabson.Sh HISTORY
140c0b9f4feSDoug RabsonThe
141c0b9f4feSDoug Rabson.Nm
142d76ba3efSGavin Atkinsonfunction first appeared in
143c0b9f4feSDoug Rabson.Fx 7.0 .
144c0b9f4feSDoug Rabson.Sh AUTHORS
145c0b9f4feSDoug RabsonJohn Wray, Iris Associates
14660b9f20aSDoug Rabson.Sh COPYRIGHT
14760b9f20aSDoug RabsonCopyright (C) The Internet Society (2000).  All Rights Reserved.
14860b9f20aSDoug Rabson.Pp
14960b9f20aSDoug RabsonThis document and translations of it may be copied and furnished to
15060b9f20aSDoug Rabsonothers, and derivative works that comment on or otherwise explain it
15160b9f20aSDoug Rabsonor assist in its implementation may be prepared, copied, published
15260b9f20aSDoug Rabsonand distributed, in whole or in part, without restriction of any
15360b9f20aSDoug Rabsonkind, provided that the above copyright notice and this paragraph are
15460b9f20aSDoug Rabsonincluded on all such copies and derivative works.  However, this
15560b9f20aSDoug Rabsondocument itself may not be modified in any way, such as by removing
15660b9f20aSDoug Rabsonthe copyright notice or references to the Internet Society or other
15760b9f20aSDoug RabsonInternet organizations, except as needed for the purpose of
15860b9f20aSDoug Rabsondeveloping Internet standards in which case the procedures for
15960b9f20aSDoug Rabsoncopyrights defined in the Internet Standards process must be
16060b9f20aSDoug Rabsonfollowed, or as required to translate it into languages other than
16160b9f20aSDoug RabsonEnglish.
16260b9f20aSDoug Rabson.Pp
16360b9f20aSDoug RabsonThe limited permissions granted above are perpetual and will not be
16460b9f20aSDoug Rabsonrevoked by the Internet Society or its successors or assigns.
16560b9f20aSDoug Rabson.Pp
16660b9f20aSDoug RabsonThis document and the information contained herein is provided on an
16760b9f20aSDoug Rabson"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
16860b9f20aSDoug RabsonTASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
16960b9f20aSDoug RabsonBUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
17060b9f20aSDoug RabsonHEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
17160b9f20aSDoug RabsonMERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
172