share/man/man3gss/gss_canonicalize_name.3gss

   1 '\" te
   2 .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GSS_CANONICALIZE_NAME 3GSS "Jan 14, 2003"
   7 .SH NAME
   8 gss_canonicalize_name \- convert an internal name to a mechanism name
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [\fIflag \&.\|.\|.\fR] \fIfile\fR\&.\|.\|. \fB-lgss\fR [\fIlibrary \&.\|.\|.\fR]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_canonicalize_name\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_name_t\fR \fIinput_name\fR,\fBconst gss_OID\fR \fImech_type\fR,
  17      \fBgss_name_t *\fR\fIoutput_name\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBgss_canonicalize_name()\fR function generates a canonical mechanism name
  24 from an arbitrary internal name.  The mechanism name is the name that would be
  25 returned to a context acceptor on successful authentication of a context where
  26 the initiator used the \fIinput_name\fR in a successful call to
  27 \fBgss_acquire_cred\fR(3GSS), specifying an OID set containing \fImech_type\fR
  28 as its only member, followed by a call to \fBgss_init_sec_context\fR(3GSS),
  29 specifying \fImech_type\fR as the authentication mechanism.
  30 .SH PARAMETERS
  31 .sp
  32 .LP
  33 The parameter descriptions for \fBgss_canonicalize_name()\fR follow:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIminor_status\fR\fR
  38 .ad
  39 .RS 16n
  40 Mechanism-specific status code.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIinput_name\fR\fR
  47 .ad
  48 .RS 16n
  49 The name for which a canonical form is desired.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fImech_type\fR\fR
  56 .ad
  57 .RS 16n
  58 The authentication mechanism for which the canonical form of the name is
  59 desired.  The desired mechanism must be specified explicitly; no default is
  60 provided.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIoutput_name\fR\fR
  67 .ad
  68 .RS 16n
  69 The resultant canonical name.  Storage associated with this name must be freed
  70 by the application after use with a call to \fBgss_release_name\fR(3GSS).
  71 .RE
  72
  73 .SH ERRORS
  74 .sp
  75 .LP
  76 The \fBgss_canonicalize_name()\fR function may return the status codes:
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBGSS_S_COMPLETE\fR\fR
  81 .ad
  82 .RS 22n
  83 Successful completion.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBGSS_S_BAD_MECH\fR\fR
  90 .ad
  91 .RS 22n
  92 The identified mechanism is not supported.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBGSS_S_BAD_NAMETYPE\fR\fR
  99 .ad
 100 .RS 22n
 101 The provided internal name contains no elements that could be processed by the
 102 specified mechanism.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBGSS_S_BAD_NAME\fR\fR
 109 .ad
 110 .RS 22n
 111 The provided internal name was ill-formed.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBGSS_S_FAILURE\fR\fR
 118 .ad
 119 .RS 22n
 120 The underlying mechanism detected an error for which no specific \fBGSS\fR
 121 status code is defined.  The mechanism-specific status code reported by means
 122 of the \fIminor_status\fR parameter details the error condition.
 123 .RE
 124
 125 .SH ATTRIBUTES
 126 .sp
 127 .LP
 128 See \fBattributes\fR(5) for descriptions of the following attributes:
 129 .sp
 130
 131 .sp
 132 .TS
 133 box;
 134 c | c
 135 l | l .
 136 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 137 _
 138 MT-Level        Safe
 139 .TE
 140
 141 .SH SEE ALSO
 142 .sp
 143 .LP
 144 \fBgss_acquire_cred\fR(3GSS), \fBgss_init_sec_context\fR(3GSS),
 145 \fBgss_release_name\fR(3GSS), \fBattributes\fR(5)
 146 .sp
 147 .LP
 148 \fISolaris Security for Developers Guide\fR