1 '\" te

     2 .\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

     3 .TH gss_inquire_context 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions"

     4 .SH NAME

     5 gss_inquire_context \- obtain information about a security context

     6 .SH SYNOPSIS

     7 .LP

     8 .nf

     9 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 

    10 #include <gssapi/gssapi.h>

    11 

    12 \fBOM_uint32\fR \fBgss_inquire_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,

    13      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR,\fBgss_name_t *\fR\fIsrc_name\fR,

    14      \fBgss_name_t *\fR\fItarg_name\fR, \fBOM_uint32 *\fR\fIlifetime_rec\fR,

    15      \fBgss_OID *\fR\fImech_type\fR, \fBOM_uint32 *\fR\fIctx_flags\fR,

    16      \fBint *\fR\fIlocally_initiated\fR, \fBint *\fR\fIopen\fR);

    17 .fi

    18 

    19 .SH DESCRIPTION

    20 .sp

    21 .LP

    22 The \fBgss_inquire_context()\fR function obtains information about a security context. The caller must already have obtained a handle that refers to the context, although the context need not be fully established.

    23 .SH PARAMETERS

    24 .sp

    25 .LP

    26 The parameter descriptions for \fBgss_inquire_context()\fR are as follows:

    27 .sp

    28 .ne 2

    29 .mk

    30 .na

    31 \fB\fIminor_status\fR\fR

    32 .ad

    33 .RS 21n

    34 .rt  

    35 A mechanism-specific status code.

    36 .RE

    37 

    38 .sp

    39 .ne 2

    40 .mk

    41 .na

    42 \fB\fIcontext_handle\fR\fR

    43 .ad

    44 .RS 21n

    45 .rt  

    46 A handle that refers to the security context.

    47 .RE

    48 

    49 .sp

    50 .ne 2

    51 .mk

    52 .na

    53 \fB\fIsrc_name\fR\fR

    54 .ad

    55 .RS 21n

    56 .rt  

    57 The name of the context initiator. If the context was established using anonymous authentication, and if the application invoking \fBgss_inquire_context()\fR is the context acceptor, an anonymous name is returned.  Storage associated with this name must be freed by the application after use with a call to \fBgss_release_name()\fR. Specify \fBNULL\fR if the parameter is not required.

    58 .RE

    59 

    60 .sp

    61 .ne 2

    62 .mk

    63 .na

    64 \fB\fItarg_name\fR\fR

    65 .ad

    66 .RS 21n

    67 .rt  

    68 The name of the context acceptor. Storage associated with this name must be freed by the application after use with a call to \fBgss_release_name()\fR. If the context acceptor did not authenticate itself, and if the initiator did not specify a target name in its call to \fBgss_init_sec_context()\fR, the value \fBGSS_C_NO_NAME\fR is returned. Specify \fBNULL\fR if the parameter is not required.

    69 .RE

    70 

    71 .sp

    72 .ne 2

    73 .mk

    74 .na

    75 \fB\fIlifetime_rec\fR\fR

    76 .ad

    77 .RS 21n

    78 .rt  

    79 The number of seconds for which the context will remain valid. If the context has expired, this parameter will be set to zero. Specify \fBNULL\fR if the parameter is not required.

    80 .RE

    81 

    82 .sp

    83 .ne 2

    84 .mk

    85 .na

    86 \fB\fImech_type\fR\fR

    87 .ad

    88 .RS 21n

    89 .rt  

    90 The security mechanism providing the context. The returned \fBOID\fR is a pointer to static storage that should be treated as read-only by the application; in particular, the application should not attempt to free it. Specify \fBNULL\fR if the parameter is not required.

    91 .RE

    92 

    93 .sp

    94 .ne 2

    95 .mk

    96 .na

    97 \fB\fIctx_flags\fR\fR

    98 .ad

    99 .RS 21n

   100 .rt  

   101 Contains various independent flags, each of which indicates that the context supports (or is expected to support, if \fBctx_open\fR is false) a specific service option. If not needed, specify \fBNULL\fR.  Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically \fBAND\fRed with the \fBret_flags\fR value to test whether a given option is supported by the context.  The flags are:

   102 .sp

   103 .ne 2

   104 .mk

   105 .na

   106 \fB\fBGSS_C_DELEG_FLAG\fR\fR

   107 .ad

   108 .RS 25n

   109 .rt  

   110 If true, credentials were delegated from the initiator to the acceptor. If false, no credentials were delegated.

   111 .RE

   112 

   113 .sp

   114 .ne 2

   115 .mk

   116 .na

   117 \fB\fBGSS_C_MUTUAL_FLAG\fR\fR

   118 .ad

   119 .RS 25n

   120 .rt  

   121 If true, the acceptor was authenticated to the initiator. If false, the acceptor did not authenticate itself.

   122 .RE

   123 

   124 .sp

   125 .ne 2

   126 .mk

   127 .na

   128 \fB\fBGSS_C_REPLAY_FLAG\fR\fR

   129 .ad

   130 .RS 25n

   131 .rt  

   132 If true, the replay of protected messages will be detected. If false, replayed messages will not be detected.

   133 .RE

   134 

   135 .sp

   136 .ne 2

   137 .mk

   138 .na

   139 \fB\fBGSS_C_SEQUENCE_FLAG\fR\fR

   140 .ad

   141 .RS 25n

   142 .rt  

   143 If true, out-of-sequence protected messages will be detected. If false, out-of-sequence messages will not be detected.

   144 .RE

   145 

   146 .sp

   147 .ne 2

   148 .mk

   149 .na

   150 \fB\fBGSS_C_CONF_FLAG\fR\fR

   151 .ad

   152 .RS 25n

   153 .rt  

   154 If true, confidential service may be invoked by calling the \fBgss_wrap\fR(3GSS) routine. If false, no confidential service is available through \fBgss_wrap()\fR. \fBgss_wrap()\fR provides message encapsulation, data-origin authentication, and integrity services only.

   155 .RE

   156 

   157 .sp

   158 .ne 2

   159 .mk

   160 .na

   161 \fB\fBGSS_C_INTEG_FLAG\fR\fR

   162 .ad

   163 .RS 25n

   164 .rt  

   165 If true, integrity service can be invoked by calling either the \fBgss_get_mic()\fR or the \fBgss_wrap()\fR routine. If false, per-message integrity service is unavailable.

   166 .RE

   167 

   168 .sp

   169 .ne 2

   170 .mk

   171 .na

   172 \fB\fBGSS_C_ANON_FLAG\fR\fR

   173 .ad

   174 .RS 25n

   175 .rt  

   176 If true, the initiator's identity is not revealed to the acceptor. The \fIsrc_name\fR parameter, if requested, contains an anonymous internal name. If false, the initiator has been authenticated normally.

   177 .RE

   178 

   179 .sp

   180 .ne 2

   181 .mk

   182 .na

   183 \fB\fBGSS_C_PROT_READY_FLAG\fR\fR

   184 .ad

   185 .RS 25n

   186 .rt  

   187 If true, the protection services, as specified by the states of the \fBGSS_C_CONF_FLAG\fR and \fBGSS_C_INTEG_FLAG\fR, are available for use. If false, they are available only if the context is fully established, that is, if the \fIopen\fR parameter is non-zero.

   188 .RE

   189 

   190 .sp

   191 .ne 2

   192 .mk

   193 .na

   194 \fB\fBGSS_C_TRANS_FLAG\fR\fR

   195 .ad

   196 .RS 25n

   197 .rt  

   198 If true, resultant security context can be transferred to other processes through a call to \fBgss_export_sec_context()\fR. If false, the security context is not transferable.

   199 .RE

   200 

   201 .RE

   202 

   203 .sp

   204 .ne 2

   205 .mk

   206 .na

   207 \fB\fIlocally_initiated\fR\fR

   208 .ad

   209 .RS 21n

   210 .rt  

   211 Non-zero if the invoking application is the context initiator. Specify \fBNULL\fR if the parameter is not required.

   212 .RE

   213 

   214 .sp

   215 .ne 2

   216 .mk

   217 .na

   218 \fB\fIopen\fR\fR

   219 .ad

   220 .RS 21n

   221 .rt  

   222 Non-zero if the context is fully established; zero if a context-establishment token is expected from the peer application. Specify \fBNULL\fR if the parameter is not required.

   223 .RE

   224 

   225 .SH ERRORS

   226 .sp

   227 .LP

   228 \fBgss_inquire_context()\fR returns one of the following status codes:

   229 .sp

   230 .ne 2

   231 .mk

   232 .na

   233 \fB\fBGSS_S_COMPLETE\fR\fR

   234 .ad

   235 .RS 20n

   236 .rt  

   237 Successful completion.

   238 .RE

   239 

   240 .sp

   241 .ne 2

   242 .mk

   243 .na

   244 \fB\fBGSS_S_NO_CONTEXT\fR\fR

   245 .ad

   246 .RS 20n

   247 .rt  

   248 The referenced context could not be accessed.

   249 .RE

   250 

   251 .sp

   252 .ne 2

   253 .mk

   254 .na

   255 \fB\fBGSS_S_FAILURE\fR\fR

   256 .ad

   257 .RS 20n

   258 .rt  

   259 The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined.  The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.

   260 .RE

   261 

   262 .SH ATTRIBUTES

   263 .sp

   264 .LP

   265 See \fBattributes\fR(5)  for descriptions of the following attributes:

   266 .sp

   267 

   268 .sp

   269 .TS

   270 tab() box;

   271 cw(2.75i) |cw(2.75i) 

   272 lw(2.75i) |lw(2.75i) 

   273 .

   274 ATTRIBUTE TYPEATTRIBUTE VALUE

   275 _

   276 MT-LevelSafe

   277 .TE

   278 

   279 .SH SEE ALSO

   280 .sp

   281 .LP

   282 \fBgss_accept_sec_context\fR(3GSS), \fBgss_context_time\fR(3GSS), \fBgss_delete_sec_context\fR(3GSS), \fBgss_export_sec_context\fR(3GSS), \fBgss_import_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS), \fBgss_process_context_token\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBgss_wrap_size_limit\fR(3GSS), \fBattributes\fR(5)

   283 .sp

   284 .LP

   285 \fI\fR