31 * through one of the <code>createName</code> methods that exist in the {@link
32 * GSSManager GSSManager} class. Conceptually a GSSName contains many
33 * representations of the entity or many primitive name elements, one for
34 * each supported underlying mechanism. In GSS terminology, a GSSName that
35 * contains an element from just one mechanism is called a Mechanism Name
36 * (MN)<p>
37 *
38 * Since different authentication mechanisms may employ different
39 * namespaces for identifying their principals, GSS-API's naming support is
40 * necessarily complex in multi-mechanism environments (or even in some
41 * single-mechanism environments where the underlying mechanism supports
42 * multiple namespaces). Different name formats and their definitions are
43 * identified with {@link Oid Oid's} and some standard types
44 * are defined in this interface. The format of the names can be derived
45 * based on the unique <code>Oid</code> of its name type.<p>
46 *
47 * Included below are code examples utilizing the <code>GSSName</code> interface.
48 * The code below creates a <code>GSSName</code>, converts it to an MN, performs a
49 * comparison, obtains a printable representation of the name, exports it
50 * to a byte array and then re-imports to obtain a
51 * new <code>GSSName</code>.<p>
52 * <pre>
53 * GSSManager manager = GSSManager.getInstance();
54 *
55 * // create a host based service name
56 * GSSName name = manager.createName("service@host",
57 * GSSName.NT_HOSTBASED_SERVICE);
58 *
59 * Oid krb5 = new Oid("1.2.840.113554.1.2.2");
60 *
61 * GSSName mechName = name.canonicalize(krb5);
62 *
63 * // the above two steps are equivalent to the following
64 * GSSName mechName = manager.createName("service@host",
65 * GSSName.NT_HOSTBASED_SERVICE, krb5);
66 *
67 * // perform name comparison
68 * if (name.equals(mechName))
69 * print("Names are equals.");
70 *
71 * // obtain textual representation of name and its printable
219 * (MN), suitable for direct, byte by byte comparison by authorization
220 * functions. If the name is not an MN, implementations may throw a
221 * GSSException with the NAME_NOT_MN status code. If an implementation
222 * chooses not to throw an exception, it should use some system specific
223 * default mechanism to canonicalize the name and then export
224 * it. Structurally, an exported name object consists of a header
225 * containing an OID identifying the mechanism that authenticated the
226 * name, and a trailer containing the name itself, where the syntax of
227 * the trailer is defined by the individual mechanism specification. The
228 * format of the header of the output buffer is specified in RFC 2743.<p>
229 *
230 * The exported name is useful when used in large access control lists
231 * where the overhead of creating a <code>GSSName</code> object on each
232 * name and invoking the equals method on each name from the ACL may be
233 * prohibitive.<p>
234 *
235 * Exported names may be re-imported by using the byte array factory
236 * method {@link GSSManager#createName(byte[], Oid)
237 * GSSManager.createName} and specifying the NT_EXPORT_NAME as the name
238 * type object identifier. The resulting <code>GSSName</code> name will
239 * also be a MN.<p>
240 * @return a byte[] containing the exported name. RFC 2743 defines the
241 * "Mechanism-Independent Exported Name Object Format" for these bytes.
242 *
243 * @throws GSSException containing the following
244 * major error codes:
245 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
246 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
247 * {@link GSSException#FAILURE GSSException.FAILURE}
248 */
249 public byte[] export() throws GSSException;
250
251 /**
252 * Returns a textual representation of the <code>GSSName</code> object. To retrieve
253 * the printed name format, which determines the syntax of the returned
254 * string, use the {@link #getStringNameType() getStringNameType}
255 * method.
256 *
257 * @return a String representing this name in printable form.
258 */
259 public String toString();
|
31 * through one of the <code>createName</code> methods that exist in the {@link
32 * GSSManager GSSManager} class. Conceptually a GSSName contains many
33 * representations of the entity or many primitive name elements, one for
34 * each supported underlying mechanism. In GSS terminology, a GSSName that
35 * contains an element from just one mechanism is called a Mechanism Name
36 * (MN)<p>
37 *
38 * Since different authentication mechanisms may employ different
39 * namespaces for identifying their principals, GSS-API's naming support is
40 * necessarily complex in multi-mechanism environments (or even in some
41 * single-mechanism environments where the underlying mechanism supports
42 * multiple namespaces). Different name formats and their definitions are
43 * identified with {@link Oid Oid's} and some standard types
44 * are defined in this interface. The format of the names can be derived
45 * based on the unique <code>Oid</code> of its name type.<p>
46 *
47 * Included below are code examples utilizing the <code>GSSName</code> interface.
48 * The code below creates a <code>GSSName</code>, converts it to an MN, performs a
49 * comparison, obtains a printable representation of the name, exports it
50 * to a byte array and then re-imports to obtain a
51 * new <code>GSSName</code>.
52 * <pre>
53 * GSSManager manager = GSSManager.getInstance();
54 *
55 * // create a host based service name
56 * GSSName name = manager.createName("service@host",
57 * GSSName.NT_HOSTBASED_SERVICE);
58 *
59 * Oid krb5 = new Oid("1.2.840.113554.1.2.2");
60 *
61 * GSSName mechName = name.canonicalize(krb5);
62 *
63 * // the above two steps are equivalent to the following
64 * GSSName mechName = manager.createName("service@host",
65 * GSSName.NT_HOSTBASED_SERVICE, krb5);
66 *
67 * // perform name comparison
68 * if (name.equals(mechName))
69 * print("Names are equals.");
70 *
71 * // obtain textual representation of name and its printable
219 * (MN), suitable for direct, byte by byte comparison by authorization
220 * functions. If the name is not an MN, implementations may throw a
221 * GSSException with the NAME_NOT_MN status code. If an implementation
222 * chooses not to throw an exception, it should use some system specific
223 * default mechanism to canonicalize the name and then export
224 * it. Structurally, an exported name object consists of a header
225 * containing an OID identifying the mechanism that authenticated the
226 * name, and a trailer containing the name itself, where the syntax of
227 * the trailer is defined by the individual mechanism specification. The
228 * format of the header of the output buffer is specified in RFC 2743.<p>
229 *
230 * The exported name is useful when used in large access control lists
231 * where the overhead of creating a <code>GSSName</code> object on each
232 * name and invoking the equals method on each name from the ACL may be
233 * prohibitive.<p>
234 *
235 * Exported names may be re-imported by using the byte array factory
236 * method {@link GSSManager#createName(byte[], Oid)
237 * GSSManager.createName} and specifying the NT_EXPORT_NAME as the name
238 * type object identifier. The resulting <code>GSSName</code> name will
239 * also be a MN.
240 *
241 * @return a byte[] containing the exported name. RFC 2743 defines the
242 * "Mechanism-Independent Exported Name Object Format" for these bytes.
243 *
244 * @throws GSSException containing the following
245 * major error codes:
246 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
247 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
248 * {@link GSSException#FAILURE GSSException.FAILURE}
249 */
250 public byte[] export() throws GSSException;
251
252 /**
253 * Returns a textual representation of the <code>GSSName</code> object. To retrieve
254 * the printed name format, which determines the syntax of the returned
255 * string, use the {@link #getStringNameType() getStringNameType}
256 * method.
257 *
258 * @return a String representing this name in printable form.
259 */
260 public String toString();
|