summaryrefslogtreecommitdiffstats
path: root/crypto
diff options
context:
space:
mode:
authormarkm <markm@FreeBSD.org>2000-02-24 11:19:29 +0000
committermarkm <markm@FreeBSD.org>2000-02-24 11:19:29 +0000
commit1a9f61a7f93f39ece93b59bd2ee55b06a82bacac (patch)
tree0d3f9b1dc38dc05736fdc34b54382a3d3fae3986 /crypto
parent50efcd9b31d45996ff9dc2dd8e29f209a0b4e03a (diff)
parent69414e22b995b6d161fc19bcab66823585f1d394 (diff)
downloadFreeBSD-src-1a9f61a7f93f39ece93b59bd2ee55b06a82bacac.zip
FreeBSD-src-1a9f61a7f93f39ece93b59bd2ee55b06a82bacac.tar.gz
This commit was generated by cvs2svn to compensate for changes in r57419,
which included commits to RCS files with non-trunk default branches.
Diffstat (limited to 'crypto')
-rw-r--r--crypto/heimdal/ChangeLog40
-rw-r--r--crypto/heimdal/NEWS11
-rw-r--r--crypto/heimdal/appl/telnet/ChangeLog5
-rw-r--r--crypto/heimdal/appl/telnet/telnet/commands.c4
-rw-r--r--crypto/heimdal/appl/test/common.c6
-rw-r--r--crypto/heimdal/appl/test/gss_common.c6
-rw-r--r--crypto/heimdal/appl/test/gssapi_client.c127
-rw-r--r--crypto/heimdal/appl/test/gssapi_server.c153
-rw-r--r--crypto/heimdal/appl/test/test_locl.h5
-rwxr-xr-xcrypto/heimdal/configure4
-rw-r--r--crypto/heimdal/configure.in4
-rw-r--r--crypto/heimdal/doc/ack.texi2
-rw-r--r--crypto/heimdal/doc/standardisation/rfc2743.txt5659
-rw-r--r--crypto/heimdal/doc/standardisation/rfc2744.txt5659
-rw-r--r--crypto/heimdal/kdc/config.c76
-rw-r--r--crypto/heimdal/kdc/connect.c74
-rw-r--r--crypto/heimdal/kdc/kaserver.c6
-rw-r--r--crypto/heimdal/kdc/kdc.863
-rw-r--r--crypto/heimdal/kdc/kdc_locl.h7
-rw-r--r--crypto/heimdal/kdc/kerberos4.c6
-rw-r--r--crypto/heimdal/lib/gssapi/ChangeLog24
-rw-r--r--crypto/heimdal/lib/gssapi/Makefile.am6
-rw-r--r--crypto/heimdal/lib/gssapi/Makefile.in17
-rw-r--r--crypto/heimdal/lib/gssapi/accept_sec_context.c17
-rw-r--r--crypto/heimdal/lib/gssapi/delete_sec_context.c3
-rw-r--r--crypto/heimdal/lib/gssapi/export_sec_context.c142
-rw-r--r--crypto/heimdal/lib/gssapi/gssapi_locl.h12
-rw-r--r--crypto/heimdal/lib/gssapi/import_sec_context.c180
-rw-r--r--crypto/heimdal/lib/krb5/Makefile.am4
-rw-r--r--crypto/heimdal/lib/krb5/Makefile.in4
-rw-r--r--crypto/heimdal/lib/krb5/changepw.c25
-rw-r--r--crypto/heimdal/lib/krb5/context.c8
-rw-r--r--crypto/heimdal/lib/krb5/krb5-protos.h9
-rw-r--r--crypto/heimdal/lib/krb5/krb5_err.et8
-rw-r--r--crypto/heimdal/lib/krb5/rd_req.c26
-rw-r--r--crypto/heimdal/lib/krb5/transited.c31
-rw-r--r--crypto/heimdal/lib/roken/ChangeLog8
-rw-r--r--crypto/heimdal/lib/roken/Makefile.am5
-rw-r--r--crypto/heimdal/lib/roken/Makefile.in19
-rw-r--r--crypto/heimdal/lib/roken/getaddrinfo_hostspec.c89
-rw-r--r--crypto/heimdal/lib/roken/getarg.c12
-rw-r--r--crypto/heimdal/lib/roken/roken-common.h3
-rw-r--r--crypto/heimdal/lib/roken/roken.h.in7
43 files changed, 12345 insertions, 231 deletions
diff --git a/crypto/heimdal/ChangeLog b/crypto/heimdal/ChangeLog
index f71ec4b..08c0391 100644
--- a/crypto/heimdal/ChangeLog
+++ b/crypto/heimdal/ChangeLog
@@ -1,3 +1,43 @@
+2000-02-14 Assar Westerlund <assar@sics.se>
+
+ * Release 0.2o
+
+2000-02-13 Assar Westerlund <assar@sics.se>
+
+ * lib/krb5/Makefile.am: set version to 9:0:0
+
+ * kdc/kaserver.c (do_authenticate): return the kvno of the server
+ and not the client. Thanks to Brandon S. Allbery KF8NH
+ <allbery@kf8nh.apk.net> and Chaskiel M Grundman
+ <cg2v@andrew.cmu.edu> for debugging.
+
+ * kdc/kerberos4.c (do_version4): if an tgs-req is received with an
+ old kvno, return an error reply and write a message in the log.
+
+2000-02-12 Assar Westerlund <assar@sics.se>
+
+ * appl/test/gssapi_server.c (proto): with `--fork', create a child
+ and send over/receive creds with export/import_sec_context
+ * appl/test/gssapi_client.c (proto): with `--fork', create a child
+ and send over/receive creds with export/import_sec_context
+ * appl/test/common.c: add `--fork' / `-f' (only used by gssapi)
+
+2000-02-11 Assar Westerlund <assar@sics.se>
+
+ * kdc/kdc_locl.h: remove keyfile add explicit_addresses
+ * kdc/connect.c (init_sockets): pay attention to
+ explicit_addresses some more comments. better error messages.
+ * kdc/config.c: add some comments.
+ remove --key-file.
+ add --addresses.
+
+ * lib/krb5/context.c (krb5_set_extra_addresses): const-ize and use
+ proper abstraction
+
+2000-02-07 Johan Danielsson <joda@pdc.kth.se>
+
+ * lib/krb5/changepw.c: use roken_getaddrinfo_hostspec
+
2000-02-07 Assar Westerlund <assar@sics.se>
* Release 0.2n
diff --git a/crypto/heimdal/NEWS b/crypto/heimdal/NEWS
index 9410ada..b9799c7 100644
--- a/crypto/heimdal/NEWS
+++ b/crypto/heimdal/NEWS
@@ -1,3 +1,14 @@
+Changes in release 0.2o:
+
+ * gss_{import,export}_sec_context added to libgssapi
+
+ * new option --addresses to kdc (for listening on an explicit set of
+ addresses)
+
+ * bug fixes in the krb4 and kaserver emulation part of the kdc
+
+ * other bug fixes
+
Changes in release 0.2n:
* more robust parsing of dump files in kadmin
diff --git a/crypto/heimdal/appl/telnet/ChangeLog b/crypto/heimdal/appl/telnet/ChangeLog
index 76a7546..b38f16d 100644
--- a/crypto/heimdal/appl/telnet/ChangeLog
+++ b/crypto/heimdal/appl/telnet/ChangeLog
@@ -1,3 +1,8 @@
+2000-02-12 Assar Westerlund <assar@sics.se>
+
+ * telnet/commands.c (tn): only set tos for AF_INET. From
+ itojun@iijlab.net
+
2000-02-07 Assar Westerlund <assar@sics.se>
* libtelnet/kerberos.c (kerberos4_is): send a reject back to the
diff --git a/crypto/heimdal/appl/telnet/telnet/commands.c b/crypto/heimdal/appl/telnet/telnet/commands.c
index 1cf0ee8..dd78636 100644
--- a/crypto/heimdal/appl/telnet/telnet/commands.c
+++ b/crypto/heimdal/appl/telnet/telnet/commands.c
@@ -33,7 +33,7 @@
#include "telnet_locl.h"
-RCSID("$Id: commands.c,v 1.59 2000/01/08 08:04:16 assar Exp $");
+RCSID("$Id: commands.c,v 1.60 2000/02/12 16:00:07 assar Exp $");
#if defined(IPPROTO_IP) && defined(IP_TOS)
int tos = -1;
@@ -2201,7 +2201,7 @@ tn(int argc, char **argv)
perror("setsockopt (IP_OPTIONS)");
#endif
#if defined(IPPROTO_IP) && defined(IP_TOS)
- {
+ if (a->ai_family == AF_INET) {
# if defined(HAVE_GETTOSBYNAME)
struct tosent *tp;
if (tos < 0 && (tp = gettosbyname("telnet", "tcp")))
diff --git a/crypto/heimdal/appl/test/common.c b/crypto/heimdal/appl/test/common.c
index 5cd4e85..30b2e2d 100644
--- a/crypto/heimdal/appl/test/common.c
+++ b/crypto/heimdal/appl/test/common.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,16 +33,18 @@
#include "test_locl.h"
-RCSID("$Id: common.c,v 1.9 1999/12/16 10:29:18 assar Exp $");
+RCSID("$Id: common.c,v 1.10 2000/02/12 21:30:47 assar Exp $");
static int help_flag;
static int version_flag;
static char *port_str;
char *service = SERVICE;
+int fork_flag;
static struct getargs args[] = {
{ "port", 'p', arg_string, &port_str, "port to listen to", "port" },
{ "service", 's', arg_string, &service, "service to use", "service" },
+ { "fork", 'f', arg_flag, &fork_flag, "do fork" },
{ "help", 'h', arg_flag, &help_flag },
{ "version", 0, arg_flag, &version_flag }
};
diff --git a/crypto/heimdal/appl/test/gss_common.c b/crypto/heimdal/appl/test/gss_common.c
index c82ba13..821114b 100644
--- a/crypto/heimdal/appl/test/gss_common.c
+++ b/crypto/heimdal/appl/test/gss_common.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -34,7 +34,7 @@
#include "test_locl.h"
#include <gssapi.h>
#include "gss_common.h"
-RCSID("$Id: gss_common.c,v 1.6 1999/12/02 17:04:56 joda Exp $");
+RCSID("$Id: gss_common.c,v 1.7 2000/02/12 21:31:38 assar Exp $");
void
write_token (int sock, gss_buffer_t buf)
@@ -64,6 +64,8 @@ read_token (int sock, gss_buffer_t buf)
len = ntohl(net_len);
buf->length = len;
buf->value = malloc(len);
+ if (buf->value == NULL)
+ err (1, "malloc %u", len);
if (read (sock, buf->value, len) != len)
err (1, "read");
}
diff --git a/crypto/heimdal/appl/test/gssapi_client.c b/crypto/heimdal/appl/test/gssapi_client.c
index 7d15b99..ed3c43a 100644
--- a/crypto/heimdal/appl/test/gssapi_client.c
+++ b/crypto/heimdal/appl/test/gssapi_client.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997 - 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -34,7 +34,52 @@
#include "test_locl.h"
#include <gssapi.h>
#include "gss_common.h"
-RCSID("$Id: gssapi_client.c,v 1.10 1999/12/04 18:15:50 assar Exp $");
+RCSID("$Id: gssapi_client.c,v 1.12 2000/02/12 21:33:17 assar Exp $");
+
+static int
+do_trans (int sock, gss_ctx_id_t context_hdl)
+{
+ OM_uint32 maj_stat, min_stat;
+ gss_buffer_desc real_input_token, real_output_token;
+ gss_buffer_t input_token = &real_input_token,
+ output_token = &real_output_token;
+
+ /* get_mic */
+
+ input_token->length = 3;
+ input_token->value = strdup("hej");
+
+ maj_stat = gss_get_mic(&min_stat,
+ context_hdl,
+ GSS_C_QOP_DEFAULT,
+ input_token,
+ output_token);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_get_mic");
+
+ write_token (sock, input_token);
+ write_token (sock, output_token);
+
+ /* wrap */
+
+ input_token->length = 7;
+ input_token->value = "hemligt";
+
+
+ maj_stat = gss_wrap (&min_stat,
+ context_hdl,
+ 1,
+ GSS_C_QOP_DEFAULT,
+ input_token,
+ NULL,
+ output_token);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_wrap");
+
+ write_token (sock, output_token);
+
+ return 0;
+}
static int
proto (int sock, const char *hostname, const char *service)
@@ -44,8 +89,9 @@ proto (int sock, const char *hostname, const char *service)
int context_established = 0;
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
- gss_buffer_t input_token, output_token;
gss_buffer_desc real_input_token, real_output_token;
+ gss_buffer_t input_token = &real_input_token,
+ output_token = &real_output_token;
OM_uint32 maj_stat, min_stat;
gss_name_t server;
gss_buffer_desc name_token;
@@ -71,9 +117,6 @@ proto (int sock, const char *hostname, const char *service)
|| addrlen != sizeof(remote))
err (1, "getpeername(%s)", hostname);
- input_token = &real_input_token;
- output_token = &real_output_token;
-
input_token->length = 0;
output_token->length = 0;
@@ -110,42 +153,42 @@ proto (int sock, const char *hostname, const char *service)
}
}
-
- /* get_mic */
-
- input_token->length = 3;
- input_token->value = strdup("hej");
-
- maj_stat = gss_get_mic(&min_stat,
- context_hdl,
- GSS_C_QOP_DEFAULT,
- input_token,
- output_token);
- if (GSS_ERROR(maj_stat))
- gss_err (1, min_stat, "gss_get_mic");
-
- write_token (sock, input_token);
- write_token (sock, output_token);
-
- /* wrap */
-
- input_token->length = 7;
- input_token->value = "hemligt";
-
-
- maj_stat = gss_wrap (&min_stat,
- context_hdl,
- 1,
- GSS_C_QOP_DEFAULT,
- input_token,
- NULL,
- output_token);
- if (GSS_ERROR(maj_stat))
- gss_err (1, min_stat, "gss_wrap");
-
- write_token (sock, output_token);
-
- return 0;
+ if (fork_flag) {
+ pid_t pid;
+ int pipefd[2];
+
+ if (pipe (pipefd) < 0)
+ err (1, "pipe");
+
+ pid = fork ();
+ if (pid < 0)
+ err (1, "fork");
+ if (pid != 0) {
+ gss_buffer_desc buf;
+
+ maj_stat = gss_export_sec_context (&min_stat,
+ &context_hdl,
+ &buf);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_export_sec_context");
+ write_token (pipefd[1], &buf);
+ exit (0);
+ } else {
+ gss_ctx_id_t context_hdl;
+ gss_buffer_desc buf;
+
+ close (pipefd[1]);
+ read_token (pipefd[0], &buf);
+ close (pipefd[0]);
+ maj_stat = gss_import_sec_context (&min_stat, &buf, &context_hdl);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_import_sec_context");
+ gss_release_buffer (&min_stat, &buf);
+ return do_trans (sock, context_hdl);
+ }
+ } else {
+ return do_trans (sock, context_hdl);
+ }
}
int
diff --git a/crypto/heimdal/appl/test/gssapi_server.c b/crypto/heimdal/appl/test/gssapi_server.c
index a17ce3e..01aa769 100644
--- a/crypto/heimdal/appl/test/gssapi_server.c
+++ b/crypto/heimdal/appl/test/gssapi_server.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997 - 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -34,59 +34,19 @@
#include "test_locl.h"
#include <gssapi.h>
#include "gss_common.h"
-RCSID("$Id: gssapi_server.c,v 1.10 1999/12/16 10:29:41 assar Exp $");
+RCSID("$Id: gssapi_server.c,v 1.12 2000/02/12 21:34:11 assar Exp $");
static int
-proto (int sock, const char *service)
+process_it(int sock,
+ gss_ctx_id_t context_hdl,
+ gss_name_t client_name
+ )
{
- struct sockaddr_in remote, local;
- int addrlen;
- gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
- gss_buffer_t input_token, output_token;
- gss_buffer_desc real_input_token, real_output_token;
OM_uint32 maj_stat, min_stat;
- gss_name_t client_name;
gss_buffer_desc name_token;
-
- addrlen = sizeof(local);
- if (getsockname (sock, (struct sockaddr *)&local, &addrlen) < 0
- || addrlen != sizeof(local))
- err (1, "getsockname)");
-
- addrlen = sizeof(remote);
- if (getpeername (sock, (struct sockaddr *)&remote, &addrlen) < 0
- || addrlen != sizeof(remote))
- err (1, "getpeername");
-
- input_token = &real_input_token;
- output_token = &real_output_token;
-
- do {
- read_token (sock, input_token);
- maj_stat =
- gss_accept_sec_context (&min_stat,
- &context_hdl,
- GSS_C_NO_CREDENTIAL,
- input_token,
- GSS_C_NO_CHANNEL_BINDINGS,
- &client_name,
- NULL,
- output_token,
- NULL,
- NULL,
- NULL);
- if(GSS_ERROR(maj_stat))
- gss_err (1, min_stat, "gss_accept_sec_context");
- if (output_token->length != 0)
- write_token (sock, output_token);
- if (GSS_ERROR(maj_stat)) {
- if (context_hdl != GSS_C_NO_CONTEXT)
- gss_delete_sec_context (&min_stat,
- &context_hdl,
- GSS_C_NO_BUFFER);
- break;
- }
- } while(maj_stat & GSS_S_CONTINUE_NEEDED);
+ gss_buffer_desc real_input_token, real_output_token;
+ gss_buffer_t input_token = &real_input_token,
+ output_token = &real_output_token;
maj_stat = gss_display_name (&min_stat,
client_name,
@@ -98,6 +58,8 @@ proto (int sock, const char *service)
fprintf (stderr, "User is `%.*s'\n", (int)name_token.length,
(char *)name_token.value);
+ gss_release_buffer (&min_stat, &name_token);
+
/* gss_verify_mic */
read_token (sock, input_token);
@@ -114,6 +76,9 @@ proto (int sock, const char *service)
fprintf (stderr, "gss_verify_mic: %.*s\n", (int)input_token->length,
(char *)input_token->value);
+ gss_release_buffer (&min_stat, input_token);
+ gss_release_buffer (&min_stat, output_token);
+
/* gss_unwrap */
read_token (sock, input_token);
@@ -130,10 +95,100 @@ proto (int sock, const char *service)
fprintf (stderr, "gss_unwrap: %.*s\n", (int)output_token->length,
(char *)output_token->value);
+ gss_release_buffer (&min_stat, input_token);
+ gss_release_buffer (&min_stat, output_token);
+
return 0;
}
static int
+proto (int sock, const char *service)
+{
+ struct sockaddr_in remote, local;
+ int addrlen;
+ gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
+ gss_buffer_desc real_input_token, real_output_token;
+ gss_buffer_t input_token = &real_input_token,
+ output_token = &real_output_token;
+ OM_uint32 maj_stat, min_stat;
+ gss_name_t client_name;
+
+ addrlen = sizeof(local);
+ if (getsockname (sock, (struct sockaddr *)&local, &addrlen) < 0
+ || addrlen != sizeof(local))
+ err (1, "getsockname)");
+
+ addrlen = sizeof(remote);
+ if (getpeername (sock, (struct sockaddr *)&remote, &addrlen) < 0
+ || addrlen != sizeof(remote))
+ err (1, "getpeername");
+
+ do {
+ read_token (sock, input_token);
+ maj_stat =
+ gss_accept_sec_context (&min_stat,
+ &context_hdl,
+ GSS_C_NO_CREDENTIAL,
+ input_token,
+ GSS_C_NO_CHANNEL_BINDINGS,
+ &client_name,
+ NULL,
+ output_token,
+ NULL,
+ NULL,
+ NULL);
+ if(GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_accept_sec_context");
+ if (output_token->length != 0)
+ write_token (sock, output_token);
+ if (GSS_ERROR(maj_stat)) {
+ if (context_hdl != GSS_C_NO_CONTEXT)
+ gss_delete_sec_context (&min_stat,
+ &context_hdl,
+ GSS_C_NO_BUFFER);
+ break;
+ }
+ } while(maj_stat & GSS_S_CONTINUE_NEEDED);
+
+ if (fork_flag) {
+ pid_t pid;
+ int pipefd[2];
+
+ if (pipe (pipefd) < 0)
+ err (1, "pipe");
+
+ pid = fork ();
+ if (pid < 0)
+ err (1, "fork");
+ if (pid != 0) {
+ gss_buffer_desc buf;
+
+ maj_stat = gss_export_sec_context (&min_stat,
+ &context_hdl,
+ &buf);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_export_sec_context");
+ write_token (pipefd[1], &buf);
+ exit (0);
+ } else {
+ gss_ctx_id_t context_hdl;
+ gss_buffer_desc buf;
+
+ close (pipefd[1]);
+ read_token (pipefd[0], &buf);
+ close (pipefd[0]);
+ maj_stat = gss_import_sec_context (&min_stat, &buf, &context_hdl);
+ if (GSS_ERROR(maj_stat))
+ gss_err (1, min_stat, "gss_import_sec_context");
+ gss_release_buffer (&min_stat, &buf);
+ return process_it (sock, context_hdl, client_name);
+ }
+ } else {
+ return process_it (sock, context_hdl, client_name);
+ }
+}
+
+static int
doit (int port, const char *service)
{
int sock, sock2;
diff --git a/crypto/heimdal/appl/test/test_locl.h b/crypto/heimdal/appl/test/test_locl.h
index 045d060..5c4ca36 100644
--- a/crypto/heimdal/appl/test/test_locl.h
+++ b/crypto/heimdal/appl/test/test_locl.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997 - 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -31,7 +31,7 @@
* SUCH DAMAGE.
*/
-/* $Id: test_locl.h,v 1.7 1999/12/04 18:17:07 assar Exp $ */
+/* $Id: test_locl.h,v 1.8 2000/02/14 02:52:55 assar Exp $ */
#ifdef HAVE_CONFIG_H
#include <config.h>
@@ -79,6 +79,7 @@
#define PORT "test"
extern char *service;
+extern int fork_flag;
int server_setup(krb5_context*, int, char**);
int client_setup(krb5_context*, int*, char**);
int client_doit (const char *hostname, int port, const char *service,
diff --git a/crypto/heimdal/configure b/crypto/heimdal/configure
index d568104..3c92e5f 100755
--- a/crypto/heimdal/configure
+++ b/crypto/heimdal/configure
@@ -1,6 +1,6 @@
#! /bin/sh
-# From configure.in Revision: 1.216
+# From configure.in Revision: 1.217
@@ -911,7 +911,7 @@ fi
PACKAGE=heimdal
-VERSION=0.2n
+VERSION=0.2o
if test "`cd $srcdir && pwd`" != "`pwd`" && test -f $srcdir/config.status; then
{ echo "configure: error: source directory already configured; run "make distclean" there first" 1>&2; exit 1; }
diff --git a/crypto/heimdal/configure.in b/crypto/heimdal/configure.in
index 3bbb65a..3f814c1 100644
--- a/crypto/heimdal/configure.in
+++ b/crypto/heimdal/configure.in
@@ -1,9 +1,9 @@
dnl Process this file with autoconf to produce a configure script.
-AC_REVISION($Revision: 1.216 $)
+AC_REVISION($Revision: 1.217 $)
AC_INIT(lib/krb5/send_to_kdc.c)
AM_CONFIG_HEADER(include/config.h)
-AM_INIT_AUTOMAKE(heimdal,0.2n)
+AM_INIT_AUTOMAKE(heimdal,0.2o)
AC_PREFIX_DEFAULT(/usr/heimdal)
diff --git a/crypto/heimdal/doc/ack.texi b/crypto/heimdal/doc/ack.texi
index bfb03b8..1594194 100644
--- a/crypto/heimdal/doc/ack.texi
+++ b/crypto/heimdal/doc/ack.texi
@@ -49,6 +49,8 @@ Bugfixes, documentation, encouragement, and code has been contributed by:
@email{ruda@@ics.muni.cz}
@item Brian A May
@email{bmay@@snoopy.apana.org.au}
+@item Chaskiel M Grundman
+@email{cg2v@@andrew.cmu.edu}
@item and we hope that those not mentioned here will forgive us.
@end table
diff --git a/crypto/heimdal/doc/standardisation/rfc2743.txt b/crypto/heimdal/doc/standardisation/rfc2743.txt
new file mode 100644
index 0000000..e5da571
--- /dev/null
+++ b/crypto/heimdal/doc/standardisation/rfc2743.txt
@@ -0,0 +1,5659 @@
+
+
+
+
+
+
+Network Working Group J. Linn
+Request for Comments: 2743 RSA Laboratories
+Obsoletes: 2078 January 2000
+Category: Standards Track
+
+
+ Generic Security Service Application Program Interface
+ Version 2, Update 1
+
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+Abstract
+
+ The Generic Security Service Application Program Interface (GSS-API),
+ Version 2, as defined in [RFC-2078], provides security services to
+ callers in a generic fashion, supportable with a range of underlying
+ mechanisms and technologies and hence allowing source-level
+ portability of applications to different environments. This
+ specification defines GSS-API services and primitives at a level
+ independent of underlying mechanism and programming language
+ environment, and is to be complemented by other, related
+ specifications:
+
+ documents defining specific parameter bindings for particular
+ language environments
+
+ documents defining token formats, protocols, and procedures to be
+ implemented in order to realize GSS-API services atop particular
+ security mechanisms
+
+ This memo obsoletes [RFC-2078], making specific, incremental changes
+ in response to implementation experience and liaison requests. It is
+ intended, therefore, that this memo or a successor version thereto
+ will become the basis for subsequent progression of the GSS-API
+ specification on the standards track.
+
+
+
+
+
+Linn Standards Track [Page 1]
+
+RFC 2743 GSS-API January 2000
+
+
+TABLE OF CONTENTS
+
+ 1: GSS-API Characteristics and Concepts . . . . . . . . . . . . 4
+ 1.1: GSS-API Constructs . . . . . . . . . . . . . . . . . . . . 6
+ 1.1.1: Credentials . . . . . . . . . . . . . . . . . . . . . . 6
+ 1.1.1.1: Credential Constructs and Concepts . . . . . . . . . . 6
+ 1.1.1.2: Credential Management . . . . . . . . . . . . . . . . 7
+ 1.1.1.3: Default Credential Resolution . . . . . . . . . . . . 8
+ 1.1.2: Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 1.1.3: Security Contexts . . . . . . . . . . . . . . . . . . . 11
+ 1.1.4: Mechanism Types . . . . . . . . . . . . . . . . . . . . 12
+ 1.1.5: Naming . . . . . . . . . . . . . . . . . . . . . . . . 13
+ 1.1.6: Channel Bindings . . . . . . . . . . . . . . . . . . . 16
+ 1.2: GSS-API Features and Issues . . . . . . . . . . . . . . . 17
+ 1.2.1: Status Reporting and Optional Service Support . . . . 17
+ 1.2.1.1: Status Reporting . . . . . . . . . . . . . . . . . . . 17
+ 1.2.1.2: Optional Service Support . . . . . . . . . . . . . . . 19
+ 1.2.2: Per-Message Security Service Availability . . . . . . . 20
+ 1.2.3: Per-Message Replay Detection and Sequencing . . . . . . 21
+ 1.2.4: Quality of Protection . . . . . . . . . . . . . . . . . 24
+ 1.2.5: Anonymity Support . . . . . . . . . . . . . . . . . . . 25
+ 1.2.6: Initialization . . . . . . . . . . . . . . . . . . . . . 25
+ 1.2.7: Per-Message Protection During Context Establishment . . 26
+ 1.2.8: Implementation Robustness . . . . . . . . . . . . . . . 27
+ 1.2.9: Delegation . . . . . . . . . . . . . . . . . . . . . . . 28
+ 1.2.10: Interprocess Context Transfer . . . . . . . . . . . . . 28
+ 2: Interface Descriptions . . . . . . . . . . . . . . . . . . 29
+ 2.1: Credential management calls . . . . . . . . . . . . . . . 31
+ 2.1.1: GSS_Acquire_cred call . . . . . . . . . . . . . . . . . 31
+ 2.1.2: GSS_Release_cred call . . . . . . . . . . . . . . . . . 34
+ 2.1.3: GSS_Inquire_cred call . . . . . . . . . . . . . . . . . 35
+ 2.1.4: GSS_Add_cred call . . . . . . . . . . . . . . . . . . . 37
+ 2.1.5: GSS_Inquire_cred_by_mech call . . . . . . . . . . . . . 40
+ 2.2: Context-level calls . . . . . . . . . . . . . . . . . . . 41
+ 2.2.1: GSS_Init_sec_context call . . . . . . . . . . . . . . . 42
+ 2.2.2: GSS_Accept_sec_context call . . . . . . . . . . . . . . 49
+ 2.2.3: GSS_Delete_sec_context call . . . . . . . . . . . . . . 53
+ 2.2.4: GSS_Process_context_token call . . . . . . . . . . . . 54
+ 2.2.5: GSS_Context_time call . . . . . . . . . . . . . . . . . 55
+ 2.2.6: GSS_Inquire_context call . . . . . . . . . . . . . . . 56
+ 2.2.7: GSS_Wrap_size_limit call . . . . . . . . . . . . . . . 57
+ 2.2.8: GSS_Export_sec_context call . . . . . . . . . . . . . . 59
+ 2.2.9: GSS_Import_sec_context call . . . . . . . . . . . . . . 61
+ 2.3: Per-message calls . . . . . . . . . . . . . . . . . . . . 62
+ 2.3.1: GSS_GetMIC call . . . . . . . . . . . . . . . . . . . . 63
+ 2.3.2: GSS_VerifyMIC call . . . . . . . . . . . . . . . . . . 64
+ 2.3.3: GSS_Wrap call . . . . . . . . . . . . . . . . . . . . . 65
+ 2.3.4: GSS_Unwrap call . . . . . . . . . . . . . . . . . . . . 66
+
+
+
+Linn Standards Track [Page 2]
+
+RFC 2743 GSS-API January 2000
+
+
+ 2.4: Support calls . . . . . . . . . . . . . . . . . . . . . . 68
+ 2.4.1: GSS_Display_status call . . . . . . . . . . . . . . . . 68
+ 2.4.2: GSS_Indicate_mechs call . . . . . . . . . . . . . . . . 69
+ 2.4.3: GSS_Compare_name call . . . . . . . . . . . . . . . . . 70
+ 2.4.4: GSS_Display_name call . . . . . . . . . . . . . . . . . 71
+ 2.4.5: GSS_Import_name call . . . . . . . . . . . . . . . . . 72
+ 2.4.6: GSS_Release_name call . . . . . . . . . . . . . . . . . 73
+ 2.4.7: GSS_Release_buffer call . . . . . . . . . . . . . . . . 74
+ 2.4.8: GSS_Release_OID_set call . . . . . . . . . . . . . . . 74
+ 2.4.9: GSS_Create_empty_OID_set call . . . . . . . . . . . . . 75
+ 2.4.10: GSS_Add_OID_set_member call . . . . . . . . . . . . . . 76
+ 2.4.11: GSS_Test_OID_set_member call . . . . . . . . . . . . . 76
+ 2.4.12: GSS_Inquire_names_for_mech call . . . . . . . . . . . . 77
+ 2.4.13: GSS_Inquire_mechs_for_name call . . . . . . . . . . . . 77
+ 2.4.14: GSS_Canonicalize_name call . . . . . . . . . . . . . . 78
+ 2.4.15: GSS_Export_name call . . . . . . . . . . . . . . . . . 79
+ 2.4.16: GSS_Duplicate_name call . . . . . . . . . . . . . . . . 80
+ 3: Data Structure Definitions for GSS-V2 Usage . . . . . . . . 81
+ 3.1: Mechanism-Independent Token Format . . . . . . . . . . . . 81
+ 3.2: Mechanism-Independent Exported Name Object Format . . . . 84
+ 4: Name Type Definitions . . . . . . . . . . . . . . . . . . . 85
+ 4.1: Host-Based Service Name Form . . . . . . . . . . . . . . . 85
+ 4.2: User Name Form . . . . . . . . . . . . . . . . . . . . . . 86
+ 4.3: Machine UID Form . . . . . . . . . . . . . . . . . . . . . 87
+ 4.4: String UID Form . . . . . . . . . . . . . . . . . . . . . 87
+ 4.5: Anonymous Nametype . . . . . . . . . . . . . . . . . . . . 87
+ 4.6: GSS_C_NO_OID . . . . . . . . . . . . . . . . . . . . . . . 88
+ 4.7: Exported Name Object . . . . . . . . . . . . . . . . . . . 88
+ 4.8: GSS_C_NO_NAME . . . . . . . . . . . . . . . . . . . . . . 88
+ 5: Mechanism-Specific Example Scenarios . . . . . . . . . . . 88
+ 5.1: Kerberos V5, single-TGT . . . . . . . . . . . . . . . . . 89
+ 5.2: Kerberos V5, double-TGT . . . . . . . . . . . . . . . . . 89
+ 5.3: X.509 Authentication Framework . . . . . . . . . . . . . 90
+ 6: Security Considerations . . . . . . . . . . . . . . . . . . 91
+ 7: Related Activities . . . . . . . . . . . . . . . . . . . . 92
+ 8: Referenced Documents . . . . . . . . . . . . . . . . . . . 93
+ Appendix A: Mechanism Design Constraints . . . . . . . . . . . 94
+ Appendix B: Compatibility with GSS-V1 . . . . . . . . . . . . . 94
+ Appendix C: Changes Relative to RFC-2078 . . . . . . . . . . . 96
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . .100
+ Full Copyright Statement . . . . . . . . . . . . . . . . . . .101
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 3]
+
+RFC 2743 GSS-API January 2000
+
+
+1: GSS-API Characteristics and Concepts
+
+ GSS-API operates in the following paradigm. A typical GSS-API caller
+ is itself a communications protocol, calling on GSS-API in order to
+ protect its communications with authentication, integrity, and/or
+ confidentiality security services. A GSS-API caller accepts tokens
+ provided to it by its local GSS-API implementation and transfers the
+ tokens to a peer on a remote system; that peer passes the received
+ tokens to its local GSS-API implementation for processing. The
+ security services available through GSS-API in this fashion are
+ implementable (and have been implemented) over a range of underlying
+ mechanisms based on secret-key and public-key cryptographic
+ technologies.
+
+ The GSS-API separates the operations of initializing a security
+ context between peers, achieving peer entity authentication
+ (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the
+ operations of providing per-message data origin authentication and
+ data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls)
+ for messages subsequently transferred in conjunction with that
+ context. (The definition for the peer entity authentication service,
+ and other definitions used in this document, corresponds to that
+ provided in [ISO-7498-2].) When establishing a security context, the
+ GSS-API enables a context initiator to optionally permit its
+ credentials to be delegated, meaning that the context acceptor may
+ initiate further security contexts on behalf of the initiating
+ caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the
+ data origin authentication and data integrity services which
+ GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of
+ confidentiality services as a caller option. Additional calls provide
+ supportive functions to the GSS-API's users.
+
+ The following paragraphs provide an example illustrating the
+ dataflows involved in use of the GSS-API by a client and server in a
+ mechanism-independent fashion, establishing a security context and
+ transferring a protected message. The example assumes that credential
+ acquisition has already been completed. The example also assumes
+ that the underlying authentication technology is capable of
+ authenticating a client to a server using elements carried within a
+ single token, and of authenticating the server to the client (mutual
+ authentication) with a single returned token; this assumption holds
+ for some presently-documented CAT mechanisms but is not necessarily
+ true for other cryptographic technologies and associated protocols.
+
+ The client calls GSS_Init_sec_context() to establish a security
+ context to the server identified by targ_name, and elects to set the
+ mutual_req_flag so that mutual authentication is performed in the
+ course of context establishment. GSS_Init_sec_context() returns an
+
+
+
+Linn Standards Track [Page 4]
+
+RFC 2743 GSS-API January 2000
+
+
+ output_token to be passed to the server, and indicates
+ GSS_S_CONTINUE_NEEDED status pending completion of the mutual
+ authentication sequence. Had mutual_req_flag not been set, the
+ initial call to GSS_Init_sec_context() would have returned
+ GSS_S_COMPLETE status. The client sends the output_token to the
+ server.
+
+ The server passes the received token as the input_token parameter to
+ GSS_Accept_sec_context(). GSS_Accept_sec_context indicates
+ GSS_S_COMPLETE status, provides the client's authenticated identity
+ in the src_name result, and provides an output_token to be passed to
+ the client. The server sends the output_token to the client.
+
+ The client passes the received token as the input_token parameter to
+ a successor call to GSS_Init_sec_context(), which processes data
+ included in the token in order to achieve mutual authentication from
+ the client's viewpoint. This call to GSS_Init_sec_context() returns
+ GSS_S_COMPLETE status, indicating successful mutual authentication
+ and the completion of context establishment for this example.
+
+ The client generates a data message and passes it to GSS_Wrap().
+ GSS_Wrap() performs data origin authentication, data integrity, and
+ (optionally) confidentiality processing on the message and
+ encapsulates the result into output_message, indicating
+ GSS_S_COMPLETE status. The client sends the output_message to the
+ server.
+
+ The server passes the received message to GSS_Unwrap(). GSS_Unwrap()
+ inverts the encapsulation performed by GSS_Wrap(), deciphers the
+ message if the optional confidentiality feature was applied, and
+ validates the data origin authentication and data integrity checking
+ quantities. GSS_Unwrap() indicates successful validation by returning
+ GSS_S_COMPLETE status along with the resultant output_message.
+
+ For purposes of this example, we assume that the server knows by
+ out-of-band means that this context will have no further use after
+ one protected message is transferred from client to server. Given
+ this premise, the server now calls GSS_Delete_sec_context() to flush
+ context-level information. Optionally, the server-side application
+ may provide a token buffer to GSS_Delete_sec_context(), to receive a
+ context_token to be transferred to the client in order to request
+ that client-side context-level information be deleted.
+
+ If a context_token is transferred, the client passes the
+ context_token to GSS_Process_context_token(), which returns
+ GSS_S_COMPLETE status after deleting context-level information at the
+ client system.
+
+
+
+
+Linn Standards Track [Page 5]
+
+RFC 2743 GSS-API January 2000
+
+
+ The GSS-API design assumes and addresses several basic goals,
+ including:
+
+ Mechanism independence: The GSS-API defines an interface to
+ cryptographically implemented strong authentication and other
+ security services at a generic level which is independent of
+ particular underlying mechanisms. For example, GSS-API-provided
+ services have been implemented using secret-key technologies
+ (e.g., Kerberos, per [RFC-1964]) and with public-key approaches
+ (e.g., SPKM, per [RFC-2025]).
+
+ Protocol environment independence: The GSS-API is independent of
+ the communications protocol suites with which it is employed,
+ permitting use in a broad range of protocol environments. In
+ appropriate environments, an intermediate implementation "veneer"
+ which is oriented to a particular communication protocol may be
+ interposed between applications which call that protocol and the
+ GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing
+ Remote Procedure Call (RPC)), thereby invoking GSS-API facilities
+ in conjunction with that protocol's communications invocations.
+
+ Protocol association independence: The GSS-API's security context
+ construct is independent of communications protocol association
+ constructs. This characteristic allows a single GSS-API
+ implementation to be utilized by a variety of invoking protocol
+ modules on behalf of those modules' calling applications. GSS-API
+ services can also be invoked directly by applications, wholly
+ independent of protocol associations.
+
+ Suitability to a range of implementation placements: GSS-API
+ clients are not constrained to reside within any Trusted Computing
+ Base (TCB) perimeter defined on a system where the GSS-API is
+ implemented; security services are specified in a manner suitable
+ to both intra-TCB and extra-TCB callers.
+
+1.1: GSS-API Constructs
+
+ This section describes the basic elements comprising the GSS-API.
+
+1.1.1: Credentials
+
+1.1.1.1: Credential Constructs and Concepts
+
+ Credentials provide the prerequisites which permit GSS-API peers to
+ establish security contexts with each other. A caller may designate
+ that the credential elements which are to be applied for context
+ initiation or acceptance be selected by default. Alternately, those
+ GSS-API callers which need to make explicit selection of particular
+
+
+
+Linn Standards Track [Page 6]
+
+RFC 2743 GSS-API January 2000
+
+
+ credentials structures may make references to those credentials
+ through GSS-API-provided credential handles ("cred_handles"). In all
+ cases, callers' credential references are indirect, mediated by GSS-
+ API implementations and not requiring callers to access the selected
+ credential elements.
+
+ A single credential structure may be used to initiate outbound
+ contexts and to accept inbound contexts. Callers needing to operate
+ in only one of these modes may designate this fact when credentials
+ are acquired for use, allowing underlying mechanisms to optimize
+ their processing and storage requirements. The credential elements
+ defined by a particular mechanism may contain multiple cryptographic
+ keys, e.g., to enable authentication and message encryption to be
+ performed with different algorithms.
+
+ A GSS-API credential structure may contain multiple credential
+ elements, each containing mechanism-specific information for a
+ particular underlying mechanism (mech_type), but the set of elements
+ within a given credential structure represent a common entity. A
+ credential structure's contents will vary depending on the set of
+ mech_types supported by a particular GSS-API implementation. Each
+ credential element identifies the data needed by its mechanism in
+ order to establish contexts on behalf of a particular principal, and
+ may contain separate credential references for use in context
+ initiation and context acceptance. Multiple credential elements
+ within a given credential having overlapping combinations of
+ mechanism, usage mode, and validity period are not permitted.
+
+ Commonly, a single mech_type will be used for all security contexts
+ established by a particular initiator to a particular target. A major
+ motivation for supporting credential sets representing multiple
+ mech_types is to allow initiators on systems which are equipped to
+ handle multiple types to initiate contexts to targets on other
+ systems which can accommodate only a subset of the set supported at
+ the initiator's system.
+
+1.1.1.2: Credential Management
+
+ It is the responsibility of underlying system-specific mechanisms and
+ OS functions below the GSS-API to ensure that the ability to acquire
+ and use credentials associated with a given identity is constrained
+ to appropriate processes within a system. This responsibility should
+ be taken seriously by implementors, as the ability for an entity to
+ utilize a principal's credentials is equivalent to the entity's
+ ability to successfully assert that principal's identity.
+
+
+
+
+
+
+Linn Standards Track [Page 7]
+
+RFC 2743 GSS-API January 2000
+
+
+ Once a set of GSS-API credentials is established, the transferability
+ of that credentials set to other processes or analogous constructs
+ within a system is a local matter, not defined by the GSS-API. An
+ example local policy would be one in which any credentials received
+ as a result of login to a given user account, or of delegation of
+ rights to that account, are accessible by, or transferable to,
+ processes running under that account.
+
+ The credential establishment process (particularly when performed on
+ behalf of users rather than server processes) is likely to require
+ access to passwords or other quantities which should be protected
+ locally and exposed for the shortest time possible. As a result, it
+ will often be appropriate for preliminary credential establishment to
+ be performed through local means at user login time, with the
+ result(s) cached for subsequent reference. These preliminary
+ credentials would be set aside (in a system-specific fashion) for
+ subsequent use, either:
+
+ to be accessed by an invocation of the GSS-API GSS_Acquire_cred()
+ call, returning an explicit handle to reference that credential
+
+ to comprise default credential elements to be installed, and to be
+ used when default credential behavior is requested on behalf of a
+ process
+
+1.1.1.3: Default Credential Resolution
+
+ The GSS_Init_sec_context() and GSS_Accept_sec_context() routines
+ allow the value GSS_C_NO_CREDENTIAL to be specified as their
+ credential handle parameter. This special credential handle
+ indicates a desire by the application to act as a default principal.
+ In support of application portability, support for the default
+ resolution behavior described below for initiator credentials
+ (GSS_Init_sec_context() usage) is mandated; support for the default
+ resolution behavior described below for acceptor credentials
+ (GSS_Accept_sec_context() usage) is recommended. If default
+ credential resolution fails, GSS_S_NO_CRED status is to be returned.
+
+ GSS_Init_sec_context:
+
+ (i) If there is only a single principal capable of initiating
+ security contexts that the application is authorized to act on
+ behalf of, then that principal shall be used, otherwise
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 8]
+
+RFC 2743 GSS-API January 2000
+
+
+ (ii) If the platform maintains a concept of a default network-
+ identity, and if the application is authorized to act on behalf
+ of that identity for the purpose of initiating security
+ contexts, then the principal corresponding to that identity
+ shall be used, otherwise
+
+ (iii) If the platform maintains a concept of a default local
+ identity, and provides a means to map local identities into
+ network-identities, and if the application is authorized to act
+ on behalf of the network-identity image of the default local
+ identity for the purpose of initiating security contexts, then
+ the principal corresponding to that identity shall be used,
+ otherwise
+
+ (iv) A user-configurable default identity should be used.
+
+ GSS_Accept_sec_context:
+
+ (i) If there is only a single authorized principal identity
+ capable of accepting security contexts, then that principal
+ shall be used, otherwise
+
+ (ii) If the mechanism can determine the identity of the target
+ principal by examining the context-establishment token, and if
+ the accepting application is authorized to act as that
+ principal for the purpose of accepting security contexts, then
+ that principal identity shall be used, otherwise
+
+ (iii) If the mechanism supports context acceptance by any
+ principal, and mutual authentication was not requested, any
+ principal that the application is authorized to accept security
+ contexts under may be used, otherwise
+
+ (iv) A user-configurable default identity shall be used.
+
+ The purpose of the above rules is to allow security contexts to be
+ established by both initiator and acceptor using the default behavior
+ wherever possible. Applications requesting default behavior are
+ likely to be more portable across mechanisms and platforms than those
+ that use GSS_Acquire_cred() to request a specific identity.
+
+1.1.2: Tokens
+
+ Tokens are data elements transferred between GSS-API callers, and are
+ divided into two classes. Context-level tokens are exchanged in order
+ to establish and manage a security context between peers. Per-message
+ tokens relate to an established context and are exchanged to provide
+
+
+
+
+Linn Standards Track [Page 9]
+
+RFC 2743 GSS-API January 2000
+
+
+ protective security services (i.e., data origin authentication,
+ integrity, and optional confidentiality) for corresponding data
+ messages.
+
+ The first context-level token obtained from GSS_Init_sec_context() is
+ required to indicate at its very beginning a globally-interpretable
+ mechanism identifier, i.e., an Object Identifier (OID) of the
+ security mechanism. The remaining part of this token as well as the
+ whole content of all other tokens are specific to the particular
+ underlying mechanism used to support the GSS-API. Section 3.1 of this
+ document provides, for designers of GSS-API mechanisms, the
+ description of the header of the first context-level token which is
+ then followed by mechanism-specific information.
+
+ Tokens' contents are opaque from the viewpoint of GSS-API callers.
+ They are generated within the GSS-API implementation at an end
+ system, provided to a GSS-API caller to be transferred to the peer
+ GSS-API caller at a remote end system, and processed by the GSS-API
+ implementation at that remote end system.
+
+ Context-level tokens may be output by GSS-API calls (and should be
+ transferred to GSS-API peers) whether or not the calls' status
+ indicators indicate successful completion. Per-message tokens, in
+ contrast, are to be returned only upon successful completion of per-
+ message calls. Zero-length tokens are never returned by GSS routines
+ for transfer to a peer. Token transfer may take place in an in-band
+ manner, integrated into the same protocol stream used by the GSS-API
+ callers for other data transfers, or in an out-of-band manner across
+ a logically separate channel.
+
+ Different GSS-API tokens are used for different purposes (e.g.,
+ context initiation, context acceptance, protected message data on an
+ established context), and it is the responsibility of a GSS-API
+ caller receiving tokens to distinguish their types, associate them
+ with corresponding security contexts, and pass them to appropriate
+ GSS-API processing routines. Depending on the caller protocol
+ environment, this distinction may be accomplished in several ways.
+
+ The following examples illustrate means through which tokens' types
+ may be distinguished:
+
+ - implicit tagging based on state information (e.g., all tokens on
+ a new association are considered to be context establishment
+ tokens until context establishment is completed, at which point
+ all tokens are considered to be wrapped data objects for that
+ context),
+
+
+
+
+
+Linn Standards Track [Page 10]
+
+RFC 2743 GSS-API January 2000
+
+
+ - explicit tagging at the caller protocol level,
+
+ - a hybrid of these approaches.
+
+ Commonly, the encapsulated data within a token includes internal
+ mechanism-specific tagging information, enabling mechanism-level
+ processing modules to distinguish tokens used within the mechanism
+ for different purposes. Such internal mechanism-level tagging is
+ recommended to mechanism designers, and enables mechanisms to
+ determine whether a caller has passed a particular token for
+ processing by an inappropriate GSS-API routine.
+
+ Development of GSS-API mechanisms based on a particular underlying
+ cryptographic technique and protocol (i.e., conformant to a specific
+ GSS-API mechanism definition) does not necessarily imply that GSS-API
+ callers using that GSS-API mechanism will be able to interoperate
+ with peers invoking the same technique and protocol outside the GSS-
+ API paradigm, or with peers implementing a different GSS-API
+ mechanism based on the same underlying technology. The format of
+ GSS-API tokens defined in conjunction with a particular mechanism,
+ and the techniques used to integrate those tokens into callers'
+ protocols, may not be interoperable with the tokens used by non-GSS-
+ API callers of the same underlying technique.
+
+1.1.3: Security Contexts
+
+ Security contexts are established between peers, using credentials
+ established locally in conjunction with each peer or received by
+ peers via delegation. Multiple contexts may exist simultaneously
+ between a pair of peers, using the same or different sets of
+ credentials. Coexistence of multiple contexts using different
+ credentials allows graceful rollover when credentials expire.
+ Distinction among multiple contexts based on the same credentials
+ serves applications by distinguishing different message streams in a
+ security sense.
+
+ The GSS-API is independent of underlying protocols and addressing
+ structure, and depends on its callers to transport GSS-API-provided
+ data elements. As a result of these factors, it is a caller
+ responsibility to parse communicated messages, separating GSS-API-
+ related data elements from caller-provided data. The GSS-API is
+ independent of connection vs. connectionless orientation of the
+ underlying communications service.
+
+ No correlation between security context and communications protocol
+ association is dictated. (The optional channel binding facility,
+ discussed in Section 1.1.6 of this document, represents an
+ intentional exception to this rule, supporting additional protection
+
+
+
+Linn Standards Track [Page 11]
+
+RFC 2743 GSS-API January 2000
+
+
+ features within GSS-API supporting mechanisms.) This separation
+ allows the GSS-API to be used in a wide range of communications
+ environments, and also simplifies the calling sequences of the
+ individual calls. In many cases (depending on underlying security
+ protocol, associated mechanism, and availability of cached
+ information), the state information required for context setup can be
+ sent concurrently with initial signed user data, without interposing
+ additional message exchanges. Messages may be protected and
+ transferred in both directions on an established GSS-API security
+ context concurrently; protection of messages in one direction does
+ not interfere with protection of messages in the reverse direction.
+
+ GSS-API implementations are expected to retain inquirable context
+ data on a context until the context is released by a caller, even
+ after the context has expired, although underlying cryptographic data
+ elements may be deleted after expiration in order to limit their
+ exposure.
+
+1.1.4: Mechanism Types
+
+ In order to successfully establish a security context with a target
+ peer, it is necessary to identify an appropriate underlying mechanism
+ type (mech_type) which both initiator and target peers support. The
+ definition of a mechanism embodies not only the use of a particular
+ cryptographic technology (or a hybrid or choice among alternative
+ cryptographic technologies), but also definition of the syntax and
+ semantics of data element exchanges which that mechanism will employ
+ in order to support security services.
+
+ It is recommended that callers initiating contexts specify the
+ "default" mech_type value, allowing system-specific functions within
+ or invoked by the GSS-API implementation to select the appropriate
+ mech_type, but callers may direct that a particular mech_type be
+ employed when necessary.
+
+ For GSS-API purposes, the phrase "negotiating mechanism" refers to a
+ mechanism which itself performs negotiation in order to select a
+ concrete mechanism which is shared between peers and is then used for
+ context establishment. Only those mechanisms which are defined in
+ their specifications as negotiating mechanisms are to yield selected
+ mechanisms with different identifier values than the value which is
+ input by a GSS-API caller, except for the case of a caller requesting
+ the "default" mech_type.
+
+ The means for identifying a shared mech_type to establish a security
+ context with a peer will vary in different environments and
+ circumstances; examples include (but are not limited to):
+
+
+
+
+Linn Standards Track [Page 12]
+
+RFC 2743 GSS-API January 2000
+
+
+ use of a fixed mech_type, defined by configuration, within an
+ environment
+
+ syntactic convention on a target-specific basis, through
+ examination of a target's name lookup of a target's name in a
+ naming service or other database in order to identify mech_types
+ supported by that target
+
+ explicit negotiation between GSS-API callers in advance of
+ security context setup
+
+ use of a negotiating mechanism
+
+ When transferred between GSS-API peers, mech_type specifiers (per
+ Section 3 of this document, represented as Object Identifiers (OIDs))
+ serve to qualify the interpretation of associated tokens. (The
+ structure and encoding of Object Identifiers is defined in [ISOIEC-
+ 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs
+ serves to preclude ambiguous interpretation of mech_type specifiers.
+ The OID representing the DASS ([RFC-1507]) MechType, for example, is
+ 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC-
+ 1964]), having been advanced to the level of Proposed Standard, is
+ 1.2.840.113554.1.2.2.
+
+1.1.5: Naming
+
+ The GSS-API avoids prescribing naming structures, treating the names
+ which are transferred across the interface in order to initiate and
+ accept security contexts as opaque objects. This approach supports
+ the GSS-API's goal of implementability atop a range of underlying
+ security mechanisms, recognizing the fact that different mechanisms
+ process and authenticate names which are presented in different
+ forms. Generalized services offering translation functions among
+ arbitrary sets of naming environments are outside the scope of the
+ GSS-API; availability and use of local conversion functions to
+ translate among the naming formats supported within a given end
+ system is anticipated.
+
+ Different classes of name representations are used in conjunction
+ with different GSS-API parameters:
+
+ - Internal form (denoted in this document by INTERNAL NAME),
+ opaque to callers and defined by individual GSS-API
+ implementations. GSS-API implementations supporting multiple
+ namespace types must maintain internal tags to disambiguate the
+ interpretation of particular names. A Mechanism Name (MN) is a
+ special case of INTERNAL NAME, guaranteed to contain elements
+
+
+
+
+Linn Standards Track [Page 13]
+
+RFC 2743 GSS-API January 2000
+
+
+ corresponding to one and only one mechanism; calls which are
+ guaranteed to emit MNs or which require MNs as input are so
+ identified within this specification.
+
+ - Contiguous string ("flat") form (denoted in this document by
+ OCTET STRING); accompanied by OID tags identifying the namespace
+ to which they correspond. Depending on tag value, flat names may
+ or may not be printable strings for direct acceptance from and
+ presentation to users. Tagging of flat names allows GSS-API
+ callers and underlying GSS-API mechanisms to disambiguate name
+ types and to determine whether an associated name's type is one
+ which they are capable of processing, avoiding aliasing problems
+ which could result from misinterpreting a name of one type as a
+ name of another type.
+
+ - The GSS-API Exported Name Object, a special case of flat name
+ designated by a reserved OID value, carries a canonicalized form
+ of a name suitable for binary comparisons.
+
+ In addition to providing means for names to be tagged with types,
+ this specification defines primitives to support a level of naming
+ environment independence for certain calling applications. To provide
+ basic services oriented towards the requirements of callers which
+ need not themselves interpret the internal syntax and semantics of
+ names, GSS-API calls for name comparison (GSS_Compare_name()),
+ human-readable display (GSS_Display_name()), input conversion
+ (GSS_Import_name()), internal name deallocation (GSS_Release_name()),
+ and internal name duplication (GSS_Duplicate_name()) functions are
+ defined. (It is anticipated that these proposed GSS-API calls will be
+ implemented in many end systems based on system-specific name
+ manipulation primitives already extant within those end systems;
+ inclusion within the GSS-API is intended to offer GSS-API callers a
+ portable means to perform specific operations, supportive of
+ authorization and audit requirements, on authenticated names.)
+
+ GSS_Import_name() implementations can, where appropriate, support
+ more than one printable syntax corresponding to a given namespace
+ (e.g., alternative printable representations for X.500 Distinguished
+ Names), allowing flexibility for their callers to select among
+ alternative representations. GSS_Display_name() implementations
+ output a printable syntax selected as appropriate to their
+ operational environments; this selection is a local matter. Callers
+ desiring portability across alternative printable syntaxes should
+ refrain from implementing comparisons based on printable name forms
+ and should instead use the GSS_Compare_name() call to determine
+ whether or not one internal-format name matches another.
+
+
+
+
+
+Linn Standards Track [Page 14]
+
+RFC 2743 GSS-API January 2000
+
+
+ When used in large access control lists, the overhead of invoking
+ GSS_Import_name() and GSS_Compare_name() on each name from the ACL
+ may be prohibitive. As an alternative way of supporting this case,
+ GSS-API defines a special form of the contiguous string name which
+ may be compared directly (e.g., with memcmp()). Contiguous names
+ suitable for comparison are generated by the GSS_Export_name()
+ routine, which requires an MN as input. Exported names may be re-
+ imported by the GSS_Import_name() routine, and the resulting internal
+ name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME
+ identifies the "export name" type. Structurally, an exported name
+ object consists of a header containing an OID identifying the
+ mechanism that authenticated the name, and a trailer containing the
+ name itself, where the syntax of the trailer is defined by the
+ individual mechanism specification. The precise format of an
+ exported name is defined in Section 3.2 of this specification.
+
+ Note that the results obtained by using GSS_Compare_name() will in
+ general be different from those obtained by invoking
+ GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the
+ exported names. The first series of operations determines whether
+ two (unauthenticated) names identify the same principal; the second
+ whether a particular mechanism would authenticate them as the same
+ principal. These two operations will in general give the same
+ results only for MNs.
+
+ The following diagram illustrates the intended dataflow among name-
+ related GSS-API processing routines.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 15]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS-API library defaults
+ |
+ |
+ V text, for
+ text --------------> internal_name (IN) -----------> display only
+ import_name() / display_name()
+ /
+ /
+ /
+ accept_sec_context() /
+ | /
+ | /
+ | / canonicalize_name()
+ | /
+ | /
+ | /
+ | /
+ | /
+ | |
+ V V <---------------------
+ single mechanism import_name() exported name: flat
+ internal_name (MN) binary "blob" usable
+ ----------------------> for access control
+ export_name()
+
+1.1.6: Channel Bindings
+
+ The GSS-API accommodates the concept of caller-provided channel
+ binding ("chan_binding") information. Channel bindings are used to
+ strengthen the quality with which peer entity authentication is
+ provided during context establishment, by limiting the scope within
+ which an intercepted context establishment token can be reused by an
+ attacker. Specifically, they enable GSS-API callers to bind the
+ establishment of a security context to relevant characteristics
+ (e.g., addresses, transformed representations of encryption keys) of
+ the underlying communications channel, of protection mechanisms
+ applied to that communications channel, and to application-specific
+ data.
+
+ The caller initiating a security context must determine the
+ appropriate channel binding values to provide as input to the
+ GSS_Init_sec_context() call, and consistent values must be provided
+ to GSS_Accept_sec_context() by the context's target, in order for
+ both peers' GSS-API mechanisms to validate that received tokens
+ possess correct channel-related characteristics. Use or non-use of
+ the GSS-API channel binding facility is a caller option. GSS-API
+ mechanisms can operate in an environment where NULL channel bindings
+ are presented; mechanism implementors are encouraged, but not
+
+
+
+Linn Standards Track [Page 16]
+
+RFC 2743 GSS-API January 2000
+
+
+ required, to make use of caller-provided channel binding data within
+ their mechanisms. Callers should not assume that underlying
+ mechanisms provide confidentiality protection for channel binding
+ information.
+
+ When non-NULL channel bindings are provided by callers, certain
+ mechanisms can offer enhanced security value by interpreting the
+ bindings' content (rather than simply representing those bindings, or
+ integrity check values computed on them, within tokens) and will
+ therefore depend on presentation of specific data in a defined
+ format. To this end, agreements among mechanism implementors are
+ defining conventional interpretations for the contents of channel
+ binding arguments, including address specifiers (with content
+ dependent on communications protocol environment) for context
+ initiators and acceptors. (These conventions are being incorporated
+ in GSS-API mechanism specifications and into the GSS-API C language
+ bindings specification.) In order for GSS-API callers to be portable
+ across multiple mechanisms and achieve the full security
+ functionality which each mechanism can provide, it is strongly
+ recommended that GSS-API callers provide channel bindings consistent
+ with these conventions and those of the networking environment in
+ which they operate.
+
+1.2: GSS-API Features and Issues
+
+ This section describes aspects of GSS-API operations, of the security
+ services which the GSS-API provides, and provides commentary on
+ design issues.
+
+1.2.1: Status Reporting and Optional Service Support
+
+1.2.1.1: Status Reporting
+
+ Each GSS-API call provides two status return values. Major_status
+ values provide a mechanism-independent indication of call status
+ (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED),
+ sufficient to drive normal control flow within the caller in a
+ generic fashion. Table 1 summarizes the defined major_status return
+ codes in tabular fashion.
+
+ Sequencing-related informatory major_status codes
+ (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
+ GSS_S_GAP_TOKEN) can be indicated in conjunction with either
+ GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls.
+ For context establishment calls, these sequencing-related codes will
+ be indicated only in conjunction with GSS_S_FAILURE status (never in
+
+
+
+
+
+Linn Standards Track [Page 17]
+
+RFC 2743 GSS-API January 2000
+
+
+ conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and,
+ therefore, always correspond to fatal failures if encountered during
+ the context establishment phase.
+
+ Table 1: GSS-API Major Status Codes
+
+ FATAL ERROR CODES
+
+ GSS_S_BAD_BINDINGS channel binding mismatch
+ GSS_S_BAD_MECH unsupported mechanism requested
+ GSS_S_BAD_NAME invalid name provided
+ GSS_S_BAD_NAMETYPE name of unsupported type provided
+ GSS_S_BAD_STATUS invalid input status selector
+ GSS_S_BAD_SIG token had invalid integrity check
+ GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG
+ GSS_S_CONTEXT_EXPIRED specified security context expired
+ GSS_S_CREDENTIALS_EXPIRED expired credentials detected
+ GSS_S_DEFECTIVE_CREDENTIAL defective credential detected
+ GSS_S_DEFECTIVE_TOKEN defective token detected
+ GSS_S_FAILURE failure, unspecified at GSS-API
+ level
+ GSS_S_NO_CONTEXT no valid security context specified
+ GSS_S_NO_CRED no valid credentials provided
+ GSS_S_BAD_QOP unsupported QOP value
+ GSS_S_UNAUTHORIZED operation unauthorized
+ GSS_S_UNAVAILABLE operation unavailable
+ GSS_S_DUPLICATE_ELEMENT duplicate credential element requested
+ GSS_S_NAME_NOT_MN name contains multi-mechanism elements
+
+ INFORMATORY STATUS CODES
+
+ GSS_S_COMPLETE normal completion
+ GSS_S_CONTINUE_NEEDED continuation call to routine
+ required
+ GSS_S_DUPLICATE_TOKEN duplicate per-message token
+ detected
+ GSS_S_OLD_TOKEN timed-out per-message token
+ detected
+ GSS_S_UNSEQ_TOKEN reordered (early) per-message token
+ detected
+ GSS_S_GAP_TOKEN skipped predecessor token(s)
+ detected
+
+ Minor_status provides more detailed status information which may
+ include status codes specific to the underlying security mechanism.
+ Minor_status values are not specified in this document.
+
+
+
+
+
+Linn Standards Track [Page 18]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_S_CONTINUE_NEEDED major_status returns, and optional message
+ outputs, are provided in GSS_Init_sec_context() and
+ GSS_Accept_sec_context() calls so that different mechanisms'
+ employment of different numbers of messages within their
+ authentication sequences need not be reflected in separate code paths
+ within calling applications. Instead, such cases are accommodated
+ with sequences of continuation calls to GSS_Init_sec_context() and
+ GSS_Accept_sec_context(). The same facility is used to encapsulate
+ mutual authentication within the GSS-API's context initiation calls.
+
+ For mech_types which require interactions with third-party servers in
+ order to establish a security context, GSS-API context establishment
+ calls may block pending completion of such third-party interactions.
+ On the other hand, no GSS-API calls pend on serialized interactions
+ with GSS-API peer entities. As a result, local GSS-API status
+ returns cannot reflect unpredictable or asynchronous exceptions
+ occurring at remote peers, and reflection of such status information
+ is a caller responsibility outside the GSS-API.
+
+1.2.1.2: Optional Service Support
+
+ A context initiator may request various optional services at context
+ establishment time. Each of these services is requested by setting a
+ flag in the req_flags input parameter to GSS_Init_sec_context().
+
+ The optional services currently defined are:
+
+ - Delegation - The (usually temporary) transfer of rights from
+ initiator to acceptor, enabling the acceptor to authenticate
+ itself as an agent of the initiator.
+
+ - Mutual Authentication - In addition to the initiator
+ authenticating its identity to the context acceptor, the context
+ acceptor should also authenticate itself to the initiator.
+
+ - Replay detection - In addition to providing message integrity
+ services, GSS_GetMIC() and GSS_Wrap() should include message
+ numbering information to enable GSS_VerifyMIC() and GSS_Unwrap()
+ to detect if a message has been duplicated.
+
+ - Out-of-sequence detection - In addition to providing message
+ integrity services, GSS_GetMIC() and GSS_Wrap() should include
+ message sequencing information to enable GSS_VerifyMIC() and
+ GSS_Unwrap() to detect if a message has been received out of
+ sequence.
+
+
+
+
+
+
+Linn Standards Track [Page 19]
+
+RFC 2743 GSS-API January 2000
+
+
+ - Anonymous authentication - The establishment of the security
+ context should not reveal the initiator's identity to the context
+ acceptor.
+
+ - Available per-message confidentiality - requests that per-
+ message confidentiality services be available on the context.
+
+ - Available per-message integrity - requests that per-message
+ integrity services be available on the context.
+
+ Any currently undefined bits within such flag arguments should be
+ ignored by GSS-API implementations when presented by an application,
+ and should be set to zero when returned to the application by the
+ GSS-API implementation.
+
+ Some mechanisms may not support all optional services, and some
+ mechanisms may only support some services in conjunction with others.
+ Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the
+ applications which services will be available from the context when
+ the establishment phase is complete, via the ret_flags output
+ parameter. In general, if the security mechanism is capable of
+ providing a requested service, it should do so, even if additional
+ services must be enabled in order to provide the requested service.
+ If the mechanism is incapable of providing a requested service, it
+ should proceed without the service, leaving the application to abort
+ the context establishment process if it considers the requested
+ service to be mandatory.
+
+ Some mechanisms may specify that support for some services is
+ optional, and that implementors of the mechanism need not provide it.
+ This is most commonly true of the confidentiality service, often
+ because of legal restrictions on the use of data-encryption, but may
+ apply to any of the services. Such mechanisms are required to send
+ at least one token from acceptor to initiator during context
+ establishment when the initiator indicates a desire to use such a
+ service, so that the initiating GSS-API can correctly indicate
+ whether the service is supported by the acceptor's GSS-API.
+
+1.2.2: Per-Message Security Service Availability
+
+ When a context is established, two flags are returned to indicate the
+ set of per-message protection security services which will be
+ available on the context:
+
+ the integ_avail flag indicates whether per-message integrity and
+ data origin authentication services are available
+
+
+
+
+
+Linn Standards Track [Page 20]
+
+RFC 2743 GSS-API January 2000
+
+
+ the conf_avail flag indicates whether per-message confidentiality
+ services are available, and will never be returned TRUE unless the
+ integ_avail flag is also returned TRUE
+
+ GSS-API callers desiring per-message security services should check
+ the values of these flags at context establishment time, and must be
+ aware that a returned FALSE value for integ_avail means that
+ invocation of GSS_GetMIC() or GSS_Wrap() primitives on the associated
+ context will apply no cryptographic protection to user data messages.
+
+ The GSS-API per-message integrity and data origin authentication
+ services provide assurance to a receiving caller that protection was
+ applied to a message by the caller's peer on the security context,
+ corresponding to the entity named at context initiation. The GSS-API
+ per-message confidentiality service provides assurance to a sending
+ caller that the message's content is protected from access by
+ entities other than the context's named peer.
+
+ The GSS-API per-message protection service primitives, as the
+ category name implies, are oriented to operation at the granularity
+ of protocol data units. They perform cryptographic operations on the
+ data units, transfer cryptographic control information in tokens,
+ and, in the case of GSS_Wrap(), encapsulate the protected data unit.
+ As such, these primitives are not oriented to efficient data
+ protection for stream-paradigm protocols (e.g., Telnet) if
+ cryptography must be applied on an octet-by-octet basis.
+
+1.2.3: Per-Message Replay Detection and Sequencing
+
+ Certain underlying mech_types offer support for replay detection
+ and/or sequencing of messages transferred on the contexts they
+ support. These optionally-selectable protection features are distinct
+ from replay detection and sequencing features applied to the context
+ establishment operation itself; the presence or absence of context-
+ level replay or sequencing features is wholly a function of the
+ underlying mech_type's capabilities, and is not selected or omitted
+ as a caller option.
+
+ The caller initiating a context provides flags (replay_det_req_flag
+ and sequence_req_flag) to specify whether the use of per-message
+ replay detection and sequencing features is desired on the context
+ being established. The GSS-API implementation at the initiator system
+ can determine whether these features are supported (and whether they
+ are optionally selectable) as a function of the selected mechanism,
+ without need for bilateral negotiation with the target. When enabled,
+ these features provide recipients with indicators as a result of
+ GSS-API processing of incoming messages, identifying whether those
+ messages were detected as duplicates or out-of-sequence. Detection of
+
+
+
+Linn Standards Track [Page 21]
+
+RFC 2743 GSS-API January 2000
+
+
+ such events does not prevent a suspect message from being provided to
+ a recipient; the appropriate course of action on a suspect message is
+ a matter of caller policy.
+
+ The semantics of the replay detection and sequencing services applied
+ to received messages, as visible across the interface which the GSS-
+ API provides to its clients, are as follows:
+
+ When replay_det_state is TRUE, the possible major_status returns for
+ well-formed and correctly signed messages are as follows:
+
+ 1. GSS_S_COMPLETE, without concurrent indication of
+ GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the
+ message was within the window (of time or sequence space) allowing
+ replay events to be detected, and that the message was not a
+ replay of a previously-processed message within that window.
+
+ 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic
+ checkvalue on the received message was correct, but that the
+ message was recognized as a duplicate of a previously-processed
+ message. In addition to identifying duplicated tokens originated
+ by a context's peer, this status may also be used to identify
+ reflected copies of locally-generated tokens; it is recommended
+ that mechanism designers include within their protocols facilities
+ to detect and report such tokens.
+
+ 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on
+ the received message was correct, but that the message is too old
+ to be checked for duplication.
+
+ When sequence_state is TRUE, the possible major_status returns for
+ well-formed and correctly signed messages are as follows:
+
+ 1. GSS_S_COMPLETE, without concurrent indication of
+ GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or
+ GSS_S_GAP_TOKEN, indicates that the message was within the window
+ (of time or sequence space) allowing replay events to be detected,
+ that the message was not a replay of a previously-processed
+ message within that window, and that no predecessor sequenced
+ messages are missing relative to the last received message (if
+ any) processed on the context with a correct cryptographic
+ checkvalue.
+
+ 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value
+ on the received message was correct, but that the message was
+ recognized as a duplicate of a previously-processed message. In
+ addition to identifying duplicated tokens originated by a
+ context's peer, this status may also be used to identify reflected
+
+
+
+Linn Standards Track [Page 22]
+
+RFC 2743 GSS-API January 2000
+
+
+ copies of locally-generated tokens; it is recommended that
+ mechanism designers include within their protocols facilities to
+ detect and report such tokens.
+
+ 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the
+ received message was correct, but that the token is too old to be
+ checked for duplication.
+
+ 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue
+ on the received message was correct, but that it is earlier in a
+ sequenced stream than a message already processed on the context.
+ [Note: Mechanisms can be architected to provide a stricter form of
+ sequencing service, delivering particular messages to recipients
+ only after all predecessor messages in an ordered stream have been
+ delivered. This type of support is incompatible with the GSS-API
+ paradigm in which recipients receive all messages, whether in
+ order or not, and provide them (one at a time, without intra-GSS-
+ API message buffering) to GSS-API routines for validation. GSS-
+ API facilities provide supportive functions, aiding clients to
+ achieve strict message stream integrity in an efficient manner in
+ conjunction with sequencing provisions in communications
+ protocols, but the GSS-API does not offer this level of message
+ stream integrity service by itself.]
+
+ 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on
+ the received message was correct, but that one or more predecessor
+ sequenced messages have not been successfully processed relative
+ to the last received message (if any) processed on the context
+ with a correct cryptographic checkvalue.
+
+ As the message stream integrity features (especially sequencing) may
+ interfere with certain applications' intended communications
+ paradigms, and since support for such features is likely to be
+ resource intensive, it is highly recommended that mech_types
+ supporting these features allow them to be activated selectively on
+ initiator request when a context is established. A context initiator
+ and target are provided with corresponding indicators
+ (replay_det_state and sequence_state), signifying whether these
+ features are active on a given context.
+
+ An example mech_type supporting per-message replay detection could
+ (when replay_det_state is TRUE) implement the feature as follows: The
+ underlying mechanism would insert timestamps in data elements output
+ by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time-
+ limited window) a cache (qualified by originator-recipient pair)
+ identifying received data elements processed by GSS_VerifyMIC() and
+ GSS_Unwrap(). When this feature is active, exception status returns
+ (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when
+
+
+
+Linn Standards Track [Page 23]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is
+ either a detected duplicate of a prior message or which is too old to
+ validate against a cache of recently received messages.
+
+1.2.4: Quality of Protection
+
+ Some mech_types provide their users with fine granularity control
+ over the means used to provide per-message protection, allowing
+ callers to trade off security processing overhead dynamically against
+ the protection requirements of particular messages. A per-message
+ quality-of-protection parameter (analogous to quality-of-service, or
+ QOS) selects among different QOP options supported by that mechanism.
+ On context establishment for a multi-QOP mech_type, context-level
+ data provides the prerequisite data for a range of protection
+ qualities.
+
+ It is expected that the majority of callers will not wish to exert
+ explicit mechanism-specific QOP control and will therefore request
+ selection of a default QOP. Definitions of, and choices among, non-
+ default QOP values are mechanism-specific, and no ordered sequences
+ of QOP values can be assumed equivalent across different mechanisms.
+ Meaningful use of non-default QOP values demands that callers be
+ familiar with the QOP definitions of an underlying mechanism or
+ mechanisms, and is therefore a non-portable construct. The
+ GSS_S_BAD_QOP major_status value is defined in order to indicate that
+ a provided QOP value is unsupported for a security context, most
+ likely because that value is unrecognized by the underlying
+ mechanism.
+
+ In the interests of interoperability, mechanisms which allow optional
+ support of particular QOP values shall satisfy one of the following
+ conditions. Either:
+
+ (i) All implementations of the mechanism are required to be
+ capable of processing messages protected using any QOP value,
+ regardless of whether they can apply protection corresponding to
+ that QOP, or
+
+ (ii) The set of mutually-supported receiver QOP values must be
+ determined during context establishment, and messages may be
+ protected by either peer using only QOP values from this
+ mutually-supported set.
+
+ NOTE: (i) is just a special-case of (ii), where implementations are
+ required to support all QOP values on receipt.
+
+
+
+
+
+
+Linn Standards Track [Page 24]
+
+RFC 2743 GSS-API January 2000
+
+
+1.2.5: Anonymity Support
+
+ In certain situations or environments, an application may wish to
+ authenticate a peer and/or protect communications using GSS-API per-
+ message services without revealing its own identity. For example,
+ consider an application which provides read access to a research
+ database, and which permits queries by arbitrary requestors. A
+ client of such a service might wish to authenticate the service, to
+ establish trust in the information received from it, but might not
+ wish to disclose its identity to the service for privacy reasons.
+
+ In ordinary GSS-API usage, a context initiator's identity is made
+ available to the context acceptor as part of the context
+ establishment process. To provide for anonymity support, a facility
+ (input anon_req_flag to GSS_Init_sec_context()) is provided through
+ which context initiators may request that their identity not be
+ provided to the context acceptor. Mechanisms are not required to
+ honor this request, but a caller will be informed (via returned
+ anon_state indicator from GSS_Init_sec_context()) whether or not the
+ request is honored. Note that authentication as the anonymous
+ principal does not necessarily imply that credentials are not
+ required in order to establish a context.
+
+ Section 4.5 of this document defines the Object Identifier value used
+ to identify an anonymous principal.
+
+ Four possible combinations of anon_state and mutual_state are
+ possible, with the following results:
+
+ anon_state == FALSE, mutual_state == FALSE: initiator
+ authenticated to target.
+
+ anon_state == FALSE, mutual_state == TRUE: initiator authenticated
+ to target, target authenticated to initiator.
+
+ anon_state == TRUE, mutual_state == FALSE: initiator authenticated
+ as anonymous principal to target.
+
+ anon_state == TRUE, mutual_state == TRUE: initiator authenticated
+ as anonymous principal to target, target authenticated to
+ initiator.
+
+1.2.6: Initialization
+
+ No initialization calls (i.e., calls which must be invoked prior to
+ invocation of other facilities in the interface) are defined in GSS-
+ API. As an implication of this fact, GSS-API implementations must
+ themselves be self-initializing.
+
+
+
+Linn Standards Track [Page 25]
+
+RFC 2743 GSS-API January 2000
+
+
+1.2.7: Per-Message Protection During Context Establishment
+
+ A facility is defined in GSS-V2 to enable protection and buffering of
+ data messages for later transfer while a security context's
+ establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases
+ where the caller side already possesses the necessary session key to
+ enable this processing. Specifically, a new state Boolean, called
+ prot_ready_state, is added to the set of information returned by
+ GSS_Init_sec_context(), GSS_Accept_sec_context(), and
+ GSS_Inquire_context().
+
+ For context establishment calls, this state Boolean is valid and
+ interpretable when the associated major_status is either
+ GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both
+ initiators and acceptors) can assume that per-message protection (via
+ GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is
+ available and ready for use if either: prot_ready_state == TRUE, or
+ major_status == GSS_S_COMPLETE, though mutual authentication (if
+ requested) cannot be guaranteed until GSS_S_COMPLETE is returned.
+ Callers making use of per-message protection services in advance of
+ GSS_S_COMPLETE status should be aware of the possibility that a
+ subsequent context establishment step may fail, and that certain
+ context data (e.g., mech_type) as returned for subsequent calls may
+ change.
+
+ This approach achieves full, transparent backward compatibility for
+ GSS-API V1 callers, who need not even know of the existence of
+ prot_ready_state, and who will get the expected behavior from
+ GSS_S_COMPLETE, but who will not be able to use per-message
+ protection before GSS_S_COMPLETE is returned.
+
+ It is not a requirement that GSS-V2 mechanisms ever return TRUE
+ prot_ready_state before completion of context establishment (indeed,
+ some mechanisms will not evolve usable message protection keys,
+ especially at the context acceptor, before context establishment is
+ complete). It is expected but not required that GSS-V2 mechanisms
+ will return TRUE prot_ready_state upon completion of context
+ establishment if they support per-message protection at all (however
+ GSS-V2 applications should not assume that TRUE prot_ready_state will
+ always be returned together with the GSS_S_COMPLETE major_status,
+ since GSS-V2 implementations may continue to support GSS-V1 mechanism
+ code, which will never return TRUE prot_ready_state).
+
+ When prot_ready_state is returned TRUE, mechanisms shall also set
+ those context service indicator flags (deleg_state, mutual_state,
+ replay_det_state, sequence_state, anon_state, trans_state,
+ conf_avail, integ_avail) which represent facilities confirmed, at
+ that time, to be available on the context being established. In
+
+
+
+Linn Standards Track [Page 26]
+
+RFC 2743 GSS-API January 2000
+
+
+ situations where prot_ready_state is returned before GSS_S_COMPLETE,
+ it is possible that additional facilities may be confirmed and
+ subsequently indicated when GSS_S_COMPLETE is returned.
+
+1.2.8: Implementation Robustness
+
+ This section recommends aspects of GSS-API implementation behavior in
+ the interests of overall robustness.
+
+ Invocation of GSS-API calls is to incur no undocumented side effects
+ visible at the GSS-API level.
+
+ If a token is presented for processing on a GSS-API security context
+ and that token generates a fatal error in processing or is otherwise
+ determined to be invalid for that context, the context's state should
+ not be disrupted for purposes of processing subsequent valid tokens.
+
+ Certain local conditions at a GSS-API implementation (e.g.,
+ unavailability of memory) may preclude, temporarily or permanently,
+ the successful processing of tokens on a GSS-API security context,
+ typically generating GSS_S_FAILURE major_status returns along with
+ locally-significant minor_status. For robust operation under such
+ conditions, the following recommendations are made:
+
+ Failing calls should free any memory they allocate, so that
+ callers may retry without causing further loss of resources.
+
+ Failure of an individual call on an established context should not
+ preclude subsequent calls from succeeding on the same context.
+
+ Whenever possible, it should be possible for
+ GSS_Delete_sec_context() calls to be successfully processed even
+ if other calls cannot succeed, thereby enabling context-related
+ resources to be released.
+
+ A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an
+ unsupported QOP will not interfere with context validity, nor shall
+ such a failure impact the ability of the application to subsequently
+ invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state
+ information concerning sequencing of outgoing messages shall be
+ unchanged by an unsuccessful call of GSS_GetMIC() or GSS_Wrap().
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 27]
+
+RFC 2743 GSS-API January 2000
+
+
+1.2.9: Delegation
+
+ The GSS-API allows delegation to be controlled by the initiating
+ application via a Boolean parameter to GSS_Init_sec_context(), the
+ routine that establishes a security context. Some mechanisms do not
+ support delegation, and for such mechanisms attempts by an
+ application to enable delegation are ignored.
+
+ The acceptor of a security context for which the initiator enabled
+ delegation will receive (via the delegated_cred_handle parameter of
+ GSS_Accept_sec_context()) a credential handle that contains the
+ delegated identity, and this credential handle may be used to
+ initiate subsequent GSS-API security contexts as an agent or delegate
+ of the initiator. If the original initiator's identity is "A" and
+ the delegate's identity is "B", then, depending on the underlying
+ mechanism, the identity embodied by the delegated credential may be
+ either "A" or "B acting for A".
+
+ For many mechanisms that support delegation, a simple Boolean does
+ not provide enough control. Examples of additional aspects of
+ delegation control that a mechanism might provide to an application
+ are duration of delegation, network addresses from which delegation
+ is valid, and constraints on the tasks that may be performed by a
+ delegate. Such controls are presently outside the scope of the GSS-
+ API. GSS-API implementations supporting mechanisms offering
+ additional controls should provide extension routines that allow
+ these controls to be exercised (perhaps by modifying the initiator's
+ GSS-API credential prior to its use in establishing a context).
+ However, the simple delegation control provided by GSS-API should
+ always be able to over-ride other mechanism-specific delegation
+ controls; if the application instructs GSS_Init_sec_context() that
+ delegation is not desired, then the implementation must not permit
+ delegation to occur. This is an exception to the general rule that a
+ mechanism may enable services even if they are not requested;
+ delegation may only be provided at the explicit request of the
+ application.
+
+1.2.10: Interprocess Context Transfer
+
+ GSS-API V2 provides routines (GSS_Export_sec_context() and
+ GSS_Import_sec_context()) which allow a security context to be
+ transferred between processes on a single machine. The most common
+ use for such a feature is a client-server design where the server is
+ implemented as a single process that accepts incoming security
+ contexts, which then launches child processes to deal with the data
+ on these contexts. In such a design, the child processes must have
+ access to the security context data structure created within the
+
+
+
+
+Linn Standards Track [Page 28]
+
+RFC 2743 GSS-API January 2000
+
+
+ parent by its call to GSS_Accept_sec_context() so that they can use
+ per-message protection services and delete the security context when
+ the communication session ends.
+
+ Since the security context data structure is expected to contain
+ sequencing information, it is impractical in general to share a
+ context between processes. Thus GSS-API provides a call
+ (GSS_Export_sec_context()) that the process which currently owns the
+ context can call to declare that it has no intention to use the
+ context subsequently, and to create an inter-process token containing
+ information needed by the adopting process to successfully import the
+ context. After successful completion of this call, the original
+ security context is made inaccessible to the calling process by GSS-
+ API, and any context handles referring to this context are no longer
+ valid. The originating process transfers the inter-process token to
+ the adopting process, which passes it to GSS_Import_sec_context(),
+ and a fresh context handle is created such that it is functionally
+ identical to the original context.
+
+ The inter-process token may contain sensitive data from the original
+ security context (including cryptographic keys). Applications using
+ inter-process tokens to transfer security contexts must take
+ appropriate steps to protect these tokens in transit.
+ Implementations are not required to support the inter-process
+ transfer of security contexts. The ability to transfer a security
+ context is indicated when the context is created, by
+ GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE
+ trans_state return value.
+
+2: Interface Descriptions
+
+ This section describes the GSS-API's service interface, dividing the
+ set of calls offered into four groups. Credential management calls
+ are related to the acquisition and release of credentials by
+ principals. Context-level calls are related to the management of
+ security contexts between principals. Per-message calls are related
+ to the protection of individual messages on established security
+ contexts. Support calls provide ancillary functions useful to GSS-API
+ callers. Table 2 groups and summarizes the calls in tabular fashion.
+
+ Table 2: GSS-API Calls
+
+ CREDENTIAL MANAGEMENT
+
+ GSS_Acquire_cred acquire credentials for use
+ GSS_Release_cred release credentials after use
+ GSS_Inquire_cred display information about
+ credentials
+
+
+
+Linn Standards Track [Page 29]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_Add_cred construct credentials incrementally
+ GSS_Inquire_cred_by_mech display per-mechanism credential
+ information
+
+ CONTEXT-LEVEL CALLS
+
+ GSS_Init_sec_context initiate outbound security context
+ GSS_Accept_sec_context accept inbound security context
+ GSS_Delete_sec_context flush context when no longer needed
+ GSS_Process_context_token process received control token on
+ context
+ GSS_Context_time indicate validity time remaining on
+ context
+ GSS_Inquire_context display information about context
+ GSS_Wrap_size_limit determine GSS_Wrap token size limit
+ GSS_Export_sec_context transfer context to other process
+ GSS_Import_sec_context import transferred context
+
+ PER-MESSAGE CALLS
+
+ GSS_GetMIC apply integrity check, receive as
+ token separate from message
+ GSS_VerifyMIC validate integrity check token
+ along with message
+ GSS_Wrap sign, optionally encrypt,
+ encapsulate
+ GSS_Unwrap decapsulate, decrypt if needed,
+ validate integrity check
+
+ SUPPORT CALLS
+
+ GSS_Display_status translate status codes to printable
+ form
+ GSS_Indicate_mechs indicate mech_types supported on
+ local system
+ GSS_Compare_name compare two names for equality
+ GSS_Display_name translate name to printable form
+ GSS_Import_name convert printable name to
+ normalized form
+ GSS_Release_name free storage of normalized-form
+ name
+ GSS_Release_buffer free storage of general GSS-allocated
+ object
+ GSS_Release_OID_set free storage of OID set object
+ GSS_Create_empty_OID_set create empty OID set
+ GSS_Add_OID_set_member add member to OID set
+ GSS_Test_OID_set_member test if OID is member of OID set
+ GSS_Inquire_names_for_mech indicate name types supported by
+
+
+
+Linn Standards Track [Page 30]
+
+RFC 2743 GSS-API January 2000
+
+
+ mechanism
+ GSS_Inquire_mechs_for_name indicates mechanisms supporting name
+ type
+ GSS_Canonicalize_name translate name to per-mechanism form
+ GSS_Export_name externalize per-mechanism name
+ GSS_Duplicate_name duplicate name object
+
+2.1: Credential management calls
+
+ These GSS-API calls provide functions related to the management of
+ credentials. Their characterization with regard to whether or not
+ they may block pending exchanges with other network entities (e.g.,
+ directories or authentication servers) depends in part on OS-specific
+ (extra-GSS-API) issues, so is not specified in this document.
+
+ The GSS_Acquire_cred() call is defined within the GSS-API in support
+ of application portability, with a particular orientation towards
+ support of portable server applications. It is recognized that (for
+ certain systems and mechanisms) credentials for interactive users may
+ be managed differently from credentials for server processes; in such
+ environments, it is the GSS-API implementation's responsibility to
+ distinguish these cases and the procedures for making this
+ distinction are a local matter. The GSS_Release_cred() call provides
+ a means for callers to indicate to the GSS-API that use of a
+ credentials structure is no longer required. The GSS_Inquire_cred()
+ call allows callers to determine information about a credentials
+ structure. The GSS_Add_cred() call enables callers to append
+ elements to an existing credential structure, allowing iterative
+ construction of a multi-mechanism credential. The
+ GSS_Inquire_cred_by_mech() call enables callers to extract per-
+ mechanism information describing a credentials structure.
+
+2.1.1: GSS_Acquire_cred call
+
+ Inputs:
+
+ o desired_name INTERNAL NAME, -- NULL requests locally-determined
+ -- default
+
+ o lifetime_req INTEGER, -- in seconds; 0 requests default
+
+ o desired_mechs SET OF OBJECT IDENTIFIER, -- NULL requests
+ -- system-selected default
+
+ o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
+ -- 2=ACCEPT-ONLY
+
+
+
+
+
+Linn Standards Track [Page 31]
+
+RFC 2743 GSS-API January 2000
+
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL,
+ -- caller must release with GSS_Release_cred()
+
+ o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL,
+ -- caller must release with GSS_Release_oid_set()
+
+ o lifetime_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that requested credentials were
+ successfully established, for the duration indicated in lifetime_rec,
+ suitable for the usage requested in cred_usage, for the set of
+ mech_types indicated in actual_mechs, and that those credentials can
+ be referenced for subsequent use with the handle returned in
+ output_cred_handle.
+
+ o GSS_S_BAD_MECH indicates that a mech_type unsupported by the GSS-
+ API implementation type was requested, causing the credential
+ establishment operation to fail.
+
+ o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
+ uninterpretable or of a type unsupported by the applicable underlying
+ GSS-API mechanism(s), so no credentials could be established for the
+ accompanying desired_name.
+
+ o GSS_S_BAD_NAME indicates that the provided desired_name is
+ inconsistent in terms of internally-incorporated type specifier
+ information, so no credentials could be established for the
+ accompanying desired_name.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential
+ elements corresponding to the requested desired_name have expired, so
+ requested credentials could not be established.
+
+ o GSS_S_NO_CRED indicates that no credential elements corresponding
+ to the requested desired_name and usage could be accessed, so
+ requested credentials could not be established. In particular, this
+ status should be returned upon temporary user-fixable conditions
+
+
+
+
+
+Linn Standards Track [Page 32]
+
+RFC 2743 GSS-API January 2000
+
+
+ preventing successful credential establishment and upon lack of
+ authorization to establish and use credentials associated with the
+ identity named in the input desired_name argument.
+
+ o GSS_S_FAILURE indicates that credential establishment failed for
+ reasons unspecified at the GSS-API level.
+
+ GSS_Acquire_cred() is used to acquire credentials so that a principal
+ can (as a function of the input cred_usage parameter) initiate and/or
+ accept security contexts under the identity represented by the
+ desired_name input argument. On successful completion, the returned
+ output_cred_handle result provides a handle for subsequent references
+ to the acquired credentials. Typically, single-user client processes
+ requesting that default credential behavior be applied for context
+ establishment purposes will have no need to invoke this call.
+
+ A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
+ which will be interpreted as a request for a credential handle that
+ will invoke default behavior when passed to GSS_Init_sec_context(),
+ if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
+ GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
+ GSS_C_BOTH. It is possible that multiple pre-established credentials
+ may exist for the same principal identity (for example, as a result
+ of multiple user login sessions) when GSS_Acquire_cred() is called;
+ the means used in such cases to select a specific credential are
+ local matters. The input lifetime_req argument to GSS_Acquire_cred()
+ may provide useful information for local GSS-API implementations to
+ employ in making this disambiguation in a manner which will best
+ satisfy a caller's intent.
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways
+ of obtaining GSS-API initiator credentials from the system login
+ process. Some implementations may therefore not support the
+ acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
+ GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
+ resulting from applying GSS_Inquire_context() to an active context,
+ or a name resulting from applying GSS_Inquire_cred() against a
+ credential handle corresponding to default behavior. It is important
+ to recognize that the explicit name which is yielded by resolving a
+ default reference may change over time, e.g., as a result of local
+ credential element management operations outside GSS-API; once
+ resolved, however, the value of such an explicit name will remain
+ constant.
+
+ The lifetime_rec result indicates the length of time for which the
+ acquired credentials will be valid, as an offset from the present. A
+ mechanism may return a reserved value indicating INDEFINITE if no
+
+
+
+Linn Standards Track [Page 33]
+
+RFC 2743 GSS-API January 2000
+
+
+ constraints on credential lifetime are imposed. A caller of
+ GSS_Acquire_cred() can request a length of time for which acquired
+ credentials are to be valid (lifetime_req argument), beginning at the
+ present, or can request credentials with a default validity interval.
+ (Requests for postdated credentials are not supported within the
+ GSS-API.) Certain mechanisms and implementations may bind in
+ credential validity period specifiers at a point preliminary to
+ invocation of the GSS_Acquire_cred() call (e.g., in conjunction with
+ user login procedures). As a result, callers requesting non-default
+ values for lifetime_req must recognize that such requests cannot
+ always be honored and must be prepared to accommodate the use of
+ returned credentials with different lifetimes as indicated in
+ lifetime_rec.
+
+ The caller of GSS_Acquire_cred() can explicitly specify a set of
+ mech_types which are to be accommodated in the returned credentials
+ (desired_mechs argument), or can request credentials for a system-
+ defined default set of mech_types. Selection of the system-specified
+ default set is recommended in the interests of application
+ portability. The actual_mechs return value may be interrogated by the
+ caller to determine the set of mechanisms with which the returned
+ credentials may be used.
+
+2.1.2: GSS_Release_cred call
+
+ Input:
+
+ o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
+ -- is specified, the call will complete successfully, but
+ -- will have no effect; no credential elements will be
+ -- released.
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the credentials referenced by the
+ input cred_handle were released for purposes of subsequent access by
+ the caller. The effect on other processes which may be authorized
+ shared access to such credentials is a local matter.
+
+
+
+
+
+
+
+Linn Standards Track [Page 34]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_NO_CRED indicates that no release operation was performed,
+ either because the input cred_handle was invalid or because the
+ caller lacks authorization to access the referenced credentials.
+
+ o GSS_S_FAILURE indicates that the release operation failed for
+ reasons unspecified at the GSS-API level.
+
+ Provides a means for a caller to explicitly request that credentials
+ be released when their use is no longer required. Note that system-
+ specific credential management functions are also likely to exist,
+ for example to assure that credentials shared among processes are
+ properly deleted when all affected processes terminate, even if no
+ explicit release requests are issued by those processes. Given the
+ fact that multiple callers are not precluded from gaining authorized
+ access to the same credentials, invocation of GSS_Release_cred()
+ cannot be assumed to delete a particular set of credentials on a
+ system-wide basis.
+
+2.1.3: GSS_Inquire_cred call
+
+ Input:
+
+ o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
+ -- is specified, default initiator credentials are queried
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o cred_name INTERNAL NAME, -- caller must release with
+ -- GSS_Release_name()
+
+ o lifetime_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
+ -- 2=ACCEPT-ONLY
+
+ o mech_set SET OF OBJECT IDENTIFIER -- caller must release
+ -- with GSS_Release_oid_set()
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 35]
+
+RFC 2743 GSS-API January 2000
+
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the credentials referenced by the
+ input cred_handle argument were valid, and that the output cred_name,
+ lifetime_rec, and cred_usage values represent, respectively, the
+ credentials' associated principal name, remaining lifetime, suitable
+ usage modes, and supported mechanism types.
+
+ o GSS_S_NO_CRED indicates that no information could be returned
+ about the referenced credentials, either because the input
+ cred_handle was invalid or because the caller lacks authorization to
+ access the referenced credentials.
+
+ o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
+ credentials are invalid.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
+ credentials have expired.
+
+ o GSS_S_FAILURE indicates that the operation failed for reasons
+ unspecified at the GSS-API level.
+
+ The GSS_Inquire_cred() call is defined primarily for the use of those
+ callers which request use of default credential behavior rather than
+ acquiring credentials explicitly with GSS_Acquire_cred(). It enables
+ callers to determine a credential structure's associated principal
+ name, remaining validity period, usability for security context
+ initiation and/or acceptance, and supported mechanisms.
+
+ For a multi-mechanism credential, the returned "lifetime" specifier
+ indicates the shortest lifetime of any of the mechanisms' elements in
+ the credential (for either context initiation or acceptance
+ purposes).
+
+ GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for
+ "cred_usage" if both of the following conditions hold:
+
+ (1) there exists in the credential an element which allows context
+ initiation using some mechanism
+
+ (2) there exists in the credential an element which allows context
+ acceptance using some mechanism (allowably, but not necessarily,
+ one of the same mechanism(s) qualifying for (1)).
+
+ If condition (1) holds but not condition (2), GSS_Inquire_cred()
+ should indicate INITIATE-ONLY for "cred_usage". If condition (2)
+ holds but not condition (1), GSS_Inquire_cred() should indicate
+ ACCEPT-ONLY for "cred_usage".
+
+
+
+Linn Standards Track [Page 36]
+
+RFC 2743 GSS-API January 2000
+
+
+ Callers requiring finer disambiguation among available combinations
+ of lifetimes, usage modes, and mechanisms should call the
+ GSS_Inquire_cred_by_mech() routine, passing that routine one of the
+ mech OIDs returned by GSS_Inquire_cred().
+
+2.1.4: GSS_Add_cred call
+
+ Inputs:
+
+ o input_cred_handle CREDENTIAL HANDLE -- handle to credential
+ -- structure created with prior GSS_Acquire_cred() or
+ -- GSS_Add_cred() call; see text for definition of behavior
+ -- when GSS_C_NO_CREDENTIAL provided.
+
+ o desired_name INTERNAL NAME
+
+ o initiator_time_req INTEGER -- in seconds; 0 requests default
+
+ o acceptor_time_req INTEGER -- in seconds; 0 requests default
+
+ o desired_mech OBJECT IDENTIFIER
+
+ o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
+ -- 2=ACCEPT-ONLY
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that
+ -- credential elements be added "in place" to the credential
+ -- structure identified by input_cred_handle,
+ -- non-NULL pointer to request that
+ -- a new credential structure and handle be created.
+ -- if credential handle returned, caller must release with
+ -- GSS_Release_cred()
+
+ o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must
+ -- release with GSS_Release_oid_set()
+
+ o initiator_time_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ o acceptor_time_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+
+
+
+Linn Standards Track [Page 37]
+
+RFC 2743 GSS-API January 2000
+
+
+ o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
+ -- 2=ACCEPT-ONLY
+
+ o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms
+ -- supported by resulting credential.
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the credentials referenced by the
+ input_cred_handle argument were valid, and that the resulting
+ credential from GSS_Add_cred() is valid for the durations indicated
+ in initiator_time_rec and acceptor_time_rec, suitable for the usage
+ requested in cred_usage, and for the mechanisms indicated in
+ actual_mechs.
+
+ o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech
+ specified a mechanism for which the referenced credential already
+ contained a credential element with overlapping cred_usage and
+ validity time specifiers.
+
+ o GSS_S_BAD_MECH indicates that the input desired_mech specified a
+ mechanism unsupported by the GSS-API implementation, causing the
+ GSS_Add_cred() operation to fail.
+
+ o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
+ uninterpretable or of a type unsupported by the applicable underlying
+ GSS-API mechanism(s), so the GSS_Add_cred() operation could not be
+ performed for that name.
+
+ o GSS_S_BAD_NAME indicates that the provided desired_name is
+ inconsistent in terms of internally-incorporated type specifier
+ information, so the GSS_Add_cred() operation could not be performed
+ for that name.
+
+ o GSS_S_NO_CRED indicates that the input_cred_handle referenced
+ invalid or inaccessible credentials. In particular, this status
+ should be returned upon temporary user-fixable conditions preventing
+ successful credential establishment or upon lack of authorization to
+ establish or use credentials representing the requested identity.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential
+ elements have expired, so the GSS_Add_cred() operation could not be
+ performed.
+
+ o GSS_S_FAILURE indicates that the operation failed for reasons
+ unspecified at the GSS-API level.
+
+
+
+
+
+Linn Standards Track [Page 38]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_Add_cred() enables callers to construct credentials iteratively
+ by adding credential elements in successive operations, corresponding
+ to different mechanisms. This offers particular value in multi-
+ mechanism environments, as the major_status and minor_status values
+ returned on each iteration are individually visible and can therefore
+ be interpreted unambiguously on a per-mechanism basis. A credential
+ element is identified by the name of the principal to which it
+ refers. GSS-API implementations must impose a local access control
+ policy on callers of this routine to prevent unauthorized callers
+ from acquiring credential elements to which they are not entitled.
+ This routine is not intended to provide a "login to the network"
+ function, as such a function would involve the creation of new
+ mechanism-specific authentication data, rather than merely acquiring
+ a GSS-API handle to existing data. Such functions, if required,
+ should be defined in implementation-specific extension routines.
+
+ If credential acquisition is time-consuming for a mechanism, the
+ mechanism may choose to delay the actual acquisition until the
+ credential is required (e.g. by GSS_Init_sec_context() or
+ GSS_Accept_sec_context()). Such mechanism-specific implementation
+ decisions should be invisible to the calling application; thus a call
+ of GSS_Inquire_cred() immediately following the call of
+ GSS_Acquire_cred() must return valid credential data, and may
+ therefore incur the overhead of a deferred credential acquisition.
+
+ If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL
+ output_cred_handle must be supplied. For the case of
+ GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create
+ the credential referenced by its output_cred_handle based on default
+ behavior. That is, the call will have the same effect as if the
+ caller had previously called GSS_Acquire_cred(), specifying the same
+ usage and passing GSS_C_NO_NAME as the desired_name parameter
+ (thereby obtaining an explicit credential handle corresponding to
+ default behavior), had passed that credential handle to
+ GSS_Add_cred(), and had finally called GSS_Release_cred() on the
+ credential handle received from GSS_Acquire_cred().
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways
+ of obtaining GSS-API initiator credentials from the system login
+ process. Some implementations may therefore not support the
+ acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
+ GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
+ resulting from applying GSS_Inquire_context() to an active context,
+ or a name resulting from applying GSS_Inquire_cred() against a
+ credential handle corresponding to default behavior. It is important
+ to recognize that the explicit name which is yielded by resolving a
+ default reference may change over time, e.g., as a result of local
+
+
+
+Linn Standards Track [Page 39]
+
+RFC 2743 GSS-API January 2000
+
+
+ credential element management operations outside GSS-API; once
+ resolved, however, the value of such an explicit name will remain
+ constant.
+
+ A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
+ which will be interpreted as a request for a credential handle that
+ will invoke default behavior when passed to GSS_Init_sec_context(),
+ if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
+ GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
+ GSS_C_BOTH.
+
+ The same input desired_name, or default reference, should be used on
+ all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a
+ particular credential.
+
+2.1.5: GSS_Inquire_cred_by_mech call
+
+ Inputs:
+
+ o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
+ -- specified, default initiator credentials are queried
+
+ o mech_type OBJECT IDENTIFIER -- specific mechanism for
+ -- which credentials are being queried
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must
+ -- release with GSS_Release_name()
+
+ o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ o lifetime_rec_accept INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
+ -- 2=ACCEPT-ONLY
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the credentials referenced by the
+ input cred_handle argument were valid, that the mechanism indicated
+ by the input mech_type was represented with elements within those
+
+
+
+Linn Standards Track [Page 40]
+
+RFC 2743 GSS-API January 2000
+
+
+ credentials, and that the output cred_name, lifetime_rec_initiate,
+ lifetime_rec_accept, and cred_usage values represent, respectively,
+ the credentials' associated principal name, remaining lifetimes, and
+ suitable usage modes.
+
+ o GSS_S_NO_CRED indicates that no information could be returned
+ about the referenced credentials, either because the input
+ cred_handle was invalid or because the caller lacks authorization to
+ access the referenced credentials.
+
+ o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
+ credentials are invalid.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
+ credentials have expired.
+
+ o GSS_S_BAD_MECH indicates that the referenced credentials do not
+ contain elements for the requested mechanism.
+
+ o GSS_S_FAILURE indicates that the operation failed for reasons
+ unspecified at the GSS-API level.
+
+ The GSS_Inquire_cred_by_mech() call enables callers in multi-
+ mechanism environments to acquire specific data about available
+ combinations of lifetimes, usage modes, and mechanisms within a
+ credential structure. The lifetime_rec_initiate result indicates the
+ available lifetime for context initiation purposes; the
+ lifetime_rec_accept result indicates the available lifetime for
+ context acceptance purposes.
+
+2.2: Context-level calls
+
+ This group of calls is devoted to the establishment and management of
+ security contexts between peers. A context's initiator calls
+ GSS_Init_sec_context(), resulting in generation of a token which the
+ caller passes to the target. At the target, that token is passed to
+ GSS_Accept_sec_context(). Depending on the underlying mech_type and
+ specified options, additional token exchanges may be performed in the
+ course of context establishment; such exchanges are accommodated by
+ GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and
+ GSS_Accept_sec_context().
+
+ Either party to an established context may invoke
+ GSS_Delete_sec_context() to flush context information when a context
+ is no longer required. GSS_Process_context_token() is used to process
+ received tokens carrying context-level control information.
+ GSS_Context_time() allows a caller to determine the length of time
+ for which an established context will remain valid.
+
+
+
+Linn Standards Track [Page 41]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_Inquire_context() returns status information describing context
+ characteristics. GSS_Wrap_size_limit() allows a caller to determine
+ the size of a token which will be generated by a GSS_Wrap()
+ operation. GSS_Export_sec_context() and GSS_Import_sec_context()
+ enable transfer of active contexts between processes on an end
+ system.
+
+2.2.1: GSS_Init_sec_context call
+
+ Inputs:
+
+ o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use
+ -- default"
+
+ o input_context_handle CONTEXT HANDLE, -- 0
+ -- (GSS_C_NO_CONTEXT) specifies "none assigned yet"
+
+ o targ_name INTERNAL NAME,
+
+ o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use
+ -- default"
+
+ o deleg_req_flag BOOLEAN,
+
+ o mutual_req_flag BOOLEAN,
+
+ o replay_det_req_flag BOOLEAN,
+
+ o sequence_req_flag BOOLEAN,
+
+ o anon_req_flag BOOLEAN,
+
+ o conf_req_flag BOOLEAN,
+
+ o integ_req_flag BOOLEAN,
+
+ o lifetime_req INTEGER, -- 0 specifies default lifetime
+
+ o chan_bindings OCTET STRING,
+
+ o input_token OCTET STRING -- NULL or token received from target
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+
+
+
+Linn Standards Track [Page 42]
+
+RFC 2743 GSS-API January 2000
+
+
+ o output_context_handle CONTEXT HANDLE, -- once returned non-NULL,
+ -- caller must release with GSS_Delete_sec_context()
+
+ o mech_type OBJECT IDENTIFIER, -- actual mechanism always
+ -- indicated, never NULL; caller should treat as read-only
+ -- and should not attempt to release
+
+ o output_token OCTET STRING, -- NULL or token to pass to context
+ -- target; caller must release with GSS_Release_buffer()
+
+ o deleg_state BOOLEAN,
+
+ o mutual_state BOOLEAN,
+
+ o replay_det_state BOOLEAN,
+
+ o sequence_state BOOLEAN,
+
+ o anon_state BOOLEAN,
+
+ o trans_state BOOLEAN,
+
+ o prot_ready_state BOOLEAN, -- see Section 1.2.7
+
+ o conf_avail BOOLEAN,
+
+ o integ_avail BOOLEAN,
+
+ o lifetime_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ This call may block pending network interactions for those mech_types
+ in which an authentication server or other network entity must be
+ consulted on behalf of a context initiator in order to generate an
+ output_token suitable for presentation to a specified target.
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that context-level information was
+ successfully initialized, and that the returned output_token will
+ provide sufficient information for the target to perform per-message
+ processing on the newly-established context.
+
+ o GSS_S_CONTINUE_NEEDED indicates that control information in the
+ returned output_token must be sent to the target, and that a reply
+ must be received and passed as the input_token argument
+
+
+
+
+
+Linn Standards Track [Page 43]
+
+RFC 2743 GSS-API January 2000
+
+
+ to a continuation call to GSS_Init_sec_context(), before per-message
+ processing can be performed in conjunction with this context (unless
+ the prot_ready_state value is concurrently returned TRUE).
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
+ on the input_token failed, preventing further processing from being
+ performed based on that token.
+
+ o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
+ performed on the credential structure referenced by
+ claimant_cred_handle failed, preventing further processing from being
+ performed using that credential structure.
+
+ o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
+ input_token contains an incorrect integrity check, so context setup
+ cannot be accomplished.
+
+ o GSS_S_NO_CRED indicates that no context was established, either
+ because the input cred_handle was invalid, because the referenced
+ credentials are valid for context acceptor use only, because the
+ caller lacks authorization to access the referenced credentials, or
+ because the resolution of default credentials failed.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
+ through the input claimant_cred_handle argument are no longer valid,
+ so context establishment cannot be completed.
+
+ o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller-
+ provided chan_bindings and those extracted from the input_token was
+ detected, signifying a security-relevant event and preventing context
+ establishment. (This result will be returned by
+ GSS_Init_sec_context() only for contexts where mutual_state is TRUE.)
+
+ o GSS_S_OLD_TOKEN indicates that the input_token is too old to be
+ checked for integrity. This is a fatal error during context
+ establishment.
+
+ o GSS_S_DUPLICATE_TOKEN indicates that the input token has a correct
+ integrity check, but is a duplicate of a token already processed.
+ This is a fatal error during context establishment.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided; this major status will be
+ returned only for successor calls following GSS_S_CONTINUE_ NEEDED
+ status returns.
+
+
+
+
+
+
+Linn Standards Track [Page 44]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is of a
+ type uninterpretable or unsupported by the applicable underlying
+ GSS-API mechanism(s), so context establishment cannot be completed.
+
+ o GSS_S_BAD_NAME indicates that the provided targ_name is
+ inconsistent in terms of internally-incorporated type specifier
+ information, so context establishment cannot be accomplished.
+
+ o GSS_S_BAD_MECH indicates receipt of a context establishment token
+ or of a caller request specifying a mechanism unsupported by the
+ local system or with the caller's active credentials
+
+ o GSS_S_FAILURE indicates that context setup could not be
+ accomplished for reasons unspecified at the GSS-API level, and that
+ no interface-defined recovery action is available.
+
+ This routine is used by a context initiator, and ordinarily emits an
+ output_token suitable for use by the target within the selected
+ mech_type's protocol. For the case of a multi-step exchange, this
+ output_token will be one in a series, each generated by a successive
+ call. Using information in the credentials structure referenced by
+ claimant_cred_handle, GSS_Init_sec_context() initializes the data
+ structures required to establish a security context with target
+ targ_name.
+
+ The targ_name may be any valid INTERNAL NAME; it need not be an MN.
+ In addition to support for other name types, it is recommended (newly
+ as of GSS-V2, Update 1) that mechanisms be able to accept
+ GSS_C_NO_NAME as an input type for targ_name. While recommended,
+ such support is not required, and it is recognized that not all
+ mechanisms can construct tokens without explicitly naming the context
+ target, even when mutual authentication of the target is not
+ obtained. Callers wishing to make use of this facility and concerned
+ with portability should be aware that support for GSS_C_NO_NAME as
+ input targ_name type is unlikely to be provided within mechanism
+ definitions specified prior to GSS-V2, Update 1.
+
+ The claimant_cred_handle must correspond to the same valid
+ credentials structure on the initial call to GSS_Init_sec_context()
+ and on any successor calls resulting from GSS_S_CONTINUE_NEEDED
+ status returns; different protocol sequences modeled by the
+ GSS_S_CONTINUE_NEEDED facility will require access to credentials at
+ different points in the context establishment sequence.
+
+ The caller-provided input_context_handle argument is to be 0
+ (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first
+ GSS_Init_sec_context() call relating to a given context. If
+ successful (i.e., if accompanied by major_status GSS_S_COMPLETE or
+
+
+
+Linn Standards Track [Page 45]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_S_CONTINUE_NEEDED), and only if successful, the initial
+ GSS_Init_sec_context() call returns a non-zero output_context_handle
+ for use in future references to this context. Once a non-zero
+ output_context_handle has been returned, GSS-API callers should call
+ GSS_Delete_sec_context() to release context-related resources if
+ errors occur in later phases of context establishment, or when an
+ established context is no longer required. If GSS_Init_sec_context()
+ is passed the handle of a context which is already fully established,
+ GSS_S_FAILURE status is returned.
+
+ When continuation attempts to GSS_Init_sec_context() are needed to
+ perform context establishment, the previously-returned non-zero
+ handle value is entered into the input_context_handle argument and
+ will be echoed in the returned output_context_handle argument. On
+ such continuation attempts (and only on continuation attempts) the
+ input_token value is used, to provide the token returned from the
+ context's target.
+
+ The chan_bindings argument is used by the caller to provide
+ information binding the security context to security-related
+ characteristics (e.g., addresses, cryptographic keys) of the
+ underlying communications channel. See Section 1.1.6 of this document
+ for more discussion of this argument's usage.
+
+ The input_token argument contains a message received from the target,
+ and is significant only on a call to GSS_Init_sec_context() which
+ follows a previous return indicating GSS_S_CONTINUE_NEEDED
+ major_status.
+
+ It is the caller's responsibility to establish a communications path
+ to the target, and to transmit any returned output_token (independent
+ of the accompanying returned major_status value) to the target over
+ that path. The output_token can, however, be transmitted along with
+ the first application-provided input message to be processed by
+ GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully-
+ established context. (Note: when the GSS-V2 prot_ready_state
+ indicator is returned TRUE, it can be possible to transfer a
+ protected message before context establishment is complete: see also
+ Section 1.2.7)
+
+ The initiator may request various context-level functions through
+ input flags: the deleg_req_flag requests delegation of access rights,
+ the mutual_req_flag requests mutual authentication, the
+ replay_det_req_flag requests that replay detection features be
+ applied to messages transferred on the established context, and the
+ sequence_req_flag requests that sequencing be enforced. (See Section
+
+
+
+
+
+Linn Standards Track [Page 46]
+
+RFC 2743 GSS-API January 2000
+
+
+ 1.2.3 for more information on replay detection and sequencing
+ features.) The anon_req_flag requests that the initiator's identity
+ not be transferred within tokens to be sent to the acceptor.
+
+ The conf_req_flag and integ_req_flag provide informatory inputs to
+ the GSS-API implementation as to whether, respectively, per-message
+ confidentiality and per-message integrity services will be required
+ on the context. This information is important as an input to
+ negotiating mechanisms. It is important to recognize, however, that
+ the inclusion of these flags (which are newly defined for GSS-V2)
+ introduces a backward incompatibility with callers implemented to
+ GSS-V1, where the flags were not defined. Since no GSS-V1 callers
+ would set these flags, even if per-message services are desired,
+ GSS-V2 mechanism implementations which enable such services
+ selectively based on the flags' values may fail to provide them to
+ contexts established for GSS-V1 callers. It may be appropriate under
+ certain circumstances, therefore, for such mechanism implementations
+ to infer these service request flags to be set if a caller is known
+ to be implemented to GSS-V1.
+
+ Not all of the optionally-requestable features will be available in
+ all underlying mech_types. The corresponding return state values
+ deleg_state, mutual_state, replay_det_state, and sequence_state
+ indicate, as a function of mech_type processing capabilities and
+ initiator-provided input flags, the set of features which will be
+ active on the context. The returned trans_state value indicates
+ whether the context is transferable to other processes through use of
+ GSS_Export_sec_context(). These state indicators' values are
+ undefined unless either the routine's major_status indicates
+ GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with
+ GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is
+ possible that additional features, not confirmed or indicated along
+ with TRUE prot_ready_state, will be confirmed and indicated when
+ GSS_S_COMPLETE is subsequently returned.
+
+ The returned anon_state and prot_ready_state values are significant
+ for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status
+ returns from GSS_Init_sec_context(). When anon_state is returned
+ TRUE, this indicates that neither the current token nor its
+ predecessors delivers or has delivered the initiator's identity.
+ Callers wishing to perform context establishment only if anonymity
+ support is provided should transfer a returned token from
+ GSS_Init_sec_context() to the peer only if it is accompanied by a
+ TRUE anon_state indicator. When prot_ready_state is returned TRUE in
+ conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates
+ that per-message protection operations may be applied on the context:
+ see Section 1.2.7 for further discussion of this facility.
+
+
+
+
+Linn Standards Track [Page 47]
+
+RFC 2743 GSS-API January 2000
+
+
+ Failure to provide the precise set of features requested by the
+ caller does not cause context establishment to fail; it is the
+ caller's prerogative to delete the context if the feature set
+ provided is unsuitable for the caller's use.
+
+ The returned mech_type value indicates the specific mechanism
+ employed on the context; it will never indicate the value for
+ "default". A valid mech_type result must be returned along with a
+ GSS_S_COMPLETE status return; GSS-API implementations may (but are
+ not required to) also return mech_type along with predecessor calls
+ indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is
+ determinable) in conjunction with fatal error cases. For the case of
+ mechanisms which themselves perform negotiation, the returned
+ mech_type result may indicate selection of a mechanism identified by
+ an OID different than that passed in the input mech_type argument,
+ and the returned value may change between successive calls returning
+ GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE.
+
+ The conf_avail return value indicates whether the context supports
+ per-message confidentiality services, and so informs the caller
+ whether or not a request for encryption through the conf_req_flag
+ input to GSS_Wrap() can be honored. In similar fashion, the
+ integ_avail return value indicates whether per-message integrity
+ services are available (through either GSS_GetMIC() or GSS_Wrap()) on
+ the established context. These state indicators' values are undefined
+ unless either the routine's major_status indicates GSS_S_COMPLETE, or
+ TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED
+ major_status.
+
+ The lifetime_req input specifies a desired upper bound for the
+ lifetime of the context to be established, with a value of 0 used to
+ request a default lifetime. The lifetime_rec return value indicates
+ the length of time for which the context will be valid, expressed as
+ an offset from the present; depending on mechanism capabilities,
+ credential lifetimes, and local policy, it may not correspond to the
+ value requested in lifetime_req. If no constraints on context
+ lifetime are imposed, this may be indicated by returning a reserved
+ value representing INDEFINITE lifetime_req. The value of lifetime_rec
+ is undefined unless the routine's major_status indicates
+ GSS_S_COMPLETE.
+
+ If the mutual_state is TRUE, this fact will be reflected within the
+ output_token. A call to GSS_Accept_sec_context() at the target in
+ conjunction with such a context will return a token, to be processed
+ by a continuation call to GSS_Init_sec_context(), in order to achieve
+ mutual authentication.
+
+
+
+
+
+Linn Standards Track [Page 48]
+
+RFC 2743 GSS-API January 2000
+
+
+2.2.2: GSS_Accept_sec_context call
+
+ Inputs:
+
+ o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies
+ -- "use default"
+
+ o input_context_handle CONTEXT HANDLE, -- 0
+ -- (GSS_C_NO_CONTEXT) specifies "not yet assigned"
+
+ o chan_bindings OCTET STRING,
+
+ o input_token OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o src_name INTERNAL NAME, -- guaranteed to be MN
+ -- once returned, caller must release with GSS_Release_name()
+
+ o mech_type OBJECT IDENTIFIER, -- caller should treat as
+ -- read-only; does not need to be released
+
+ o output_context_handle CONTEXT HANDLE, -- once returned
+ -- non-NULL in context establishment sequence, caller
+ -- must release with GSS_Delete_sec_context()
+
+ o deleg_state BOOLEAN,
+
+ o mutual_state BOOLEAN,
+
+ o replay_det_state BOOLEAN,
+
+ o sequence_state BOOLEAN,
+
+ o anon_state BOOLEAN,
+
+ o trans_state BOOLEAN,
+
+ o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion
+
+ o conf_avail BOOLEAN,
+
+ o integ_avail BOOLEAN,
+
+
+
+
+Linn Standards Track [Page 49]
+
+RFC 2743 GSS-API January 2000
+
+
+ o lifetime_rec INTEGER, -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL,
+ -- caller must release with GSS_Release_cred()
+
+ o output_token OCTET STRING -- NULL or token to pass to context
+ -- initiator; if returned non-NULL, caller must release with
+ -- GSS_Release_buffer()
+
+ This call may block pending network interactions for those mech_types
+ in which a directory service or other network entity must be
+ consulted on behalf of a context acceptor in order to validate a
+ received input_token.
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that context-level data structures were
+ successfully initialized, and that per-message processing can now be
+ performed in conjunction with this context.
+
+ o GSS_S_CONTINUE_NEEDED indicates that control information in the
+ returned output_token must be sent to the initiator, and that a
+ response must be received and passed as the input_token argument to a
+ continuation call to GSS_Accept_sec_context(), before per-message
+ processing can be performed in conjunction with this context.
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
+ on the input_token failed, preventing further processing from being
+ performed based on that token.
+
+ o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
+ performed on the credential structure referenced by
+ acceptor_cred_handle failed, preventing further processing from being
+ performed using that credential structure.
+
+ o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
+ input_token contains an incorrect integrity check, so context setup
+ cannot be accomplished.
+
+ o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the
+ received input_token was correct, but that the input_token was
+ recognized as a duplicate of an input_token already processed. No new
+ context is established.
+
+
+
+
+
+
+
+Linn Standards Track [Page 50]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_OLD_TOKEN indicates that the integrity check on the received
+ input_token was correct, but that the input_token is too old to be
+ checked for duplication against previously-processed input_tokens. No
+ new context is established.
+
+ o GSS_S_NO_CRED indicates that no context was established, either
+ because the input cred_handle was invalid, because the referenced
+ credentials are valid for context initiator use only, because the
+ caller lacks authorization to access the referenced credentials, or
+ because the procedure for default credential resolution failed.
+
+ o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
+ through the input acceptor_cred_handle argument are no longer valid,
+ so context establishment cannot be completed.
+
+ o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller-
+ provided chan_bindings and those extracted from the input_token was
+ detected, signifying a security-relevant event and preventing context
+ establishment.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided; this major status will be
+ returned only for successor calls following GSS_S_CONTINUE_ NEEDED
+ status returns.
+
+ o GSS_S_BAD_MECH indicates receipt of a context establishment token
+ specifying a mechanism unsupported by the local system or with the
+ caller's active credentials.
+
+ o GSS_S_FAILURE indicates that context setup could not be
+ accomplished for reasons unspecified at the GSS-API level, and that
+ no interface-defined recovery action is available.
+
+ The GSS_Accept_sec_context() routine is used by a context target.
+ Using information in the credentials structure referenced by the
+ input acceptor_cred_handle, it verifies the incoming input_token and
+ (following the successful completion of a context establishment
+ sequence) returns the authenticated src_name and the mech_type used.
+ The returned src_name is guaranteed to be an MN, processed by the
+ mechanism under which the context was established. The
+ acceptor_cred_handle must correspond to the same valid credentials
+ structure on the initial call to GSS_Accept_sec_context() and on any
+ successor calls resulting from GSS_S_CONTINUE_NEEDED status returns;
+ different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED
+ mechanism will require access to credentials at different points in
+ the context establishment sequence.
+
+
+
+
+
+Linn Standards Track [Page 51]
+
+RFC 2743 GSS-API January 2000
+
+
+ The caller-provided input_context_handle argument is to be 0
+ (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first
+ GSS_Accept_sec_context() call relating to a given context. If
+ successful (i.e., if accompanied by major_status GSS_S_COMPLETE or
+ GSS_S_CONTINUE_NEEDED), and only if successful, the initial
+ GSS_Accept_sec_context() call returns a non-zero
+ output_context_handle for use in future references to this context.
+ Once a non-zero output_context_handle has been returned, GSS-API
+ callers should call GSS_Delete_sec_context() to release context-
+ related resources if errors occur in later phases of context
+ establishment, or when an established context is no longer required.
+ If GSS_Accept_sec_context() is passed the handle of a context which
+ is already fully established, GSS_S_FAILURE status is returned.
+
+ The chan_bindings argument is used by the caller to provide
+ information binding the security context to security-related
+ characteristics (e.g., addresses, cryptographic keys) of the
+ underlying communications channel. See Section 1.1.6 of this document
+ for more discussion of this argument's usage.
+
+ The returned state results (deleg_state, mutual_state,
+ replay_det_state, sequence_state, anon_state, trans_state, and
+ prot_ready_state) reflect the same information as described for
+ GSS_Init_sec_context(), and their values are significant under the
+ same return state conditions.
+
+ The conf_avail return value indicates whether the context supports
+ per-message confidentiality services, and so informs the caller
+ whether or not a request for encryption through the conf_req_flag
+ input to GSS_Wrap() can be honored. In similar fashion, the
+ integ_avail return value indicates whether per-message integrity
+ services are available (through either GSS_GetMIC() or GSS_Wrap())
+ on the established context. These values are significant under the
+ same return state conditions as described under
+ GSS_Init_sec_context().
+
+ The lifetime_rec return value is significant only in conjunction with
+ GSS_S_COMPLETE major_status, and indicates the length of time for
+ which the context will be valid, expressed as an offset from the
+ present.
+
+ The returned mech_type value indicates the specific mechanism
+ employed on the context; it will never indicate the value for
+ "default". A valid mech_type result must be returned whenever
+ GSS_S_COMPLETE status is indicated; GSS-API implementations may (but
+ are not required to) also return mech_type along with predecessor
+ calls indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is
+ determinable) in conjunction with fatal error cases. For the case of
+
+
+
+Linn Standards Track [Page 52]
+
+RFC 2743 GSS-API January 2000
+
+
+ mechanisms which themselves perform negotiation, the returned
+ mech_type result may indicate selection of a mechanism identified by
+ an OID different than that passed in the input mech_type argument,
+ and the returned value may change between successive calls returning
+ GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE.
+
+ The delegated_cred_handle result is significant only when deleg_state
+ is TRUE, and provides a means for the target to reference the
+ delegated credentials. The output_token result, when non-NULL,
+ provides a context-level token to be returned to the context
+ initiator to continue a multi-step context establishment sequence. As
+ noted with GSS_Init_sec_context(), any returned token should be
+ transferred to the context's peer (in this case, the context
+ initiator), independent of the value of the accompanying returned
+ major_status.
+
+ Note: A target must be able to distinguish a context-level
+ input_token, which is passed to GSS_Accept_sec_context(), from the
+ per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap().
+ These data elements may arrive in a single application message, and
+ GSS_Accept_sec_context() must be performed before per-message
+ processing can be performed successfully.
+
+2.2.3: GSS_Delete_sec_context call
+
+ Input:
+
+ o context_handle CONTEXT HANDLE
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o output_context_token OCTET STRING
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the context was recognized, and that
+ relevant context-specific information was flushed. If the caller
+ provides a non-null buffer to receive an output_context_token, and
+ the mechanism returns a non-NULL token into that buffer, the returned
+ output_context_token is ready for transfer to the context's peer.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided, so no deletion was performed.
+
+
+
+
+Linn Standards Track [Page 53]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the GSS_Delete_sec_context() operation could not be performed for
+ reasons unspecified at the GSS-API level.
+
+ This call can be made by either peer in a security context, to flush
+ context-specific information. Once a non-zero output_context_handle
+ has been returned by context establishment calls, GSS-API callers
+ should call GSS_Delete_sec_context() to release context-related
+ resources if errors occur in later phases of context establishment,
+ or when an established context is no longer required. This call may
+ block pending network interactions for mech_types in which active
+ notification must be made to a central server when a security context
+ is to be deleted.
+
+ If a non-null output_context_token parameter is provided by the
+ caller, an output_context_token may be returned to the caller. If an
+ output_context_token is provided to the caller, it can be passed to
+ the context's peer to inform the peer's GSS-API implementation that
+ the peer's corresponding context information can also be flushed.
+ (Once a context is established, the peers involved are expected to
+ retain cached credential and context-related information until the
+ information's expiration time is reached or until a
+ GSS_Delete_sec_context() call is made.)
+
+ The facility for context_token usage to signal context deletion is
+ retained for compatibility with GSS-API Version 1. For current
+ usage, it is recommended that both peers to a context invoke
+ GSS_Delete_sec_context() independently, passing a null
+ output_context_token buffer to indicate that no context_token is
+ required. Implementations of GSS_Delete_sec_context() should delete
+ relevant locally-stored context information.
+
+ Attempts to perform per-message processing on a deleted context will
+ result in error returns.
+
+2.2.4: GSS_Process_context_token call
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o input_context_token OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+
+
+Linn Standards Track [Page 54]
+
+RFC 2743 GSS-API January 2000
+
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the input_context_token was
+ successfully processed in conjunction with the context referenced by
+ context_handle.
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
+ on the received context_token failed, preventing further processing
+ from being performed with that token.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided.
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the GSS_Process_context_token() operation could not be performed for
+ reasons unspecified at the GSS-API level.
+
+ This call is used to process context_tokens received from a peer once
+ a context has been established, with corresponding impact on
+ context-level state information. One use for this facility is
+ processing of the context_tokens generated by
+ GSS_Delete_sec_context(); GSS_Process_context_token() will not block
+ pending network interactions for that purpose. Another use is to
+ process tokens indicating remote-peer context establishment failures
+ after the point where the local GSS-API implementation has already
+ indicated GSS_S_COMPLETE status.
+
+2.2.5: GSS_Context_time call
+
+ Input:
+
+ o context_handle CONTEXT HANDLE,
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o lifetime_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the referenced context is valid, and
+ will remain valid for the amount of time indicated in lifetime_rec.
+
+
+
+
+
+Linn Standards Track [Page 55]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_CONTEXT_EXPIRED indicates that data items related to the
+ referenced context have expired.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided.
+
+ o GSS_S_FAILURE indicates that the requested operation failed for
+ reasons unspecified at the GSS-API level.
+
+ This call is used to determine the amount of time for which a
+ currently established context will remain valid.
+
+2.2.6: GSS_Inquire_context call
+
+ Input:
+
+ o context_handle CONTEXT HANDLE,
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o src_name INTERNAL NAME, -- name of context initiator,
+ -- guaranteed to be MN;
+ -- caller must release with GSS_Release_name() if returned
+
+ o targ_name INTERNAL NAME, -- name of context target,
+ -- guaranteed to be MN;
+ -- caller must release with GSS_Release_name() if returned
+
+ o lifetime_rec INTEGER -- in seconds, or reserved value for
+ -- INDEFINITE or EXPIRED
+
+ o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this
+ -- security context; caller should treat as read-only and not
+ -- attempt to release
+
+ o deleg_state BOOLEAN,
+
+ o mutual_state BOOLEAN,
+
+ o replay_det_state BOOLEAN,
+
+ o sequence_state BOOLEAN,
+
+ o anon_state BOOLEAN,
+
+
+
+Linn Standards Track [Page 56]
+
+RFC 2743 GSS-API January 2000
+
+
+ o trans_state BOOLEAN,
+
+ o prot_ready_state BOOLEAN,
+
+ o conf_avail BOOLEAN,
+
+ o integ_avail BOOLEAN,
+
+ o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor
+
+ o open BOOLEAN, -- TRUE if context fully established, FALSE
+ -- if partly established (in CONTINUE_NEEDED state)
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the referenced context is valid and
+ that deleg_state, mutual_state, replay_det_state, sequence_state,
+ anon_state, trans_state, prot_ready_state, conf_avail, integ_avail,
+ locally_initiated, and open return values describe the corresponding
+ characteristics of the context. If open is TRUE, lifetime_rec is
+ also returned: if open is TRUE and the context peer's name is known,
+ src_name and targ_name are valid in addition to the values listed
+ above. The mech_type value must be returned for contexts where open
+ is TRUE and may be returned for contexts where open is FALSE.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided. Return values other than
+ major_status and minor_status are undefined.
+
+ o GSS_S_FAILURE indicates that the requested operation failed for
+ reasons unspecified at the GSS-API level. Return values other than
+ major_status and minor_status are undefined.
+
+ This call is used to extract information describing characteristics
+ of a security context. Note that GSS-API implementations are
+ expected to retain inquirable context data on a context until the
+ context is released by a caller, even after the context has expired,
+ although underlying cryptographic data elements may be deleted after
+ expiration in order to limit their exposure.
+
+2.2.7: GSS_Wrap_size_limit call
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o conf_req_flag BOOLEAN,
+
+
+
+
+Linn Standards Track [Page 57]
+
+RFC 2743 GSS-API January 2000
+
+
+ o qop INTEGER,
+
+ o output_size INTEGER
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o max_input_size INTEGER
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates a successful token size determination:
+ an input message with a length in octets equal to the returned
+ max_input_size value will, when passed to GSS_Wrap() for processing
+ on the context identified by the context_handle parameter with the
+ confidentiality request state as provided in conf_req_flag and with
+ the quality of protection specifier provided in the qop parameter,
+ yield an output token no larger than the value of the provided
+ output_size parameter.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that the provided input
+ context_handle is recognized, but that the referenced context has
+ expired. Return values other than major_status and minor_status are
+ undefined.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided. Return values other than
+ major_status and minor_status are undefined.
+
+ o GSS_S_BAD_QOP indicates that the provided QOP value is not
+ recognized or supported for the context.
+
+ o GSS_S_FAILURE indicates that the requested operation failed for
+ reasons unspecified at the GSS-API level. Return values other than
+ major_status and minor_status are undefined.
+
+ This call is used to determine the largest input datum which may be
+ passed to GSS_Wrap() without yielding an output token larger than a
+ caller-specified value.
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 58]
+
+RFC 2743 GSS-API January 2000
+
+
+2.2.8: GSS_Export_sec_context call
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o interprocess_token OCTET STRING -- caller must release
+ -- with GSS_Release_buffer()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the referenced context has been
+ successfully exported to a representation in the interprocess_token,
+ and is no longer available for use by the caller.
+
+ o GSS_S_UNAVAILABLE indicates that the context export facility is
+ not available for use on the referenced context. (This status should
+ occur only for contexts for which the trans_state value is FALSE.)
+ Return values other than major_status and minor_status are undefined.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that the provided input
+ context_handle is recognized, but that the referenced context has
+ expired. Return values other than major_status and minor_status are
+ undefined.
+
+ o GSS_S_NO_CONTEXT indicates that no valid context was recognized
+ for the input context_handle provided. Return values other than
+ major_status and minor_status are undefined.
+
+ o GSS_S_FAILURE indicates that the requested operation failed for
+ reasons unspecified at the GSS-API level. Return values other than
+ major_status and minor_status are undefined.
+
+ This call generates an interprocess token for transfer to another
+ process within an end system, in order to transfer control of a
+ security context to that process. The recipient of the interprocess
+ token will call GSS_Import_sec_context() to accept the transfer. The
+ GSS_Export_sec_context() operation is defined for use only with
+ security contexts which are fully and successfully established (i.e.,
+ those for which GSS_Init_sec_context() and GSS_Accept_sec_context()
+ have returned GSS_S_COMPLETE major_status).
+
+
+
+
+Linn Standards Track [Page 59]
+
+RFC 2743 GSS-API January 2000
+
+
+ A successful GSS_Export_sec_context() operation deactivates the
+ security context for the calling process; for this case, the GSS-API
+ implementation shall deallocate all process-wide resources associated
+ with the security context and shall set the context_handle to
+ GSS_C_NO_CONTEXT. In the event of an error that makes it impossible
+ to complete export of the security context, the GSS-API
+ implementation must not return an interprocess token and should
+ strive to leave the security context referenced by the context_handle
+ untouched. If this is impossible, it is permissible for the
+ implementation to delete the security context, provided that it also
+ sets the context_handle parameter to GSS_C_NO_CONTEXT.
+
+ Portable callers must not assume that a given interprocess token can
+ be imported by GSS_Import_sec_context() more than once, thereby
+ creating multiple instantiations of a single context. GSS-API
+ implementations may detect and reject attempted multiple imports, but
+ are not required to do so.
+
+ The internal representation contained within the interprocess token
+ is an implementation-defined local matter. Interprocess tokens
+ cannot be assumed to be transferable across different GSS-API
+ implementations.
+
+ It is recommended that GSS-API implementations adopt policies suited
+ to their operational environments in order to define the set of
+ processes eligible to import a context, but specific constraints in
+ this area are local matters. Candidate examples include transfers
+ between processes operating on behalf of the same user identity, or
+ processes comprising a common job. However, it may be impossible to
+ enforce such policies in some implementations.
+
+ In support of the above goals, implementations may protect the
+ transferred context data by using cryptography to protect data within
+ the interprocess token, or by using interprocess tokens as a means to
+ reference local interprocess communication facilities (protected by
+ other means) rather than storing the context data directly within the
+ tokens.
+
+ Transfer of an open context may, for certain mechanisms and
+ implementations, reveal data about the credential which was used to
+ establish the context. Callers should, therefore, be cautious about
+ the trustworthiness of processes to which they transfer contexts.
+ Although the GSS-API implementation may provide its own set of
+ protections over the exported context, the caller is responsible for
+ protecting the interprocess token from disclosure, and for taking
+ care that the context is transferred to an appropriate destination
+ process.
+
+
+
+
+Linn Standards Track [Page 60]
+
+RFC 2743 GSS-API January 2000
+
+
+2.2.9: GSS_Import_sec_context call
+
+ Inputs:
+
+ o interprocess_token OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o context_handle CONTEXT HANDLE -- if successfully returned,
+ -- caller must release with GSS_Delete_sec_context()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the context represented by the input
+ interprocess_token has been successfully transferred to the caller,
+ and is available for future use via the output context_handle.
+
+ o GSS_S_NO_CONTEXT indicates that the context represented by the
+ input interprocess_token was invalid. Return values other than
+ major_status and minor_status are undefined.
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token
+ was defective. Return values other than major_status and
+ minor_status are undefined.
+
+ o GSS_S_UNAVAILABLE indicates that the context import facility is
+ not available for use on the referenced context. Return values other
+ than major_status and minor_status are undefined.
+
+ o GSS_S_UNAUTHORIZED indicates that the context represented by the
+ input interprocess_token is unauthorized for transfer to the caller.
+ Return values other than major_status and minor_status are undefined.
+
+ o GSS_S_FAILURE indicates that the requested operation failed for
+ reasons unspecified at the GSS-API level. Return values other than
+ major_status and minor_status are undefined.
+
+ This call processes an interprocess token generated by
+ GSS_Export_sec_context(), making the transferred context available
+ for use by the caller. After a successful GSS_Import_sec_context()
+ operation, the imported context is available for use by the importing
+ process. In particular, the imported context is usable for all per-
+ message operations and may be deleted or exported by its importer.
+ The inability to receive delegated credentials through
+
+
+
+Linn Standards Track [Page 61]
+
+RFC 2743 GSS-API January 2000
+
+
+ gss_import_sec_context() precludes establishment of new contexts
+ based on information delegated to the importer's end system within
+ the context which is being imported, unless those delegated
+ credentials are obtained through separate routines (e.g., XGSS-API
+ calls) outside the GSS-V2 definition.
+
+ For further discussion of the security and authorization issues
+ regarding this call, please see the discussion in Section 2.2.8.
+
+2.3: Per-message calls
+
+ This group of calls is used to perform per-message protection
+ processing on an established security context. None of these calls
+ block pending network interactions. These calls may be invoked by a
+ context's initiator or by the context's target. The four members of
+ this group should be considered as two pairs; the output from
+ GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output
+ from GSS_Wrap() is properly input to GSS_Unwrap().
+
+ GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication
+ and data integrity services. When GSS_GetMIC() is invoked on an input
+ message, it yields a per-message token containing data items which
+ allow underlying mechanisms to provide the specified security
+ services. The original message, along with the generated per-message
+ token, is passed to the remote peer; these two data elements are
+ processed by GSS_VerifyMIC(), which validates the message in
+ conjunction with the separate token.
+
+ GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality
+ in addition to the data origin authentication and data integrity
+ services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap()
+ outputs a single data element, encapsulating optionally enciphered
+ user data as well as associated token data items. The data element
+ output from GSS_Wrap() is passed to the remote peer and processed by
+ GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as
+ required) with validation of data items related to authentication and
+ integrity.
+
+ Although zero-length tokens are never returned by GSS calls for
+ transfer to a context's peer, a zero-length object may be passed by a
+ caller into GSS_Wrap(), in which case the corresponding peer calling
+ GSS_Unwrap() on the transferred token will receive a zero-length
+ object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be
+ called on an empty object, yielding a MIC which GSS_VerifyMIC() will
+ successfully verify against the active security context in
+ conjunction with a zero-length object.
+
+
+
+
+
+Linn Standards Track [Page 62]
+
+RFC 2743 GSS-API January 2000
+
+
+2.3.1: GSS_GetMIC call
+
+ Note: This call is functionally equivalent to the GSS_Sign call as
+ defined in previous versions of this specification. In the interests
+ of backward compatibility, it is recommended that implementations
+ support this function under both names for the present; future
+ references to this function as GSS_Sign are deprecated.
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o qop_req INTEGER, -- 0 specifies default QOP
+
+ o message OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o per_msg_token OCTET STRING -- caller must release
+ -- with GSS_Release_buffer()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that an integrity check, suitable for an
+ established security context, was successfully applied and that the
+ message and corresponding per_msg_token are ready for transmission.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
+ have expired, so that the requested operation cannot be performed.
+
+ o GSS_S_NO_CONTEXT indicates that no context was recognized for the
+ input context_handle provided.
+
+ o GSS_S_BAD_QOP indicates that the provided QOP value is not
+ recognized or supported for the context.
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the requested operation could not be performed for reasons
+ unspecified at the GSS-API level.
+
+ Using the security context referenced by context_handle, apply an
+ integrity check to the input message (along with timestamps and/or
+ other data included in support of mech_type-specific mechanisms) and
+ (if GSS_S_COMPLETE status is indicated) return the result in
+
+
+
+Linn Standards Track [Page 63]
+
+RFC 2743 GSS-API January 2000
+
+
+ per_msg_token. The qop_req parameter, interpretation of which is
+ discussed in Section 1.2.4, allows quality-of-protection control. The
+ caller passes the message and the per_msg_token to the target.
+
+ The GSS_GetMIC() function completes before the message and
+ per_msg_token is sent to the peer; successful application of
+ GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC()
+ has been (or can necessarily be) performed successfully when the
+ message arrives at the destination.
+
+ Mechanisms which do not support per-message protection services
+ should return GSS_S_FAILURE if this routine is called.
+
+2.3.2: GSS_VerifyMIC call
+
+ Note: This call is functionally equivalent to the GSS_Verify call as
+ defined in previous versions of this specification. In the interests
+ of backward compatibility, it is recommended that implementations
+ support this function under both names for the present; future
+ references to this function as GSS_Verify are deprecated.
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o message OCTET STRING,
+
+ o per_msg_token OCTET STRING
+
+ Outputs:
+
+ o qop_state INTEGER,
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the message was successfully
+ verified.
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
+ on the received per_msg_token failed, preventing further processing
+ from being performed with that token.
+
+ o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
+ per_msg_token contains an incorrect integrity check for the message.
+
+
+
+Linn Standards Track [Page 64]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
+ GSS_S_GAP_TOKEN values appear in conjunction with the optional per-
+ message replay detection features described in Section 1.2.3; their
+ semantics are described in that section.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
+ have expired, so that the requested operation cannot be performed.
+
+ o GSS_S_NO_CONTEXT indicates that no context was recognized for the
+ input context_handle provided.
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the GSS_VerifyMIC() operation could not be performed for reasons
+ unspecified at the GSS-API level.
+
+ Using the security context referenced by context_handle, verify that
+ the input per_msg_token contains an appropriate integrity check for
+ the input message, and apply any active replay detection or
+ sequencing features. Returns an indication of the quality-of-
+ protection applied to the processed message in the qop_state result.
+
+ Mechanisms which do not support per-message protection services
+ should return GSS_S_FAILURE if this routine is called.
+
+2.3.3: GSS_Wrap call
+
+ Note: This call is functionally equivalent to the GSS_Seal call as
+ defined in previous versions of this specification. In the interests
+ of backward compatibility, it is recommended that implementations
+ support this function under both names for the present; future
+ references to this function as GSS_Seal are deprecated.
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o conf_req_flag BOOLEAN,
+
+ o qop_req INTEGER, -- 0 specifies default QOP
+
+ o input_message OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+
+
+
+Linn Standards Track [Page 65]
+
+RFC 2743 GSS-API January 2000
+
+
+ o conf_state BOOLEAN,
+
+ o output_message OCTET STRING -- caller must release with
+ -- GSS_Release_buffer()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the input_message was successfully
+ processed and that the output_message is ready for transmission.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
+ have expired, so that the requested operation cannot be performed.
+
+ o GSS_S_NO_CONTEXT indicates that no context was recognized for the
+ input context_handle provided.
+
+ o GSS_S_BAD_QOP indicates that the provided QOP value is not
+ recognized or supported for the context.
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the GSS_Wrap() operation could not be performed for reasons
+ unspecified at the GSS-API level.
+
+ Performs the data origin authentication and data integrity functions
+ of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that
+ confidentiality be applied to the input_message. Confidentiality may
+ not be supported in all mech_types or by all implementations; the
+ returned conf_state flag indicates whether confidentiality was
+ provided for the input_message. The qop_req parameter, interpretation
+ of which is discussed in Section 1.2.4, allows quality-of-protection
+ control.
+
+ When GSS_S_COMPLETE status is returned, the GSS_Wrap() call yields a
+ single output_message data element containing (optionally enciphered)
+ user data as well as control information.
+
+ Mechanisms which do not support per-message protection services
+ should return GSS_S_FAILURE if this routine is called.
+
+2.3.4: GSS_Unwrap call
+
+ Note: This call is functionally equivalent to the GSS_Unseal call as
+ defined in previous versions of this specification. In the interests
+ of backward compatibility, it is recommended that implementations
+ support this function under both names for the present; future
+ references to this function as GSS_Unseal are deprecated.
+
+
+
+
+
+Linn Standards Track [Page 66]
+
+RFC 2743 GSS-API January 2000
+
+
+ Inputs:
+
+ o context_handle CONTEXT HANDLE,
+
+ o input_message OCTET STRING
+
+ Outputs:
+
+ o conf_state BOOLEAN,
+
+ o qop_state INTEGER,
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o output_message OCTET STRING -- caller must release with
+ -- GSS_Release_buffer()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the input_message was successfully
+ processed and that the resulting output_message is available.
+
+ o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
+ on the per_msg_token extracted from the input_message failed,
+ preventing further processing from being performed.
+
+ o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect
+ integrity check was detected for the message.
+
+ o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
+ GSS_S_GAP_TOKEN values appear in conjunction with the optional per-
+ message replay detection features described in Section 1.2.3; their
+ semantics are described in that section.
+
+ o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
+ have expired, so that the requested operation cannot be performed.
+
+ o GSS_S_NO_CONTEXT indicates that no context was recognized for the
+ input context_handle provided.
+
+ o GSS_S_FAILURE indicates that the context is recognized, but that
+ the GSS_Unwrap() operation could not be performed for reasons
+ unspecified at the GSS-API level.
+
+
+
+
+
+
+Linn Standards Track [Page 67]
+
+RFC 2743 GSS-API January 2000
+
+
+ Processes a data element generated (and optionally enciphered) by
+ GSS_Wrap(), provided as input_message. The returned conf_state value
+ indicates whether confidentiality was applied to the input_message.
+ If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message.
+ Returns an indication of the quality-of-protection applied to the
+ processed message in the qop_state result. GSS_Unwrap() performs the
+ data integrity and data origin authentication checking functions of
+ GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in
+ output_message.
+
+ Mechanisms which do not support per-message protection services
+ should return GSS_S_FAILURE if this routine is called.
+
+2.4: Support calls
+
+ This group of calls provides support functions useful to GSS-API
+ callers, independent of the state of established contexts. Their
+ characterization with regard to blocking or non-blocking status in
+ terms of network interactions is unspecified.
+
+2.4.1: GSS_Display_status call
+
+ Inputs:
+
+ o status_value INTEGER, -- GSS-API major_status or minor_status
+ -- return value
+
+ o status_type INTEGER, -- 1 if major_status, 2 if minor_status
+
+ o mech_type OBJECT IDENTIFIER -- mech_type to be used for
+ -- minor_status translation
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o status_string_set SET OF OCTET STRING -- required calls for
+ -- release by caller are specific to language bindings
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a valid printable status
+ representation (possibly representing more than one status event
+ encoded within the status_value) is available in the returned
+ status_string_set.
+
+
+
+
+Linn Standards Track [Page 68]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_BAD_MECH indicates that translation in accordance with an
+ unsupported mech_type was requested, so translation could not be
+ performed.
+
+ o GSS_S_BAD_STATUS indicates that the input status_value was
+ invalid, or that the input status_type carried a value other than 1
+ or 2, so translation could not be performed.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Provides a means for callers to translate GSS-API-returned major and
+ minor status codes into printable string representations. Note: some
+ language bindings may employ an iterative approach in order to emit
+ successive status components; this approach is acceptable but not
+ required for conformance with the current specification.
+
+ Although not contemplated in [RFC-2078], it has been observed that
+ some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED
+ status when iterating through successive messages returned from
+ GSS_Display_status(). This behavior is deprecated;
+ GSS_S_CONTINUE_NEEDED should be returned only by
+ GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal
+ portability, however, it is recommended that defensive callers be
+ able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated
+ by GSS_Display_status() or any other call other than
+ GSS_Init_sec_context() or GSS_Accept_sec_context().
+
+2.4.2: GSS_Indicate_mechs call
+
+ Input:
+
+ o (none)
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o mech_set SET OF OBJECT IDENTIFIER -- caller must release
+ -- with GSS_Release_oid_set()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a set of available mechanisms has
+ been returned in mech_set.
+
+
+
+
+Linn Standards Track [Page 69]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to determine the set of mechanism types available on
+ the local system. This call is intended for support of specialized
+ callers who need to request non-default mech_type sets from GSS-API
+ calls which accept input mechanism type specifiers.
+
+2.4.3: GSS_Compare_name call
+
+ Inputs:
+
+ o name1 INTERNAL NAME,
+
+ o name2 INTERNAL NAME
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o name_equal BOOLEAN
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that name1 and name2 were comparable, and
+ that the name_equal result indicates whether name1 and name2
+ represent the same entity.
+
+ o GSS_S_BAD_NAMETYPE indicates that the two input names' types are
+ different and incomparable, so that the comparison operation could
+ not be completed.
+
+ o GSS_S_BAD_NAME indicates that one or both of the input names was
+ ill-formed in terms of its internal type specifier, so the comparison
+ operation could not be completed.
+
+ o GSS_S_FAILURE indicates that the call's operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to compare two internal name representations to
+ determine whether they refer to the same entity. If either name
+ presented to GSS_Compare_name() denotes an anonymous principal,
+ GSS_Compare_name() shall indicate FALSE. It is not required that
+ either or both inputs name1 and name2 be MNs; for some
+
+
+
+
+
+Linn Standards Track [Page 70]
+
+RFC 2743 GSS-API January 2000
+
+
+ implementations and cases, GSS_S_BAD_NAMETYPE may be returned,
+ indicating name incomparability, for the case where neither input
+ name is an MN.
+
+2.4.4: GSS_Display_name call
+
+ Inputs:
+
+ o name INTERNAL NAME
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o name_string OCTET STRING, -- caller must release
+ -- with GSS_Release_buffer()
+
+ o name_type OBJECT IDENTIFIER -- caller should treat
+ -- as read-only; does not need to be released
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a valid printable name
+ representation is available in the returned name_string.
+
+ o GSS_S_BAD_NAME indicates that the contents of the provided name
+ were inconsistent with the internally-indicated name type, so no
+ printable representation could be generated.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to translate an internal name representation into a
+ printable form with associated namespace type descriptor. The syntax
+ of the printable form is a local matter.
+
+ If the input name represents an anonymous identity, a reserved value
+ (GSS_C_NT_ANONYMOUS) shall be returned for name_type.
+
+ The GSS_C_NO_OID name type is to be returned only when the
+ corresponding internal name was created through import with
+ GSS_C_NO_OID. It is acceptable for mechanisms to normalize names
+ imported with GSS_C_NO_OID into other supported types and, therefore,
+ to display them with types other than GSS_C_NO_OID.
+
+
+
+
+
+Linn Standards Track [Page 71]
+
+RFC 2743 GSS-API January 2000
+
+
+2.4.5: GSS_Import_name call
+
+ Inputs:
+
+ o input_name_string OCTET STRING,
+
+ o input_name_type OBJECT IDENTIFIER
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o output_name INTERNAL NAME -- caller must release with
+ -- GSS_Release_name()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a valid name representation is
+ output in output_name and described by the type value in
+ output_name_type.
+
+ o GSS_S_BAD_NAMETYPE indicates that the input_name_type is
+ unsupported by the applicable underlying GSS-API mechanism(s), so the
+ import operation could not be completed.
+
+ o GSS_S_BAD_NAME indicates that the provided input_name_string is
+ ill-formed in terms of the input_name_type, so the import operation
+ could not be completed.
+
+ o GSS_S_BAD_MECH indicates that the input presented for import was
+ an exported name object and that its enclosed mechanism type was not
+ recognized or was unsupported by the GSS-API implementation.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to provide a name representation as a contiguous octet
+ string, designate the type of namespace in conjunction with which it
+ should be parsed, and convert that representation to an internal form
+ suitable for input to other GSS-API routines. The syntax of the
+ input_name_string is defined in conjunction with its associated name
+ type; depending on the input_name_type, the associated
+ input_name_string may or may not be a printable string. If the
+ input_name_type's value is GSS_C_NO_OID, a mechanism-specific default
+ printable syntax (which shall be specified in the corresponding GSS-
+ V2 mechanism specification) is assumed for the input_name_string;
+
+
+
+Linn Standards Track [Page 72]
+
+RFC 2743 GSS-API January 2000
+
+
+ other input_name_type values as registered by GSS-API implementations
+ can be used to indicate specific non-default name syntaxes. Note: The
+ input_name_type argument serves to describe and qualify the
+ interpretation of the associated input_name_string; it does not
+ specify the data type of the returned output_name.
+
+ If a mechanism claims support for a particular name type, its
+ GSS_Import_name() operation shall be able to accept all possible
+ values conformant to the external name syntax as defined for that
+ name type. These imported values may correspond to:
+
+ (1) locally registered entities (for which credentials may be
+ acquired),
+
+ (2) non-local entities (for which local credentials cannot be
+ acquired, but which may be referenced as targets of initiated
+ security contexts or initiators of accepted security contexts), or
+ to
+
+ (3) neither of the above.
+
+ Determination of whether a particular name belongs to class (1), (2),
+ or (3) as described above is not guaranteed to be performed by the
+ GSS_Import_name() function.
+
+ The internal name generated by a GSS_Import_name() operation may be a
+ single-mechanism MN, and is likely to be an MN within a single-
+ mechanism implementation, but portable callers must not depend on
+ this property (and must not, therefore, assume that the output from
+ GSS_Import_name() can be passed directly to GSS_Export_name() without
+ first being processed through GSS_Canonicalize_name()).
+
+2.4.6: GSS_Release_name call
+
+ Inputs:
+
+ o name INTERNAL NAME
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the storage associated with the
+ input name was successfully released.
+
+
+
+Linn Standards Track [Page 73]
+
+RFC 2743 GSS-API January 2000
+
+
+ o GSS_S_BAD_NAME indicates that the input name argument did not
+ contain a valid name.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to release the storage associated with an internal
+ name representation. This call's specific behavior depends on the
+ language and programming environment within which a GSS-API
+ implementation operates, and is therefore detailed within applicable
+ bindings specifications; in particular, implementation and invocation
+ of this call may be superfluous (and may be omitted) within bindings
+ where memory management is automatic.
+
+2.4.7: GSS_Release_buffer call
+
+ Inputs:
+
+ o buffer OCTET STRING
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the storage associated with the
+ input buffer was successfully released.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to release the storage associated with an OCTET STRING
+ buffer allocated by another GSS-API call. This call's specific
+ behavior depends on the language and programming environment within
+ which a GSS-API implementation operates, and is therefore detailed
+ within applicable bindings specifications; in particular,
+ implementation and invocation of this call may be superfluous (and
+ may be omitted) within bindings where memory management is automatic.
+
+2.4.8: GSS_Release_OID_set call
+
+ Inputs:
+
+ o buffer SET OF OBJECT IDENTIFIER
+
+
+
+
+Linn Standards Track [Page 74]
+
+RFC 2743 GSS-API January 2000
+
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the storage associated with the
+ input object identifier set was successfully released.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to release the storage associated with an object
+ identifier set object allocated by another GSS-API call. This call's
+ specific behavior depends on the language and programming environment
+ within which a GSS-API implementation operates, and is therefore
+ detailed within applicable bindings specifications; in particular,
+ implementation and invocation of this call may be superfluous (and
+ may be omitted) within bindings where memory management is automatic.
+
+2.4.9: GSS_Create_empty_OID_set call
+
+ Inputs:
+
+ o (none)
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o oid_set SET OF OBJECT IDENTIFIER -- caller must release
+ -- with GSS_Release_oid_set()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates successful completion
+
+ o GSS_S_FAILURE indicates that the operation failed
+
+ Creates an object identifier set containing no object identifiers, to
+ which members may be subsequently added using the
+ GSS_Add_OID_set_member() routine. These routines are intended to be
+ used to construct sets of mechanism object identifiers, for input to
+ GSS_Acquire_cred().
+
+
+
+Linn Standards Track [Page 75]
+
+RFC 2743 GSS-API January 2000
+
+
+2.4.10: GSS_Add_OID_set_member call
+
+ Inputs:
+
+ o member_oid OBJECT IDENTIFIER,
+
+ o oid_set SET OF OBJECT IDENTIFIER
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates successful completion
+
+ o GSS_S_FAILURE indicates that the operation failed
+
+ Adds an Object Identifier to an Object Identifier set. This routine
+ is intended for use in conjunction with GSS_Create_empty_OID_set()
+ when constructing a set of mechanism OIDs for input to
+ GSS_Acquire_cred().
+
+2.4.11: GSS_Test_OID_set_member call
+
+ Inputs:
+
+ o member OBJECT IDENTIFIER,
+
+ o set SET OF OBJECT IDENTIFIER
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o present BOOLEAN
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates successful completion
+
+ o GSS_S_FAILURE indicates that the operation failed
+
+
+
+
+
+Linn Standards Track [Page 76]
+
+RFC 2743 GSS-API January 2000
+
+
+ Interrogates an Object Identifier set to determine whether a
+ specified Object Identifier is a member. This routine is intended to
+ be used with OID sets returned by GSS_Indicate_mechs(),
+ GSS_Acquire_cred(), and GSS_Inquire_cred().
+
+2.4.12: GSS_Inquire_names_for_mech call
+
+ Input:
+
+ o input_mech_type OBJECT IDENTIFIER, -- mechanism type
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o name_type_set SET OF OBJECT IDENTIFIER -- caller must release
+ -- with GSS_Release_oid_set()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that the output name_type_set contains a
+ list of name types which are supported by the locally available
+ mechanism identified by input_mech_type.
+
+ o GSS_S_BAD_MECH indicates that the mechanism identified by
+ input_mech_type was unsupported within the local implementation,
+ causing the query to fail.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ Allows callers to determine the set of name types which are
+ supportable by a specific locally-available mechanism.
+
+2.4.13: GSS_Inquire_mechs_for_name call
+
+ Inputs:
+
+ o input_name INTERNAL NAME,
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+
+
+
+Linn Standards Track [Page 77]
+
+RFC 2743 GSS-API January 2000
+
+
+ o mech_types SET OF OBJECT IDENTIFIER -- caller must release
+ -- with GSS_Release_oid_set()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a set of object identifiers,
+ corresponding to the set of mechanisms suitable for processing the
+ input_name, is available in mech_types.
+
+ o GSS_S_BAD_NAME indicates that the input_name was ill-formed and
+ could not be processed.
+
+ o GSS_S_BAD_NAMETYPE indicates that the input_name parameter
+ contained an invalid name type or a name type unsupported by the
+ GSS-API implementation.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ This routine returns the mechanism set with which the input_name may
+ be processed.
+
+ Each mechanism returned will recognize at least one element within
+ the name. It is permissible for this routine to be implemented within
+ a mechanism-independent GSS-API layer, using the type information
+ contained within the presented name, and based on registration
+ information provided by individual mechanism implementations. This
+ means that the returned mech_types result may indicate that a
+ particular mechanism will understand a particular name when in fact
+ it would refuse to accept that name as input to
+ GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(),
+ or GSS_Add_cred(), due to some property of the particular name rather
+ than a property of the name type. Thus, this routine should be used
+ only as a pre-filter for a call to a subsequent mechanism-specific
+ routine.
+
+2.4.14: GSS_Canonicalize_name call
+
+ Inputs:
+
+ o input_name INTERNAL NAME,
+
+ o mech_type OBJECT IDENTIFIER -- must be explicit mechanism,
+ -- not "default" specifier or identifier of negotiating mechanism
+
+ Outputs:
+
+ o major_status INTEGER,
+
+
+
+Linn Standards Track [Page 78]
+
+RFC 2743 GSS-API January 2000
+
+
+ o minor_status INTEGER,
+
+ o output_name INTERNAL NAME -- caller must release with
+ -- GSS_Release_name()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a mechanism-specific reduction of
+ the input_name, as processed by the mechanism identified by
+ mech_type, is available in output_name.
+
+ o GSS_S_BAD_MECH indicates that the identified mechanism is
+ unsupported for this operation; this may correspond either to a
+ mechanism wholly unsupported by the local GSS-API implementation or
+ to a negotiating mechanism with which the canonicalization operation
+ cannot be performed.
+
+ o GSS_S_BAD_NAMETYPE indicates that the input name does not contain
+ an element with suitable type for processing by the identified
+ mechanism.
+
+ o GSS_S_BAD_NAME indicates that the input name contains an element
+ with suitable type for processing by the identified mechanism, but
+ that this element could not be processed successfully.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ This routine reduces a GSS-API internal name input_name, which may in
+ general contain elements corresponding to multiple mechanisms, to a
+ mechanism-specific Mechanism Name (MN) output_name by applying the
+ translations corresponding to the mechanism identified by mech_type.
+ The contents of input_name are unaffected by the
+ GSS_Canonicalize_name() operation. References to output_name will
+ remain valid until output_name is released, independent of whether or
+ not input_name is subsequently released.
+
+2.4.15: GSS_Export_name call
+
+ Inputs:
+
+ o input_name INTERNAL NAME, -- required to be MN
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+
+
+Linn Standards Track [Page 79]
+
+RFC 2743 GSS-API January 2000
+
+
+ o output_name OCTET STRING -- caller must release
+ -- with GSS_Release_buffer()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that a flat representation of the input
+ name is available in output_name.
+
+ o GSS_S_NAME_NOT_MN indicates that the input name contained elements
+ corresponding to multiple mechanisms, so cannot be exported into a
+ single-mechanism flat form.
+
+ o GSS_S_BAD_NAME indicates that the input name was an MN, but could
+ not be processed.
+
+ o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, but
+ that its type is unsupported by the GSS-API implementation.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ This routine creates a flat name representation, suitable for
+ bytewise comparison or for input to GSS_Import_name() in conjunction
+ with the reserved GSS-API Exported Name Object OID, from a internal-
+ form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name()
+ or GSS_Accept_sec_context().
+
+ The emitted GSS-API Exported Name Object is self-describing; no
+ associated parameter-level OID need be emitted by this call. This
+ flat representation consists of a mechanism-independent wrapper
+ layer, defined in Section 3.2 of this document, enclosing a
+ mechanism-defined name representation.
+
+ In all cases, the flat name output by GSS_Export_name() to correspond
+ to a particular input MN must be invariant over time within a
+ particular installation.
+
+ The GSS_S_NAME_NOT_MN status code is provided to enable
+ implementations to reject input names which are not MNs. It is not,
+ however, required for purposes of conformance to this specification
+ that all non-MN input names must necessarily be rejected.
+
+2.4.16: GSS_Duplicate_name call
+
+ Inputs:
+
+ o src_name INTERNAL NAME
+
+
+
+
+Linn Standards Track [Page 80]
+
+RFC 2743 GSS-API January 2000
+
+
+ Outputs:
+
+ o major_status INTEGER,
+
+ o minor_status INTEGER,
+
+ o dest_name INTERNAL NAME -- caller must release
+ -- with GSS_Release_name()
+
+ Return major_status codes:
+
+ o GSS_S_COMPLETE indicates that dest_name references an internal
+ name object containing the same name as passed to src_name.
+
+ o GSS_S_BAD_NAME indicates that the input name was invalid.
+
+ o GSS_S_FAILURE indicates that the requested operation could not be
+ performed for reasons unspecified at the GSS-API level.
+
+ This routine takes input internal name src_name, and returns another
+ reference (dest_name) to that name which can be used even if src_name
+ is later freed. (Note: This may be implemented by copying or through
+ use of reference counts.)
+
+3: Data Structure Definitions for GSS-V2 Usage
+
+ Subsections of this section define, for interoperability and
+ portability purposes, certain data structures for use with GSS-V2.
+
+3.1: Mechanism-Independent Token Format
+
+ This section specifies a mechanism-independent level of encapsulating
+ representation for the initial token of a GSS-API context
+ establishment sequence, incorporating an identifier of the mechanism
+ type to be used on that context and enabling tokens to be interpreted
+ unambiguously at GSS-API peers. Use of this format is required for
+ initial context establishment tokens of Internet standards-track
+ GSS-API mechanisms; use in non-initial tokens is optional.
+
+ The encoding format for the token tag is derived from ASN.1 and DER
+ (per illustrative ASN.1 syntax included later within this
+ subsection), but its concrete representation is defined directly in
+ terms of octets rather than at the ASN.1 level in order to facilitate
+ interoperable implementation without use of general ASN.1 processing
+ code. The token tag consists of the following elements, in order:
+
+ 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that
+ -- constructed form, definite length encoding follows.
+
+
+
+Linn Standards Track [Page 81]
+
+RFC 2743 GSS-API January 2000
+
+
+ 2. Token length octets, specifying length of subsequent data
+ (i.e., the summed lengths of elements 3-5 in this list, and of the
+ mechanism-defined token object following the tag). This element
+ comprises a variable number of octets:
+
+ 2a. If the indicated value is less than 128, it shall be
+ represented in a single octet with bit 8 (high order) set to
+ "0" and the remaining bits representing the value.
+
+ 2b. If the indicated value is 128 or more, it shall be
+ represented in two or more octets, with bit 8 of the first
+ octet set to "1" and the remaining bits of the first octet
+ specifying the number of additional octets. The subsequent
+ octets carry the value, 8 bits per octet, most significant
+ digit first. The minimum number of octets shall be used to
+ encode the length (i.e., no octets representing leading zeros
+ shall be included within the length encoding).
+
+ 3. 0x06 -- Tag for OBJECT IDENTIFIER
+
+ 4. Object identifier length -- length (number of octets) of
+ -- the encoded object identifier contained in element 5,
+ -- encoded per rules as described in 2a. and 2b. above.
+
+ 5. Object identifier octets -- variable number of octets,
+ -- encoded per ASN.1 BER rules:
+
+ 5a. The first octet contains the sum of two values: (1) the
+ top-level object identifier component, multiplied by 40
+ (decimal), and (2) the second-level object identifier
+ component. This special case is the only point within an
+ object identifier encoding where a single octet represents
+ contents of more than one component.
+
+ 5b. Subsequent octets, if required, encode successively-lower
+ components in the represented object identifier. A component's
+ encoding may span multiple octets, encoding 7 bits per octet
+ (most significant bits first) and with bit 8 set to "1" on all
+ but the final octet in the component's encoding. The minimum
+ number of octets shall be used to encode each component (i.e.,
+ no octets representing leading zeros shall be included within a
+ component's encoding).
+
+ (Note: In many implementations, elements 3-5 may be stored and
+ referenced as a contiguous string constant.)
+
+
+
+
+
+
+Linn Standards Track [Page 82]
+
+RFC 2743 GSS-API January 2000
+
+
+ The token tag is immediately followed by a mechanism-defined token
+ object. Note that no independent size specifier intervenes following
+ the object identifier value to indicate the size of the mechanism-
+ defined token object. While ASN.1 usage within mechanism-defined
+ tokens is permitted, there is no requirement that the mechanism-
+ specific innerContextToken, innerMsgToken, and sealedUserData data
+ elements must employ ASN.1 BER/DER encoding conventions.
+
+ The following ASN.1 syntax is included for descriptive purposes only,
+ to illustrate structural relationships among token and tag objects.
+ For interoperability purposes, token and tag encoding shall be
+ performed using the concrete encoding procedures described earlier in
+ this subsection.
+
+ GSS-API DEFINITIONS ::=
+
+ BEGIN
+
+ MechType ::= OBJECT IDENTIFIER
+ -- data structure definitions
+ -- callers must be able to distinguish among
+ -- InitialContextToken, SubsequentContextToken,
+ -- PerMsgToken, and SealedMessage data elements
+ -- based on the usage in which they occur
+
+ InitialContextToken ::=
+ -- option indication (delegation, etc.) indicated within
+ -- mechanism-specific token
+ [APPLICATION 0] IMPLICIT SEQUENCE {
+ thisMech MechType,
+ innerContextToken ANY DEFINED BY thisMech
+ -- contents mechanism-specific
+ -- ASN.1 structure not required
+ }
+
+ SubsequentContextToken ::= innerContextToken ANY
+ -- interpretation based on predecessor InitialContextToken
+ -- ASN.1 structure not required
+
+ PerMsgToken ::=
+ -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC
+ -- ASN.1 structure not required
+ innerMsgToken ANY
+
+ SealedMessage ::=
+ -- as emitted by GSS_Wrap and processed by GSS_Unwrap
+ -- includes internal, mechanism-defined indicator
+ -- of whether or not encrypted
+
+
+
+Linn Standards Track [Page 83]
+
+RFC 2743 GSS-API January 2000
+
+
+ -- ASN.1 structure not required
+ sealedUserData ANY
+
+ END
+
+3.2: Mechanism-Independent Exported Name Object Format
+
+ This section specifies a mechanism-independent level of encapsulating
+ representation for names exported via the GSS_Export_name() call,
+ including an object identifier representing the exporting mechanism.
+ The format of names encapsulated via this representation shall be
+ defined within individual mechanism drafts. The Object Identifier
+ value to indicate names of this type is defined in Section 4.7 of
+ this document.
+
+ No name type OID is included in this mechanism-independent level of
+ format definition, since (depending on individual mechanism
+ specifications) the enclosed name may be implicitly typed or may be
+ explicitly typed using a means other than OID encoding.
+
+ The bytes within MECH_OID_LEN and NAME_LEN elements are represented
+ most significant byte first (equivalently, in IP network byte order).
+
+ Length Name Description
+
+ 2 TOK_ID Token Identifier
+ For exported name objects, this
+ must be hex 04 01.
+ 2 MECH_OID_LEN Length of the Mechanism OID
+ MECH_OID_LEN MECH_OID Mechanism OID, in DER
+ 4 NAME_LEN Length of name
+ NAME_LEN NAME Exported name; format defined in
+ applicable mechanism draft.
+
+ A concrete example of the contents of an exported name object,
+ derived from the Kerberos Version 5 mechanism, is as follows:
+
+ 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz
+
+ 04 01 mandatory token identifier
+
+ 00 0B 2-byte length of the immediately following DER-encoded
+ ASN.1 value of type OID, most significant octet first
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 84]
+
+RFC 2743 GSS-API January 2000
+
+
+ 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value
+ of type OID; Kerberos V5
+ mechanism OID indicates
+ Kerberos V5 exported name
+
+ in Detail: 06 Identifier octet (6=OID)
+ 09 Length octet(s)
+ 2A 86 48 86 F7 12 01 02 02 Content octet(s)
+
+ hx xx xx xl 4-byte length of the immediately following exported
+ name blob, most significant octet first
+
+ pp qq ... zz exported name blob of specified length,
+ bits and bytes specified in the
+ (Kerberos 5) GSS-API v2 mechanism spec
+
+4: Name Type Definitions
+
+ This section includes definitions for name types and associated
+ syntaxes which are defined in a mechanism-independent fashion at the
+ GSS-API level rather than being defined in individual mechanism
+ specifications.
+
+4.1: Host-Based Service Name Form
+
+ This name form shall be represented by the Object Identifier:
+
+ {iso(1) member-body(2) United States(840) mit(113554) infosys(1)
+ "gssapi(2) generic(1) service_name(4)}.
+
+ The recommended symbolic name for this type is
+ "GSS_C_NT_HOSTBASED_SERVICE".
+
+ For reasons of compatibility with existing implementations, it is
+ recommended that this OID be used rather than the alternate value as
+ included in [RFC-2078]:
+
+ {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
+ 2(gss-host-based-services)}
+
+ While it is not recommended that this alternate value be emitted on
+ output by GSS implementations, it is recommended that it be accepted
+ on input as equivalent to the recommended value.
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 85]
+
+RFC 2743 GSS-API January 2000
+
+
+ This name type is used to represent services associated with host
+ computers. Support for this name form is recommended to mechanism
+ designers in the interests of portability, but is not mandated by
+ this specification. This name form is constructed using two elements,
+ "service" and "hostname", as follows:
+
+ service@hostname
+
+ When a reference to a name of this type is resolved, the "hostname"
+ may (as an example implementation strategy) be canonicalized by
+ attempting a DNS lookup and using the fully-qualified domain name
+ which is returned, or by using the "hostname" as provided if the DNS
+ lookup fails. The canonicalization operation also maps the host's
+ name into lower-case characters.
+
+ The "hostname" element may be omitted. If no "@" separator is
+ included, the entire name is interpreted as the service specifier,
+ with the "hostname" defaulted to the canonicalized name of the local
+ host.
+
+ Documents specifying means for GSS integration into a particular
+ protocol should state either:
+
+ (a) that a specific IANA-registered name associated with that
+ protocol shall be used for the "service" element (this admits, if
+ needed, the possibility that a single name can be registered and
+ shared among a related set of protocols), or
+
+ (b) that the generic name "host" shall be used for the "service"
+ element, or
+
+ (c) that, for that protocol, fallback in specified order (a, then
+ b) or (b, then a) shall be applied.
+
+ IANA registration of specific names per (a) should be handled in
+ accordance with the "Specification Required" assignment policy,
+ defined by BCP 26, RFC 2434 as follows: "Values and their meaning
+ must be documented in an RFC or other available reference, in
+ sufficient detail so that interoperability between independent
+ implementations is possible."
+
+4.2: User Name Form
+
+ This name form shall be represented by the Object Identifier {iso(1)
+ member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
+ generic(1) user_name(1)}. The recommended mechanism-independent
+ symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same
+
+
+
+
+Linn Standards Track [Page 86]
+
+RFC 2743 GSS-API January 2000
+
+
+ name form and OID is defined within the Kerberos V5 GSS-API
+ mechanism, but the symbolic name recommended there begins with a
+ "GSS_KRB5_NT_" prefix.)
+
+ This name type is used to indicate a named user on a local system.
+ Its syntax and interpretation may be OS-specific. This name form is
+ constructed as:
+
+ username
+
+4.3: Machine UID Form
+
+ This name form shall be represented by the Object Identifier {iso(1)
+ member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
+ generic(1) machine_uid_name(2)}. The recommended mechanism-
+ independent symbolic name for this type is
+ "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is
+ defined within the Kerberos V5 GSS-API mechanism, but the symbolic
+ name recommended there begins with a "GSS_KRB5_NT_" prefix.)
+
+ This name type is used to indicate a numeric user identifier
+ corresponding to a user on a local system. Its interpretation is
+ OS-specific. The gss_buffer_desc representing a name of this type
+ should contain a locally-significant user ID, represented in host
+ byte order. The GSS_Import_name() operation resolves this uid into a
+ username, which is then treated as the User Name Form.
+
+4.4: String UID Form
+
+ This name form shall be represented by the Object Identifier {iso(1)
+ member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
+ generic(1) string_uid_name(3)}. The recommended symbolic name for
+ this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form
+ and OID is defined within the Kerberos V5 GSS-API mechanism, but the
+ symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.)
+
+ This name type is used to indicate a string of digits representing
+ the numeric user identifier of a user on a local system. Its
+ interpretation is OS-specific. This name type is similar to the
+ Machine UID Form, except that the buffer contains a string
+ representing the user ID.
+
+4.5: Anonymous Nametype
+
+ The following Object Identifier value is provided as a means to
+ identify anonymous names, and can be compared against in order to
+ determine, in a mechanism-independent fashion, whether a name refers
+ to an anonymous principal:
+
+
+
+Linn Standards Track [Page 87]
+
+RFC 2743 GSS-API January 2000
+
+
+ {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
+ 3(gss-anonymous-name)}
+
+ The recommended symbolic name corresponding to this definition is
+ GSS_C_NT_ANONYMOUS.
+
+4.6: GSS_C_NO_OID
+
+ The recommended symbolic name GSS_C_NO_OID corresponds to a null
+ input value instead of an actual object identifier. Where specified,
+ it indicates interpretation of an associated name based on a
+ mechanism-specific default printable syntax.
+
+4.7: Exported Name Object
+
+ Name objects of the Mechanism-Independent Exported Name Object type,
+ as defined in Section 3.2 of this document, will be identified with
+ the following Object Identifier:
+
+ {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
+ 4(gss-api-exported-name)}
+
+ The recommended symbolic name corresponding to this definition is
+ GSS_C_NT_EXPORT_NAME.
+
+4.8: GSS_C_NO_NAME
+
+ The recommended symbolic name GSS_C_NO_NAME indicates that no name is
+ being passed within a particular value of a parameter used for the
+ purpose of transferring names. Note: GSS_C_NO_NAME is not an actual
+ name type, and is not represented by an OID; its acceptability in
+ lieu of an actual name is confined to specific calls
+ (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with
+ usages as identified within this specification.
+
+5: Mechanism-Specific Example Scenarios
+
+ This section provides illustrative overviews of the use of various
+ candidate mechanism types to support the GSS-API. These discussions
+ are intended primarily for readers familiar with specific security
+ technologies, demonstrating how GSS-API functions can be used and
+ implemented by candidate underlying mechanisms. They should not be
+ regarded as constrictive to implementations or as defining the only
+ means through which GSS-API functions can be realized with a
+ particular underlying technology, and do not demonstrate all GSS-API
+ features with each technology.
+
+
+
+
+
+Linn Standards Track [Page 88]
+
+RFC 2743 GSS-API January 2000
+
+
+5.1: Kerberos V5, single-TGT
+
+ OS-specific login functions yield a TGT to the local realm Kerberos
+ server; TGT is placed in a credentials structure for the client.
+ Client calls GSS_Acquire_cred() to acquire a cred_handle in order to
+ reference the credentials for use in establishing security contexts.
+
+ Client calls GSS_Init_sec_context(). If the requested service is
+ located in a different realm, GSS_Init_sec_context() gets the
+ necessary TGT/key pairs needed to traverse the path from local to
+ target realm; these data are placed in the owner's TGT cache. After
+ any needed remote realm resolution, GSS_Init_sec_context() yields a
+ service ticket to the requested service with a corresponding session
+ key; these data are stored in conjunction with the context. GSS-API
+ code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP
+ response(s) (in the successful case) or KRB_ERROR.
+
+ Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted
+ KRB_AP_REQ message, and returns it in output_token. The client sends
+ the output_token to the service.
+
+ The service passes the received token as the input_token argument to
+ GSS_Accept_sec_context(), which verifies the authenticator, provides
+ the service with the client's authenticated name, and returns an
+ output_context_handle.
+
+ Both parties now hold the session key associated with the service
+ ticket, and can use this key in subsequent GSS_GetMIC(),
+ GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations.
+
+5.2: Kerberos V5, double-TGT
+
+ TGT acquisition as above.
+
+ Note: To avoid unnecessary frequent invocations of error paths when
+ implementing the GSS-API atop Kerberos V5, it seems appropriate to
+ represent "single-TGT K-V5" and "double-TGT K-V5" with separate
+ mech_types, and this discussion makes that assumption.
+
+ Based on the (specified or defaulted) mech_type,
+ GSS_Init_sec_context() determines that the double-TGT protocol
+ should be employed for the specified target. GSS_Init_sec_context()
+ returns GSS_S_CONTINUE_NEEDED major_status, and its returned
+ output_token contains a request to the service for the service's TGT.
+ (If a service TGT with suitably long remaining lifetime already
+ exists in a cache, it may be usable, obviating the need for this
+ step.) The client passes the output_token to the service. Note: this
+ scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED
+
+
+
+Linn Standards Track [Page 89]
+
+RFC 2743 GSS-API January 2000
+
+
+ status return facility than for support of mutual authentication;
+ note that both uses can coexist as successive operations within a
+ single context establishment operation.
+
+ The service passes the received token as the input_token argument to
+ GSS_Accept_sec_context(), which recognizes it as a request for TGT.
+ (Note that current Kerberos V5 defines no intra-protocol mechanism to
+ represent such a request.) GSS_Accept_sec_context() returns
+ GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in
+ its output_token. The service sends the output_token to the client.
+
+ The client passes the received token as the input_token argument to a
+ continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches
+ the received service TGT and uses it as part of a service ticket
+ request to the Kerberos authentication server, storing the returned
+ service ticket and session key in conjunction with the context.
+ GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and
+ returns it in output_token along with GSS_S_COMPLETE return
+ major_status. The client sends the output_token to the service.
+
+ Service passes the received token as the input_token argument to a
+ continuation call to GSS_Accept_sec_context().
+ GSS_Accept_sec_context() verifies the authenticator, provides the
+ service with the client's authenticated name, and returns
+ major_status GSS_S_COMPLETE.
+
+ GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as
+ above.
+
+5.3: X.509 Authentication Framework
+
+ This example illustrates use of the GSS-API in conjunction with
+ public-key mechanisms, consistent with the X.509 Directory
+ Authentication Framework.
+
+ The GSS_Acquire_cred() call establishes a credentials structure,
+ making the client's private key accessible for use on behalf of the
+ client.
+
+ The client calls GSS_Init_sec_context(), which interrogates the
+ Directory to acquire (and validate) a chain of public-key
+ certificates, thereby collecting the public key of the service. The
+ certificate validation operation determines that suitable integrity
+ checks were applied by trusted authorities and that those
+ certificates have not expired. GSS_Init_sec_context() generates a
+ secret key for use in per-message protection operations on the
+ context, and enciphers that secret key under the service's public
+ key.
+
+
+
+Linn Standards Track [Page 90]
+
+RFC 2743 GSS-API January 2000
+
+
+ The enciphered secret key, along with an authenticator quantity
+ signed with the client's private key, is included in the output_token
+ from GSS_Init_sec_context(). The output_token also carries a
+ certification path, consisting of a certificate chain leading from
+ the service to the client; a variant approach would defer this path
+ resolution to be performed by the service instead of being asserted
+ by the client. The client application sends the output_token to the
+ service.
+
+ The service passes the received token as the input_token argument to
+ GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the
+ certification path, and as a result determines a certified binding
+ between the client's distinguished name and the client's public key.
+ Given that public key, GSS_Accept_sec_context() can process the
+ input_token's authenticator quantity and verify that the client's
+ private key was used to sign the input_token. At this point, the
+ client is authenticated to the service. The service uses its private
+ key to decipher the enciphered secret key provided to it for per-
+ message protection operations on the context.
+
+ The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which
+ causes per-message authentication, integrity, and (optional)
+ confidentiality facilities to be applied to that message. The service
+ uses the context's shared secret key to perform corresponding
+ GSS_VerifyMIC() and GSS_Unwrap() calls.
+
+6: Security Considerations
+
+ This document specifies a service interface for security facilities
+ and services; as such, security considerations are considered
+ throughout the specification. Nonetheless, it is appropriate to
+ summarize certain specific points relevant to GSS-API implementors
+ and calling applications. Usage of the GSS-API interface does not in
+ itself provide security services or assurance; instead, these
+ attributes are dependent on the underlying mechanism(s) which support
+ a GSS-API implementation. Callers must be attentive to the requests
+ made to GSS-API calls and to the status indicators returned by GSS-
+ API, as these specify the security service characteristics which
+ GSS-API will provide. When the interprocess context transfer
+ facility is used, appropriate local controls should be applied to
+ constrain access to interprocess tokens and to the sensitive data
+ which they contain.
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 91]
+
+RFC 2743 GSS-API January 2000
+
+
+7: Related Activities
+
+ In order to implement the GSS-API atop existing, emerging, and future
+ security mechanisms:
+
+ object identifiers must be assigned to candidate GSS-API
+ mechanisms and the name types which they support
+
+ concrete data element formats and processing procedures must be
+ defined for candidate mechanisms
+
+ Calling applications must implement formatting conventions which will
+ enable them to distinguish GSS-API tokens from other data carried in
+ their application protocols.
+
+ Concrete language bindings are required for the programming
+ environments in which the GSS-API is to be employed, as [RFC-1509]
+ defines for the C programming language and GSS-V1. C Language
+ bindings for GSS-V2 are defined in [RFC-2744].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 92]
+
+RFC 2743 GSS-API January 2000
+
+
+8: Referenced Documents
+
+ [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security
+ Architecture.
+
+ [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax
+ Notation One (ASN.1)".
+
+ [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules
+ for Abstract Syntax Notation One (ASN.1)".)
+
+ [RFC-1507]: Kaufman, C., "DASS: Distributed Authentication Security
+ Service", RFC 1507, September 1993.
+
+ [RFC-1508]: Linn, J., "Generic Security Service Application Program
+ Interface", RFC 1508, September 1993.
+
+ [RFC-1509]: Wray, J., "Generic Security Service API: C-bindings",
+ RFC 1509, September 1993.
+
+ [RFC-1964]: Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
+ RFC 1964, June 1996.
+
+ [RFC-2025]: Adams, C., "The Simple Public-Key GSS-API Mechanism
+ (SPKM)", RFC 2025, October 1996.
+
+ [RFC-2078]: Linn, J., "Generic Security Service Application Program
+ Interface, Version 2", RFC 2078, January 1997.
+
+ [RFC-2203]: Eisler, M., Chiu, A. and L. Ling, "RPCSEC_GSS Protocol
+ Specification", RFC 2203, September 1997.
+
+ [RFC-2744]: Wray, J., "Generic Security Service API Version 2 :
+ C-bindings", RFC 2744, January 2000.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 93]
+
+RFC 2743 GSS-API January 2000
+
+
+APPENDIX A
+
+MECHANISM DESIGN CONSTRAINTS
+
+ The following constraints on GSS-API mechanism designs are adopted in
+ response to observed caller protocol requirements, and adherence
+ thereto is anticipated in subsequent descriptions of GSS-API
+ mechanisms to be documented in standards-track Internet
+ specifications.
+
+ It is strongly recommended that mechanisms offering per-message
+ protection services also offer at least one of the replay detection
+ and sequencing services, as mechanisms offering neither of the latter
+ will fail to satisfy recognized requirements of certain candidate
+ caller protocols.
+
+APPENDIX B
+
+COMPATIBILITY WITH GSS-V1
+
+ It is the intent of this document to define an interface and
+ procedures which preserve compatibility between GSS-V1 [RFC-1508]
+ callers and GSS-V2 providers. All calls defined in GSS-V1 are
+ preserved, and it has been a goal that GSS-V1 callers should be able
+ to operate atop GSS-V2 provider implementations. Certain detailed
+ changes, summarized in this section, have been made in order to
+ resolve omissions identified in GSS-V1.
+
+ The following GSS-V1 constructs, while supported within GSS-V2, are
+ deprecated:
+
+ Names for per-message processing routines: GSS_Seal() deprecated
+ in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of
+ GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap();
+ GSS_Verify() deprecated in favor of GSS_VerifyMIC().
+
+ GSS_Delete_sec_context() facility for context_token usage,
+ allowing mechanisms to signal context deletion, is retained for
+ compatibility with GSS-V1. For current usage, it is recommended
+ that both peers to a context invoke GSS_Delete_sec_context()
+ independently, passing a null output_context_token buffer to
+ indicate that no context_token is required. Implementations of
+ GSS_Delete_sec_context() should delete relevant locally-stored
+ context information.
+
+ This GSS-V2 specification adds the following calls which are not
+ present in GSS-V1:
+
+
+
+
+Linn Standards Track [Page 94]
+
+RFC 2743 GSS-API January 2000
+
+
+ Credential management calls: GSS_Add_cred(),
+ GSS_Inquire_cred_by_mech().
+
+ Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(),
+ GSS_Export_sec_context(), GSS_Import_sec_context().
+
+ Per-message calls: No new calls. Existing calls have been
+ renamed.
+
+ Support calls: GSS_Create_empty_OID_set(),
+ GSS_Add_OID_set_member(), GSS_Test_OID_set_member(),
+ GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(),
+ GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name().
+
+ This GSS-V2 specification introduces three new facilities applicable
+ to security contexts, indicated using the following context state
+ values which are not present in GSS-V1:
+
+ anon_state, set TRUE to indicate that a context's initiator is
+ anonymous from the viewpoint of the target; Section 1.2.5 of this
+ specification provides a summary description of the GSS-V2
+ anonymity support facility, support and use of which is optional.
+
+ prot_ready_state, set TRUE to indicate that a context may be used
+ for per-message protection before final completion of context
+ establishment; Section 1.2.7 of this specification provides a
+ summary description of the GSS-V2 facility enabling mechanisms to
+ selectively permit per-message protection during context
+ establishment, support and use of which is optional.
+
+ trans_state, set TRUE to indicate that a context is transferable
+ to another process using the GSS-V2 GSS_Export_sec_context()
+ facility.
+
+ These state values are represented (at the C bindings level) in
+ positions within a bit vector which are unused in GSS-V1, and may be
+ safely ignored by GSS-V1 callers.
+
+ New conf_req_flag and integ_req_flag inputs are defined for
+ GSS_Init_sec_context(), primarily to provide information to
+ negotiating mechanisms. This introduces a compatibility issue with
+ GSS-V1 callers, discussed in section 2.2.1 of this specification.
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 95]
+
+RFC 2743 GSS-API January 2000
+
+
+ Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API
+ implementors in the following areas: implementation robustness,
+ credential management, behavior in multi-mechanism configurations,
+ naming support, and inclusion of optional sequencing services. The
+ token tagging facility as defined in GSS-V2, Section 3.1, is now
+ described directly in terms of octets to facilitate interoperable
+ implementation without general ASN.1 processing code; the
+ corresponding ASN.1 syntax, included for descriptive purposes, is
+ unchanged from that in GSS-V1. For use in conjunction with added
+ naming support facilities, a new Exported Name Object construct is
+ added. Additional name types are introduced in Section 4.
+
+ This GSS-V2 specification adds the following major_status values
+ which are not defined in GSS-V1:
+
+ GSS_S_BAD_QOP unsupported QOP value
+ GSS_S_UNAUTHORIZED operation unauthorized
+ GSS_S_UNAVAILABLE operation unavailable
+ GSS_S_DUPLICATE_ELEMENT duplicate credential element
+ requested
+ GSS_S_NAME_NOT_MN name contains multi-mechanism
+ elements
+ GSS_S_GAP_TOKEN skipped predecessor token(s)
+ detected
+
+ Of these added status codes, only two values are defined to be
+ returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by
+ GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by
+ GSS_VerifyMIC() and GSS_Unwrap()).
+
+ Additionally, GSS-V2 descriptions of certain calls present in GSS-V1
+ have been updated to allow return of additional major_status values
+ from the set as defined in GSS-V1: GSS_Inquire_cred() has
+ GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as
+ returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN,
+ GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and
+ GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable.
+
+APPENDIX C
+
+CHANGES RELATIVE TO RFC-2078
+
+ This document incorporates a number of changes relative to RFC-2078,
+ made primarily in response to implementation experience, for purposes
+ of alignment with the GSS-V2 C language bindings document, and to add
+ informative clarification. This section summarizes technical changes
+ incorporated.
+
+
+
+
+Linn Standards Track [Page 96]
+
+RFC 2743 GSS-API January 2000
+
+
+ General:
+
+ Clarified usage of object release routines, and incorporated
+ statement that some may be omitted within certain operating
+ environments.
+
+ Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID()
+ routines.
+
+ Clarified circumstances under which zero-length tokens may validly
+ exist as inputs and outputs to/from GSS-API calls.
+
+ Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG.
+
+ For GSS_Display_status(), deferred to language bindings the choice
+ of whether to return multiple status values in parallel or via
+ iteration, and added commentary deprecating return of
+ GSS_S_CONTINUE_NEEDED.
+
+ Adapted and incorporated clarifying material on optional service
+ support, delegation, and interprocess context transfer from C
+ bindings document.
+
+ Added and updated references to related documents, and to current
+ status of cited Kerberos mechanism OID.
+
+ Added general statement about GSS-API calls having no side effects
+ visible at the GSS-API level.
+
+ Context-related (including per-message protection issues):
+
+ Clarified GSS_Delete_sec_context() usage for partially-established
+ contexts.
+
+ Added clarification on GSS_Export_sec_context() and
+ GSS_Import_sec_context() behavior and context usage following an
+ export-import sequence.
+
+ Added informatory conf_req_flag, integ_req_flag inputs to
+ GSS_Init_sec_context(). (Note: this facility introduces a
+ backward incompatibility with GSS-V1 callers, discussed in Section
+ 2.2.1; this implication was recognized and accepted in working
+ group discussion.)
+
+ Stated that GSS_S_FAILURE is to be returned if
+ GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the
+ handle of a context which is already fully established.
+
+
+
+
+Linn Standards Track [Page 97]
+
+RFC 2743 GSS-API January 2000
+
+
+ Re GSS_Inquire_sec_context(), stated that src_name and targ_name
+ are not returned until GSS_S_COMPLETE status is reached; removed
+ use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED
+ lifetime return value); stated requirement to retain inquirable
+ data until context released by caller; added result value
+ indicating whether or not context is fully open.
+
+ Added discussion of interoperability conditions for mechanisms
+ permitting optional support of QOPs. Removed reference to
+ structured QOP elements in GSS_Verify_MIC().
+
+ Added discussion of use of GSS_S_DUPLICATE_TOKEN status to
+ indicate reflected per-message tokens.
+
+ Clarified use of informational sequencing codes from per-message
+ protection calls in conjunction with GSS_S_COMPLETE and
+ GSS_S_FAILURE major_status returns, adjusting status code
+ descriptions accordingly.
+
+ Added specific statements about impact of GSS_GetMIC() and
+ GSS_Wrap() failures on context state information, and generalized
+ existing statements about impact of processing failures on
+ received per-message tokens.
+
+ For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted
+ returned mech_type to be valid before GSS_S_COMPLETE, recognizing
+ that the value may change on successive continuation calls in the
+ negotiated mechanism case.
+
+ Deleted GSS_S_CONTEXT_EXPIRED status from
+ GSS_Import_sec_context().
+
+ Added conf_req_flag input to GSS_Wrap_size_limit().
+
+ Stated requirement for mechanisms' support of per-message
+ protection services to be usable concurrently in both directions
+ on a context.
+
+ Credential-related:
+
+ For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings
+ statement of likely non-support for INITIATE or BOTH credentials
+ if input name is neither empty nor a name resulting from applying
+ GSS_Inquire_cred() against the default credential. Further,
+ stated that an explicit name returned by GSS_Inquire_context()
+ should also be accepted. Added commentary about potentially
+ time-variant results of default resolution and attendant
+ implications. Aligned with C bindings re behavior when
+
+
+
+Linn Standards Track [Page 98]
+
+RFC 2743 GSS-API January 2000
+
+
+ GSS_C_NO_NAME provided for desired_name. In GSS_Acquire_cred(),
+ stated that NULL, rather than empty OID set, should be used for
+ desired_mechs in order to request default mechanism set.
+
+ Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for
+ GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED
+ as appropriate return for temporary, user-fixable credential
+ unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to
+ return GSS_S_NO_CRED if an authorization failure is encountered
+ upon credential acquisition.
+
+ Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message
+ protection, GSS_Context_time(), and GSS_Inquire_context() calls.
+
+ For GSS_Add_cred(), aligned with C bindings' description of
+ behavior when addition of elements to the default credential is
+ requested.
+
+ Upgraded recommended default credential resolution algorithm to
+ status of requirement for initiator credentials.
+
+ For GSS_Release_cred(), GSS_Inquire_cred(), and
+ GSS_Inquire_cred_by_mech(), clarified behavior for input
+ GSS_C_NO_CREDENTIAL.
+
+ Name-related:
+
+ Aligned GSS_Inquire_mechs_for_name() description with C bindings.
+
+ Removed GSS_S_BAD_NAMETYPE status return from
+ GSS_Duplicate_name(), GSS_Display_name(); constrained its
+ applicability for GSS_Compare_name().
+
+ Aligned with C bindings statement re GSS_Import_name() behavior
+ with GSS_C_NO_OID input name type, and stated that GSS-V2
+ mechanism specifications are to define processing procedures
+ applicable to their mechanisms. Also clarified GSS_C_NO_OID usage
+ with GSS_Display_name().
+
+ Downgraded reference to name canonicalization via DNS lookup to an
+ example.
+
+ For GSS_Canonicalize_name(), stated that neither negotiated
+ mechanisms nor the default mechanism are supported input
+ mech_types for this operation, and specified GSS_S_BAD_MECH status
+ to be returned in this case. Clarified that the
+ GSS_Canonicalize_name() operation is non-destructive to its input
+ name.
+
+
+
+Linn Standards Track [Page 99]
+
+RFC 2743 GSS-API January 2000
+
+
+ Clarified semantics of GSS_C_NT_USER_NAME name type.
+
+ Added descriptions of additional name types. Also added
+ discussion of GSS_C_NO_NAME and its constrained usage with
+ specific GSS calls.
+
+ Adapted and incorporated C bindings discussion about name
+ comparisons with exported name objects.
+
+ Added recommendation to mechanism designers for support of host-
+ based service name type, deferring any requirement statement to
+ individual mechanism specifications. Added discussion of host-
+ based service's service name element and proposed approach for
+ IANA registration policy therefor.
+
+ Clarified byte ordering within exported name object. Stated that
+ GSS_S_BAD_MECH is to be returned if, in the course of attempted
+ import of an exported name object, the name object's enclosed
+ mechanism type is unrecognized or unsupported.
+
+ Stated that mechanisms may optionally accept GSS_C_NO_NAME as an
+ input target name to GSS_Init_sec_context(), with comment that
+ such support is unlikely within mechanisms predating GSS-V2,
+ Update 1.
+
+AUTHOR'S ADDRESS
+
+ John Linn
+ RSA Laboratories
+ 20 Crosby Drive
+ Bedford, MA 01730 USA
+
+ Phone: +1 781.687.7817
+ EMail: jlinn@rsasecurity.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 100]
+
+RFC 2743 GSS-API January 2000
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linn Standards Track [Page 101]
+
diff --git a/crypto/heimdal/doc/standardisation/rfc2744.txt b/crypto/heimdal/doc/standardisation/rfc2744.txt
new file mode 100644
index 0000000..7f0c619
--- /dev/null
+++ b/crypto/heimdal/doc/standardisation/rfc2744.txt
@@ -0,0 +1,5659 @@
+
+
+
+
+
+
+Network Working Group J. Wray
+Request for Comments: 2744 Iris Associates
+Obsoletes: 1509 January 2000
+Category: Standards Track
+
+
+ Generic Security Service API Version 2 : C-bindings
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+Abstract
+
+ This document specifies C language bindings for Version 2, Update 1
+ of the Generic Security Service Application Program Interface (GSS-
+ API), which is described at a language-independent conceptual level
+ in RFC-2743 [GSSAPI]. It obsoletes RFC-1509, making specific
+ incremental changes in response to implementation experience and
+ liaison requests. It is intended, therefore, that this memo or a
+ successor version thereof will become the basis for subsequent
+ progression of the GSS-API specification on the standards track.
+
+ The Generic Security Service Application Programming Interface
+ provides security services to its callers, and is intended for
+ implementation atop a variety of underlying cryptographic mechanisms.
+ Typically, GSS-API callers will be application protocols into which
+ security enhancements are integrated through invocation of services
+ provided by the GSS-API. The GSS-API allows a caller application to
+ authenticate a principal identity associated with a peer application,
+ to delegate rights to a peer, and to apply security services such as
+ confidentiality and integrity on a per-message basis.
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 1]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+1. Introduction
+
+ The Generic Security Service Application Programming Interface
+ [GSSAPI] provides security services to calling applications. It
+ allows a communicating application to authenticate the user
+ associated with another application, to delegate rights to another
+ application, and to apply security services such as confidentiality
+ and integrity on a per-message basis.
+
+ There are four stages to using the GSS-API:
+
+ a) The application acquires a set of credentials with which it may
+ prove its identity to other processes. The application's
+ credentials vouch for its global identity, which may or may not be
+ related to any local username under which it may be running.
+
+ b) A pair of communicating applications establish a joint security
+ context using their credentials. The security context is a pair
+ of GSS-API data structures that contain shared state information,
+ which is required in order that per-message security services may
+ be provided. Examples of state that might be shared between
+ applications as part of a security context are cryptographic keys,
+ and message sequence numbers. As part of the establishment of a
+ security context, the context initiator is authenticated to the
+ responder, and may require that the responder is authenticated in
+ turn. The initiator may optionally give the responder the right
+ to initiate further security contexts, acting as an agent or
+ delegate of the initiator. This transfer of rights is termed
+ delegation, and is achieved by creating a set of credentials,
+ similar to those used by the initiating application, but which may
+ be used by the responder.
+
+ To establish and maintain the shared information that makes up the
+ security context, certain GSS-API calls will return a token data
+ structure, which is an opaque data type that may contain
+ cryptographically protected data. The caller of such a GSS-API
+ routine is responsible for transferring the token to the peer
+ application, encapsulated if necessary in an application-
+ application protocol. On receipt of such a token, the peer
+ application should pass it to a corresponding GSS-API routine
+ which will decode the token and extract the information, updating
+ the security context state information accordingly.
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 2]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ c) Per-message services are invoked to apply either:
+
+ integrity and data origin authentication, or confidentiality,
+ integrity and data origin authentication to application data,
+ which are treated by GSS-API as arbitrary octet-strings. An
+ application transmitting a message that it wishes to protect will
+ call the appropriate GSS-API routine (gss_get_mic or gss_wrap) to
+ apply protection, specifying the appropriate security context, and
+ send the resulting token to the receiving application. The
+ receiver will pass the received token (and, in the case of data
+ protected by gss_get_mic, the accompanying message-data) to the
+ corresponding decoding routine (gss_verify_mic or gss_unwrap) to
+ remove the protection and validate the data.
+
+ d) At the completion of a communications session (which may extend
+ across several transport connections), each application calls a
+ GSS-API routine to delete the security context. Multiple contexts
+ may also be used (either successively or simultaneously) within a
+ single communications association, at the option of the
+ applications.
+
+2. GSS-API Routines
+
+ This section lists the routines that make up the GSS-API, and
+ offers a brief description of the purpose of each routine.
+ Detailed descriptions of each routine are listed in alphabetical
+ order in section 5.
+
+ Table 2-1 GSS-API Credential-management Routines
+
+ Routine Section Function
+ ------- ------- --------
+ gss_acquire_cred 5.2 Assume a global identity; Obtain
+ a GSS-API credential handle for
+ pre-existing credentials.
+ gss_add_cred 5.3 Construct credentials
+ incrementally
+ gss_inquire_cred 5.21 Obtain information about a
+ credential
+ gss_inquire_cred_by_mech 5.22 Obtain per-mechanism information
+ about a credential.
+ gss_release_cred 5.27 Discard a credential handle.
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 3]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Table 2-2 GSS-API Context-Level Routines
+
+ Routine Section Function
+ ------- ------- --------
+ gss_init_sec_context 5.19 Initiate a security context with
+ a peer application
+ gss_accept_sec_context 5.1 Accept a security context
+ initiated by a
+ peer application
+ gss_delete_sec_context 5.9 Discard a security context
+ gss_process_context_token 5.25 Process a token on a security
+ context from a peer application
+ gss_context_time 5.7 Determine for how long a context
+ will remain valid
+ gss_inquire_context 5.20 Obtain information about a
+ security context
+ gss_wrap_size_limit 5.34 Determine token-size limit for
+ gss_wrap on a context
+ gss_export_sec_context 5.14 Transfer a security context to
+ another process
+ gss_import_sec_context 5.17 Import a transferred context
+
+
+ Table 2-3 GSS-API Per-message Routines
+
+ Routine Section Function
+ ------- ------- --------
+ gss_get_mic 5.15 Calculate a cryptographic message
+ integrity code (MIC) for a
+ message; integrity service
+ gss_verify_mic 5.32 Check a MIC against a message;
+ verify integrity of a received
+ message
+ gss_wrap 5.33 Attach a MIC to a message, and
+ optionally encrypt the message
+ content;
+ confidentiality service
+ gss_unwrap 5.31 Verify a message with attached
+ MIC, and decrypt message content
+ if necessary.
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 4]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Table 2-4 GSS-API Name manipulation Routines
+
+ Routine Section Function
+ ------- ------- --------
+ gss_import_name 5.16 Convert a contiguous string name
+ to internal-form
+ gss_display_name 5.10 Convert internal-form name to
+ text
+ gss_compare_name 5.6 Compare two internal-form names
+
+ gss_release_name 5.28 Discard an internal-form name
+ gss_inquire_names_for_mech 5.24 List the name-types supported by
+ the specified mechanism
+ gss_inquire_mechs_for_name 5.23 List mechanisms that support the
+ specified name-type
+ gss_canonicalize_name 5.5 Convert an internal name to an MN
+ gss_export_name 5.13 Convert an MN to export form
+ gss_duplicate_name 5.12 Create a copy of an internal name
+
+
+ Table 2-5 GSS-API Miscellaneous Routines
+
+ Routine Section Function
+ ------- ------- --------
+ gss_add_oid_set_member 5.4 Add an object identifier to
+ a set
+ gss_display_status 5.11 Convert a GSS-API status code
+ to text
+ gss_indicate_mechs 5.18 Determine available underlying
+ authentication mechanisms
+ gss_release_buffer 5.26 Discard a buffer
+ gss_release_oid_set 5.29 Discard a set of object
+ identifiers
+ gss_create_empty_oid_set 5.8 Create a set containing no
+ object identifiers
+ gss_test_oid_set_member 5.30 Determines whether an object
+ identifier is a member of a set.
+
+ Individual GSS-API implementations may augment these routines by
+ providing additional mechanism-specific routines if required
+ functionality is not available from the generic forms. Applications
+ are encouraged to use the generic routines wherever possible on
+ portability grounds.
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 5]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3. Data Types and Calling Conventions
+
+ The following conventions are used by the GSS-API C-language
+ bindings:
+
+3.1. Integer types
+
+ GSS-API uses the following integer data type:
+
+ OM_uint32 32-bit unsigned integer
+
+ Where guaranteed minimum bit-count is important, this portable data
+ type is used by the GSS-API routine definitions. Individual GSS-API
+ implementations will include appropriate typedef definitions to map
+ this type onto a built-in data type. If the platform supports the
+ X/Open xom.h header file, the OM_uint32 definition contained therein
+ should be used; the GSS-API header file in Appendix A contains logic
+ that will detect the prior inclusion of xom.h, and will not attempt
+ to re-declare OM_uint32. If the X/Open header file is not available
+ on the platform, the GSS-API implementation should use the smallest
+ natural unsigned integer type that provides at least 32 bits of
+ precision.
+
+3.2. String and similar data
+
+ Many of the GSS-API routines take arguments and return values that
+ describe contiguous octet-strings. All such data is passed between
+ the GSS-API and the caller using the gss_buffer_t data type. This
+ data type is a pointer to a buffer descriptor, which consists of a
+ length field that contains the total number of bytes in the datum,
+ and a value field which contains a pointer to the actual datum:
+
+ typedef struct gss_buffer_desc_struct {
+ size_t length;
+ void *value;
+ } gss_buffer_desc, *gss_buffer_t;
+
+ Storage for data returned to the application by a GSS-API routine
+ using the gss_buffer_t conventions is allocated by the GSS-API
+ routine. The application may free this storage by invoking the
+ gss_release_buffer routine. Allocation of the gss_buffer_desc object
+ is always the responsibility of the application; unused
+ gss_buffer_desc objects may be initialized to the value
+ GSS_C_EMPTY_BUFFER.
+
+
+
+
+
+
+
+Wray Standards Track [Page 6]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3.2.1. Opaque data types
+
+ Certain multiple-word data items are considered opaque data types at
+ the GSS-API, because their internal structure has no significance
+ either to the GSS-API or to the caller. Examples of such opaque data
+ types are the input_token parameter to gss_init_sec_context (which is
+ opaque to the caller), and the input_message parameter to gss_wrap
+ (which is opaque to the GSS-API). Opaque data is passed between the
+ GSS-API and the application using the gss_buffer_t datatype.
+
+3.2.2. Character strings
+
+ Certain multiple-word data items may be regarded as simple ISO
+ Latin-1 character strings. Examples are the printable strings passed
+ to gss_import_name via the input_name_buffer parameter. Some GSS-API
+ routines also return character strings. All such character strings
+ are passed between the application and the GSS-API implementation
+ using the gss_buffer_t datatype, which is a pointer to a
+ gss_buffer_desc object.
+
+ When a gss_buffer_desc object describes a printable string, the
+ length field of the gss_buffer_desc should only count printable
+ characters within the string. In particular, a trailing NUL
+ character should NOT be included in the length count, nor should
+ either the GSS-API implementation or the application assume the
+ presence of an uncounted trailing NUL.
+
+3.3. Object Identifiers
+
+ Certain GSS-API procedures take parameters of the type gss_OID, or
+ Object identifier. This is a type containing ISO-defined tree-
+ structured values, and is used by the GSS-API caller to select an
+ underlying security mechanism and to specify namespaces. A value of
+ type gss_OID has the following structure:
+
+ typedef struct gss_OID_desc_struct {
+ OM_uint32 length;
+ void *elements;
+ } gss_OID_desc, *gss_OID;
+
+ The elements field of this structure points to the first byte of an
+ octet string containing the ASN.1 BER encoding of the value portion
+ of the normal BER TLV encoding of the gss_OID. The length field
+ contains the number of bytes in this value. For example, the gss_OID
+ value corresponding to {iso(1) identified-organization(3) icd-
+ ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)},
+ meaning the DASS X.509 authentication mechanism, has a length field
+ of 7 and an elements field pointing to seven octets containing the
+
+
+
+Wray Standards Track [Page 7]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ following octal values: 53,14,2,207,163,7,5. GSS-API implementations
+ should provide constant gss_OID values to allow applications to
+ request any supported mechanism, although applications are encouraged
+ on portability grounds to accept the default mechanism. gss_OID
+ values should also be provided to allow applications to specify
+ particular name types (see section 3.10). Applications should treat
+ gss_OID_desc values returned by GSS-API routines as read-only. In
+ particular, the application should not attempt to deallocate them
+ with free(). The gss_OID_desc datatype is equivalent to the X/Open
+ OM_object_identifier datatype[XOM].
+
+3.4. Object Identifier Sets
+
+ Certain GSS-API procedures take parameters of the type gss_OID_set.
+ This type represents one or more object identifiers (section 2.3). A
+ gss_OID_set object has the following structure:
+
+ typedef struct gss_OID_set_desc_struct {
+ size_t count;
+ gss_OID elements;
+ } gss_OID_set_desc, *gss_OID_set;
+
+ The count field contains the number of OIDs within the set. The
+ elements field is a pointer to an array of gss_OID_desc objects, each
+ of which describes a single OID. gss_OID_set values are used to name
+ the available mechanisms supported by the GSS-API, to request the use
+ of specific mechanisms, and to indicate which mechanisms a given
+ credential supports.
+
+ All OID sets returned to the application by GSS-API are dynamic
+ objects (the gss_OID_set_desc, the "elements" array of the set, and
+ the "elements" array of each member OID are all dynamically
+ allocated), and this storage must be deallocated by the application
+ using the gss_release_oid_set() routine.
+
+3.5. Credentials
+
+ A credential handle is a caller-opaque atomic datum that identifies a
+ GSS-API credential data structure. It is represented by the caller-
+ opaque type gss_cred_id_t, which should be implemented as a pointer
+ or arithmetic type. If a pointer implementation is chosen, care must
+ be taken to ensure that two gss_cred_id_t values may be compared with
+ the == operator.
+
+ GSS-API credentials can contain mechanism-specific principal
+ authentication data for multiple mechanisms. A GSS-API credential is
+ composed of a set of credential-elements, each of which is applicable
+ to a single mechanism. A credential may contain at most one
+
+
+
+Wray Standards Track [Page 8]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ credential-element for each supported mechanism. A credential-element
+ identifies the data needed by a single mechanism to authenticate a
+ single principal, and conceptually contains two credential-references
+ that describe the actual mechanism-specific authentication data, one
+ to be used by GSS-API for initiating contexts, and one to be used
+ for accepting contexts. For mechanisms that do not distinguish
+ between acceptor and initiator credentials, both references would
+ point to the same underlying mechanism-specific authentication data.
+
+ Credentials describe a set of mechanism-specific principals, and give
+ their holder the ability to act as any of those principals. All
+ principal identities asserted by a single GSS-API credential should
+ belong to the same entity, although enforcement of this property is
+ an implementation-specific matter. The GSS-API does not make the
+ actual credentials available to applications; instead a credential
+ handle is used to identify a particular credential, held internally
+ by GSS-API. The combination of GSS-API credential handle and
+ mechanism identifies the principal whose identity will be asserted by
+ the credential when used with that mechanism.
+
+ The gss_init_sec_context and gss_accept_sec_context routines allow
+ the value GSS_C_NO_CREDENTIAL to be specified as their credential
+ handle parameter. This special credential-handle indicates a desire
+ by the application to act as a default principal. While individual
+ GSS-API implementations are free to determine such default behavior
+ as appropriate to the mechanism, the following default behavior by
+ these routines is recommended for portability:
+
+ gss_init_sec_context
+
+ 1) If there is only a single principal capable of initiating
+ security contexts for the chosen mechanism that the application
+ is authorized to act on behalf of, then that principal shall be
+ used, otherwise
+
+ 2) If the platform maintains a concept of a default network-
+ identity for the chosen mechanism, and if the application is
+ authorized to act on behalf of that identity for the purpose of
+ initiating security contexts, then the principal corresponding
+ to that identity shall be used, otherwise
+
+ 3) If the platform maintains a concept of a default local
+ identity, and provides a means to map local identities into
+ network-identities for the chosen mechanism, and if the
+ application is authorized to act on behalf of the network-
+ identity image of the default local identity for the purpose of
+
+
+
+
+
+Wray Standards Track [Page 9]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ initiating security contexts using the chosen mechanism, then
+ the principal corresponding to that identity shall be used,
+ otherwise
+
+ 4) A user-configurable default identity should be used.
+
+ gss_accept_sec_context
+
+ 1) If there is only a single authorized principal identity capable
+ of accepting security contexts for the chosen mechanism, then
+ that principal shall be used, otherwise
+
+ 2) If the mechanism can determine the identity of the target
+ principal by examining the context-establishment token, and if
+ the accepting application is authorized to act as that
+ principal for the purpose of accepting security contexts using
+ the chosen mechanism, then that principal identity shall be
+ used, otherwise
+
+ 3) If the mechanism supports context acceptance by any principal,
+ and if mutual authentication was not requested, any principal
+ that the application is authorized to accept security contexts
+ under using the chosen mechanism may be used, otherwise
+
+ 4)A user-configurable default identity shall be used.
+
+ The purpose of the above rules is to allow security contexts to be
+ established by both initiator and acceptor using the default behavior
+ wherever possible. Applications requesting default behavior are
+ likely to be more portable across mechanisms and platforms than ones
+ that use gss_acquire_cred to request a specific identity.
+
+3.6. Contexts
+
+ The gss_ctx_id_t data type contains a caller-opaque atomic value that
+ identifies one end of a GSS-API security context. It should be
+ implemented as a pointer or arithmetic type. If a pointer type is
+ chosen, care should be taken to ensure that two gss_ctx_id_t values
+ may be compared with the == operator.
+
+ The security context holds state information about each end of a peer
+ communication, including cryptographic state information.
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 10]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3.7. Authentication tokens
+
+ A token is a caller-opaque type that GSS-API uses to maintain
+ synchronization between the context data structures at each end of a
+ GSS-API security context. The token is a cryptographically protected
+ octet-string, generated by the underlying mechanism at one end of a
+ GSS-API security context for use by the peer mechanism at the other
+ end. Encapsulation (if required) and transfer of the token are the
+ responsibility of the peer applications. A token is passed between
+ the GSS-API and the application using the gss_buffer_t conventions.
+
+3.8. Interprocess tokens
+
+ Certain GSS-API routines are intended to transfer data between
+ processes in multi-process programs. These routines use a caller-
+ opaque octet-string, generated by the GSS-API in one process for use
+ by the GSS-API in another process. The calling application is
+ responsible for transferring such tokens between processes in an OS-
+ specific manner. Note that, while GSS-API implementors are
+ encouraged to avoid placing sensitive information within interprocess
+ tokens, or to cryptographically protect them, many implementations
+ will be unable to avoid placing key material or other sensitive data
+ within them. It is the application's responsibility to ensure that
+ interprocess tokens are protected in transit, and transferred only to
+ processes that are trustworthy. An interprocess token is passed
+ between the GSS-API and the application using the gss_buffer_t
+ conventions.
+
+3.9. Status values
+
+ Every GSS-API routine returns two distinct values to report status
+ information to the caller: GSS status codes and Mechanism status
+ codes.
+
+3.9.1. GSS status codes
+
+ GSS-API routines return GSS status codes as their OM_uint32 function
+ value. These codes indicate errors that are independent of the
+ underlying mechanism(s) used to provide the security service. The
+ errors that can be indicated via a GSS status code are either generic
+ API routine errors (errors that are defined in the GSS-API
+ specification) or calling errors (errors that are specific to these
+ language bindings).
+
+ A GSS status code can indicate a single fatal generic API error from
+ the routine and a single calling error. In addition, supplementary
+ status information may be indicated via the setting of bits in the
+ supplementary info field of a GSS status code.
+
+
+
+Wray Standards Track [Page 11]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ These errors are encoded into the 32-bit GSS status code as follows:
+
+ MSB LSB
+ |------------------------------------------------------------|
+ | Calling Error | Routine Error | Supplementary Info |
+ |------------------------------------------------------------|
+ Bit 31 24 23 16 15 0
+
+ Hence if a GSS-API routine returns a GSS status code whose upper 16
+ bits contain a non-zero value, the call failed. If the calling error
+ field is non-zero, the invoking application's call of the routine was
+ erroneous. Calling errors are defined in table 5-1. If the routine
+ error field is non-zero, the routine failed for one of the routine-
+ specific reasons listed below in table 5-2. Whether or not the upper
+ 16 bits indicate a failure or a success, the routine may indicate
+ additional information by setting bits in the supplementary info
+ field of the status code. The meaning of individual bits is listed
+ below in table 5-3.
+
+ Table 3-1 Calling Errors
+
+ Name Value in field Meaning
+ ---- -------------- -------
+ GSS_S_CALL_INACCESSIBLE_READ 1 A required input parameter
+ could not be read
+ GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output parameter
+ could not be written.
+ GSS_S_CALL_BAD_STRUCTURE 3 A parameter was malformed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 12]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Table 3-2 Routine Errors
+
+ Name Value in field Meaning
+ ---- -------------- -------
+ GSS_S_BAD_MECH 1 An unsupported mechanism
+ was requested
+ GSS_S_BAD_NAME 2 An invalid name was
+ supplied
+ GSS_S_BAD_NAMETYPE 3 A supplied name was of an
+ unsupported type
+ GSS_S_BAD_BINDINGS 4 Incorrect channel bindings
+ were supplied
+ GSS_S_BAD_STATUS 5 An invalid status code was
+ supplied
+ GSS_S_BAD_MIC GSS_S_BAD_SIG 6 A token had an invalid MIC
+ GSS_S_NO_CRED 7 No credentials were
+ supplied, or the
+ credentials were
+ unavailable or
+ inaccessible.
+ GSS_S_NO_CONTEXT 8 No context has been
+ established
+ GSS_S_DEFECTIVE_TOKEN 9 A token was invalid
+ GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid
+ GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials
+ have expired
+ GSS_S_CONTEXT_EXPIRED 12 The context has expired
+ GSS_S_FAILURE 13 Miscellaneous failure (see
+ text)
+ GSS_S_BAD_QOP 14 The quality-of-protection
+ requested could not be
+ provided
+ GSS_S_UNAUTHORIZED 15 The operation is forbidden
+ by local security policy
+ GSS_S_UNAVAILABLE 16 The operation or option is
+ unavailable
+ GSS_S_DUPLICATE_ELEMENT 17 The requested credential
+ element already exists
+ GSS_S_NAME_NOT_MN 18 The provided name was not a
+ mechanism name
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 13]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Table 3-3 Supplementary Status Bits
+
+ Name Bit Number Meaning
+ ---- ---------- -------
+ GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by
+ gss_init_sec_context or
+ gss_accept_sec_context. The
+ routine must be called again
+ to complete its function.
+ See routine documentation for
+ detailed description
+ GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of
+ an earlier token
+ GSS_S_OLD_TOKEN 2 The token's validity period
+ has expired
+ GSS_S_UNSEQ_TOKEN 3 A later token has already been
+ processed
+ GSS_S_GAP_TOKEN 4 An expected per-message token
+ was not received
+
+ The routine documentation also uses the name GSS_S_COMPLETE, which is
+ a zero value, to indicate an absence of any API errors or
+ supplementary information bits.
+
+ All GSS_S_xxx symbols equate to complete OM_uint32 status codes,
+ rather than to bitfield values. For example, the actual value of the
+ symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is
+ 3<<16. The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and
+ GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS
+ status code and removes all but the relevant field. For example, the
+ value obtained by applying GSS_ROUTINE_ERROR to a status code removes
+ the calling errors and supplementary info fields, leaving only the
+ routine errors field. The values delivered by these macros may be
+ directly compared with a GSS_S_xxx symbol of the appropriate type.
+ The macro GSS_ERROR() is also provided, which when applied to a GSS
+ status code returns a non-zero value if the status code indicated a
+ calling or routine error, and a zero value otherwise. All macros
+ defined by GSS-API evaluate their argument(s) exactly once.
+
+ A GSS-API implementation may choose to signal calling errors in a
+ platform-specific manner instead of, or in addition to the routine
+ value; routine errors and supplementary info should be returned via
+ major status values only.
+
+ The GSS major status code GSS_S_FAILURE is used to indicate that the
+ underlying mechanism detected an error for which no specific GSS
+ status code is defined. The mechanism-specific status code will
+ provide more details about the error.
+
+
+
+Wray Standards Track [Page 14]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3.9.2. Mechanism-specific status codes
+
+ GSS-API routines return a minor_status parameter, which is used to
+ indicate specialized errors from the underlying security mechanism.
+ This parameter may contain a single mechanism-specific error,
+ indicated by a OM_uint32 value.
+
+ The minor_status parameter will always be set by a GSS-API routine,
+ even if it returns a calling error or one of the generic API errors
+ indicated above as fatal, although most other output parameters may
+ remain unset in such cases. However, output parameters that are
+ expected to return pointers to storage allocated by a routine must
+ always be set by the routine, even in the event of an error, although
+ in such cases the GSS-API routine may elect to set the returned
+ parameter value to NULL to indicate that no storage was actually
+ allocated. Any length field associated with such pointers (as in a
+ gss_buffer_desc structure) should also be set to zero in such cases.
+
+3.10. Names
+
+ A name is used to identify a person or entity. GSS-API authenticates
+ the relationship between a name and the entity claiming the name.
+
+ Since different authentication mechanisms may employ different
+ namespaces for identifying their principals, GSSAPI's naming support
+ is necessarily complex in multi-mechanism environments (or even in
+ some single-mechanism environments where the underlying mechanism
+ supports multiple namespaces).
+
+ Two distinct representations are defined for names:
+
+ An internal form. This is the GSS-API "native" format for names,
+ represented by the implementation-specific gss_name_t type. It is
+ opaque to GSS-API callers. A single gss_name_t object may contain
+ multiple names from different namespaces, but all names should
+ refer to the same entity. An example of such an internal name
+ would be the name returned from a call to the gss_inquire_cred
+ routine, when applied to a credential containing credential
+ elements for multiple authentication mechanisms employing
+ different namespaces. This gss_name_t object will contain a
+ distinct name for the entity for each authentication mechanism.
+
+ For GSS-API implementations supporting multiple namespaces,
+ objects of type gss_name_t must contain sufficient information to
+ determine the namespace to which each primitive name belongs.
+
+
+
+
+
+
+Wray Standards Track [Page 15]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Mechanism-specific contiguous octet-string forms. A format
+ capable of containing a single name (from a single namespace).
+ Contiguous string names are always accompanied by an object
+ identifier specifying the namespace to which the name belongs, and
+ their format is dependent on the authentication mechanism that
+ employs the name. Many, but not all, contiguous string names will
+ be printable, and may therefore be used by GSS-API applications
+ for communication with their users.
+
+ Routines (gss_import_name and gss_display_name) are provided to
+ convert names between contiguous string representations and the
+ internal gss_name_t type. gss_import_name may support multiple
+ syntaxes for each supported namespace, allowing users the freedom to
+ choose a preferred name representation. gss_display_name should use
+ an implementation-chosen printable syntax for each supported name-
+ type.
+
+ If an application calls gss_display_name(), passing the internal name
+ resulting from a call to gss_import_name(), there is no guarantee the
+ the resulting contiguous string name will be the same as the original
+ imported string name. Nor do name-space identifiers necessarily
+ survive unchanged after a journey through the internal name-form. An
+ example of this might be a mechanism that authenticates X.500 names,
+ but provides an algorithmic mapping of Internet DNS names into X.500.
+ That mechanism's implementation of gss_import_name() might, when
+ presented with a DNS name, generate an internal name that contained
+ both the original DNS name and the equivalent X.500 name.
+ Alternatively, it might only store the X.500 name. In the latter
+ case, gss_display_name() would most likely generate a printable X.500
+ name, rather than the original DNS name.
+
+ The process of authentication delivers to the context acceptor an
+ internal name. Since this name has been authenticated by a single
+ mechanism, it contains only a single name (even if the internal name
+ presented by the context initiator to gss_init_sec_context had
+ multiple components). Such names are termed internal mechanism
+ names, or "MN"s and the names emitted by gss_accept_sec_context() are
+ always of this type. Since some applications may require MNs without
+ wanting to incur the overhead of an authentication operation, a
+ second function, gss_canonicalize_name(), is provided to convert a
+ general internal name into an MN.
+
+ Comparison of internal-form names may be accomplished via the
+ gss_compare_name() routine, which returns true if the two names being
+ compared refer to the same entity. This removes the need for the
+ application program to understand the syntaxes of the various
+ printable names that a given GSS-API implementation may support.
+ Since GSS-API assumes that all primitive names contained within a
+
+
+
+Wray Standards Track [Page 16]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ given internal name refer to the same entity, gss_compare_name() can
+ return true if the two names have at least one primitive name in
+ common. If the implementation embodies knowledge of equivalence
+ relationships between names taken from different namespaces, this
+ knowledge may also allow successful comparison of internal names
+ containing no overlapping primitive elements.
+
+ When used in large access control lists, the overhead of invoking
+ gss_import_name() and gss_compare_name() on each name from the ACL
+ may be prohibitive. As an alternative way of supporting this case,
+ GSS-API defines a special form of the contiguous string name which
+ may be compared directly (e.g. with memcmp()). Contiguous names
+ suitable for comparison are generated by the gss_export_name()
+ routine, which requires an MN as input. Exported names may be re-
+ imported by the gss_import_name() routine, and the resulting internal
+ name will also be an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME
+ indentifies the "export name" type, and the value of this constant is
+ given in Appendix A. Structurally, an exported name object consists
+ of a header containing an OID identifying the mechanism that
+ authenticated the name, and a trailer containing the name itself,
+ where the syntax of the trailer is defined by the individual
+ mechanism specification. The precise format of an export name is
+ defined in the language-independent GSS-API specification [GSSAPI].
+
+ Note that the results obtained by using gss_compare_name() will in
+ general be different from those obtained by invoking
+ gss_canonicalize_name() and gss_export_name(), and then comparing the
+ exported names. The first series of operation determines whether two
+ (unauthenticated) names identify the same principal; the second
+ whether a particular mechanism would authenticate them as the same
+ principal. These two operations will in general give the same
+ results only for MNs.
+
+ The gss_name_t datatype should be implemented as a pointer type. To
+ allow the compiler to aid the application programmer by performing
+ type-checking, the use of (void *) is discouraged. A pointer to an
+ implementation-defined type is the preferred choice.
+
+ Storage is allocated by routines that return gss_name_t values. A
+ procedure, gss_release_name, is provided to free storage associated
+ with an internal-form name.
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 17]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3.11. Channel Bindings
+
+ GSS-API supports the use of user-specified tags to identify a given
+ context to the peer application. These tags are intended to be used
+ to identify the particular communications channel that carries the
+ context. Channel bindings are communicated to the GSS-API using the
+ following structure:
+
+ typedef struct gss_channel_bindings_struct {
+ OM_uint32 initiator_addrtype;
+ gss_buffer_desc initiator_address;
+ OM_uint32 acceptor_addrtype;
+ gss_buffer_desc acceptor_address;
+ gss_buffer_desc application_data;
+ } *gss_channel_bindings_t;
+
+ The initiator_addrtype and acceptor_addrtype fields denote the type
+ of addresses contained in the initiator_address and acceptor_address
+ buffers. The address type should be one of the following:
+
+ GSS_C_AF_UNSPEC Unspecified address type
+ GSS_C_AF_LOCAL Host-local address type
+ GSS_C_AF_INET Internet address type (e.g. IP)
+ GSS_C_AF_IMPLINK ARPAnet IMP address type
+ GSS_C_AF_PUP pup protocols (eg BSP) address type
+ GSS_C_AF_CHAOS MIT CHAOS protocol address type
+ GSS_C_AF_NS XEROX NS address type
+ GSS_C_AF_NBS nbs address type
+ GSS_C_AF_ECMA ECMA address type
+ GSS_C_AF_DATAKIT datakit protocols address type
+ GSS_C_AF_CCITT CCITT protocols
+ GSS_C_AF_SNA IBM SNA address type
+ GSS_C_AF_DECnet DECnet address type
+ GSS_C_AF_DLI Direct data link interface address type
+ GSS_C_AF_LAT LAT address type
+ GSS_C_AF_HYLINK NSC Hyperchannel address type
+ GSS_C_AF_APPLETALK AppleTalk address type
+ GSS_C_AF_BSC BISYNC 2780/3780 address type
+ GSS_C_AF_DSS Distributed system services address type
+ GSS_C_AF_OSI OSI TP4 address type
+ GSS_C_AF_X25 X.25
+ GSS_C_AF_NULLADDR No address specified
+
+ Note that these symbols name address families rather than specific
+ addressing formats. For address families that contain several
+ alternative address forms, the initiator_address and acceptor_address
+ fields must contain sufficient information to determine which address
+
+
+
+
+Wray Standards Track [Page 18]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ form is used. When not otherwise specified, addresses should be
+ specified in network byte-order (that is, native byte-ordering for
+ the address family).
+
+ Conceptually, the GSS-API concatenates the initiator_addrtype,
+ initiator_address, acceptor_addrtype, acceptor_address and
+ application_data to form an octet string. The mechanism calculates a
+ MIC over this octet string, and binds the MIC to the context
+ establishment token emitted by gss_init_sec_context. The same
+ bindings are presented by the context acceptor to
+ gss_accept_sec_context, and a MIC is calculated in the same way. The
+ calculated MIC is compared with that found in the token, and if the
+ MICs differ, gss_accept_sec_context will return a GSS_S_BAD_BINDINGS
+ error, and the context will not be established. Some mechanisms may
+ include the actual channel binding data in the token (rather than
+ just a MIC); applications should therefore not use confidential data
+ as channel-binding components.
+
+ Individual mechanisms may impose additional constraints on addresses
+ and address types that may appear in channel bindings. For example,
+ a mechanism may verify that the initiator_address field of the
+ channel bindings presented to gss_init_sec_context contains the
+ correct network address of the host system. Portable applications
+ should therefore ensure that they either provide correct information
+ for the address fields, or omit addressing information, specifying
+ GSS_C_AF_NULLADDR as the address-types.
+
+3.12. Optional parameters
+
+ Various parameters are described as optional. This means that they
+ follow a convention whereby a default value may be requested. The
+ following conventions are used for omitted parameters. These
+ conventions apply only to those parameters that are explicitly
+ documented as optional.
+
+3.12.1. gss_buffer_t types
+
+ Specify GSS_C_NO_BUFFER as a value. For an input parameter this
+ signifies that default behavior is requested, while for an output
+ parameter it indicates that the information that would be returned
+ via the parameter is not required by the application.
+
+3.12.2. Integer types (input)
+
+ Individual parameter documentation lists values to be used to
+ indicate default actions.
+
+
+
+
+
+Wray Standards Track [Page 19]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+3.12.3. Integer types (output)
+
+ Specify NULL as the value for the pointer.
+
+3.12.4. Pointer types
+
+ Specify NULL as the value.
+
+3.12.5. Object IDs
+
+ Specify GSS_C_NO_OID as the value.
+
+3.12.6. Object ID Sets
+
+ Specify GSS_C_NO_OID_SET as the value.
+
+3.12.7. Channel Bindings
+
+ Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings
+ are not to be used.
+
+4. Additional Controls
+
+ This section discusses the optional services that a context initiator
+ may request of the GSS-API at context establishment. Each of these
+ services is requested by setting a flag in the req_flags input
+ parameter to gss_init_sec_context.
+
+ The optional services currently defined are:
+
+ Delegation - The (usually temporary) transfer of rights from
+ initiator to acceptor, enabling the acceptor to authenticate
+ itself as an agent of the initiator.
+
+ Mutual Authentication - In addition to the initiator authenticating
+ its identity to the context acceptor, the context acceptor should
+ also authenticate itself to the initiator.
+
+ Replay detection - In addition to providing message integrity
+ services, gss_get_mic and gss_wrap should include message
+ numbering information to enable gss_verify_mic and gss_unwrap to
+ detect if a message has been duplicated.
+
+ Out-of-sequence detection - In addition to providing message
+ integrity services, gss_get_mic and gss_wrap should include
+ message sequencing information to enable gss_verify_mic and
+ gss_unwrap to detect if a message has been received out of
+ sequence.
+
+
+
+Wray Standards Track [Page 20]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Anonymous authentication - The establishment of the security context
+ should not reveal the initiator's identity to the context
+ acceptor.
+
+ Any currently undefined bits within such flag arguments should be
+ ignored by GSS-API implementations when presented by an application,
+ and should be set to zero when returned to the application by the
+ GSS-API implementation.
+
+ Some mechanisms may not support all optional services, and some
+ mechanisms may only support some services in conjunction with others.
+ Both gss_init_sec_context and gss_accept_sec_context inform the
+ applications which services will be available from the context when
+ the establishment phase is complete, via the ret_flags output
+ parameter. In general, if the security mechanism is capable of
+ providing a requested service, it should do so, even if additional
+ services must be enabled in order to provide the requested service.
+ If the mechanism is incapable of providing a requested service, it
+ should proceed without the service, leaving the application to abort
+ the context establishment process if it considers the requested
+ service to be mandatory.
+
+ Some mechanisms may specify that support for some services is
+ optional, and that implementors of the mechanism need not provide it.
+ This is most commonly true of the confidentiality service, often
+ because of legal restrictions on the use of data-encryption, but may
+ apply to any of the services. Such mechanisms are required to send
+ at least one token from acceptor to initiator during context
+ establishment when the initiator indicates a desire to use such a
+ service, so that the initiating GSS-API can correctly indicate
+ whether the service is supported by the acceptor's GSS-API.
+
+4.1. Delegation
+
+ The GSS-API allows delegation to be controlled by the initiating
+ application via a boolean parameter to gss_init_sec_context(), the
+ routine that establishes a security context. Some mechanisms do not
+ support delegation, and for such mechanisms attempts by an
+ application to enable delegation are ignored.
+
+ The acceptor of a security context for which the initiator enabled
+ delegation will receive (via the delegated_cred_handle parameter of
+ gss_accept_sec_context) a credential handle that contains the
+ delegated identity, and this credential handle may be used to
+ initiate subsequent GSS-API security contexts as an agent or delegate
+ of the initiator. If the original initiator's identity is "A" and
+ the delegate's identity is "B", then, depending on the underlying
+ mechanism, the identity embodied by the delegated credential may be
+
+
+
+Wray Standards Track [Page 21]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ either "A" or "B acting for A".
+
+ For many mechanisms that support delegation, a simple boolean does
+ not provide enough control. Examples of additional aspects of
+ delegation control that a mechanism might provide to an application
+ are duration of delegation, network addresses from which delegation
+ is valid, and constraints on the tasks that may be performed by a
+ delegate. Such controls are presently outside the scope of the GSS-
+ API. GSS-API implementations supporting mechanisms offering
+ additional controls should provide extension routines that allow
+ these controls to be exercised (perhaps by modifying the initiator's
+ GSS-API credential prior to its use in establishing a context).
+ However, the simple delegation control provided by GSS-API should
+ always be able to over-ride other mechanism-specific delegation
+ controls - If the application instructs gss_init_sec_context() that
+ delegation is not desired, then the implementation must not permit
+ delegation to occur. This is an exception to the general rule that a
+ mechanism may enable services even if they are not requested -
+ delegation may only be provided at the explicit request of the
+ application.
+
+4.2. Mutual authentication
+
+ Usually, a context acceptor will require that a context initiator
+ authenticate itself so that the acceptor may make an access-control
+ decision prior to performing a service for the initiator. In some
+ cases, the initiator may also request that the acceptor authenticate
+ itself. GSS-API allows the initiating application to request this
+ mutual authentication service by setting a flag when calling
+ gss_init_sec_context.
+
+ The initiating application is informed as to whether or not the
+ context acceptor has authenticated itself. Note that some mechanisms
+ may not support mutual authentication, and other mechanisms may
+ always perform mutual authentication, whether or not the initiating
+ application requests it. In particular, mutual authentication my be
+ required by some mechanisms in order to support replay or out-of-
+ sequence message detection, and for such mechanisms a request for
+ either of these services will automatically enable mutual
+ authentication.
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 22]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+4.3. Replay and out-of-sequence detection
+
+ The GSS-API may provide detection of mis-ordered message once a
+ security context has been established. Protection may be applied to
+ messages by either application, by calling either gss_get_mic or
+ gss_wrap, and verified by the peer application by calling
+ gss_verify_mic or gss_unwrap.
+
+ gss_get_mic calculates a cryptographic MIC over an application
+ message, and returns that MIC in a token. The application should
+ pass both the token and the message to the peer application, which
+ presents them to gss_verify_mic.
+
+ gss_wrap calculates a cryptographic MIC of an application message,
+ and places both the MIC and the message inside a single token. The
+ Application should pass the token to the peer application, which
+ presents it to gss_unwrap to extract the message and verify the MIC.
+
+ Either pair of routines may be capable of detecting out-of-sequence
+ message delivery, or duplication of messages. Details of such mis-
+ ordered messages are indicated through supplementary status bits in
+ the major status code returned by gss_verify_mic or gss_unwrap. The
+ relevant supplementary bits are:
+
+ GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has
+ already been received and processed. Only
+ contexts that claim to provide replay detection
+ may set this bit.
+ GSS_S_OLD_TOKEN - The token is too old to determine whether or
+ not it is a duplicate. Contexts supporting
+ out-of-sequence detection but not replay
+ detection should always set this bit if
+ GSS_S_UNSEQ_TOKEN is set; contexts that support
+ replay detection should only set this bit if the
+ token is so old that it cannot be checked for
+ duplication.
+ GSS_S_UNSEQ_TOKEN - A later token has already been processed.
+ GSS_S_GAP_TOKEN - An earlier token has not yet been received.
+
+ A mechanism need not maintain a list of all tokens that have been
+ processed in order to support these status codes. A typical
+ mechanism might retain information about only the most recent "N"
+ tokens processed, allowing it to distinguish duplicates and missing
+ tokens within the most recent "N" messages; the receipt of a token
+ older than the most recent "N" would result in a GSS_S_OLD_TOKEN
+ status.
+
+
+
+
+
+Wray Standards Track [Page 23]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+4.4. Anonymous Authentication
+
+ In certain situations, an application may wish to initiate the
+ authentication process to authenticate a peer, without revealing its
+ own identity. As an example, consider an application providing
+ access to a database containing medical information, and offering
+ unrestricted access to the service. A client of such a service might
+ wish to authenticate the service (in order to establish trust in any
+ information retrieved from it), but might not wish the service to be
+ able to obtain the client's identity (perhaps due to privacy concerns
+ about the specific inquiries, or perhaps simply to avoid being placed
+ on mailing-lists).
+
+ In normal use of the GSS-API, the initiator's identity is made
+ available to the acceptor as a result of the context establishment
+ process. However, context initiators may request that their identity
+ not be revealed to the context acceptor. Many mechanisms do not
+ support anonymous authentication, and for such mechanisms the request
+ will not be honored. An authentication token will be still be
+ generated, but the application is always informed if a requested
+ service is unavailable, and has the option to abort context
+ establishment if anonymity is valued above the other security
+ services that would require a context to be established.
+
+ In addition to informing the application that a context is
+ established anonymously (via the ret_flags outputs from
+ gss_init_sec_context and gss_accept_sec_context), the optional
+ src_name output from gss_accept_sec_context and gss_inquire_context
+ will, for such contexts, return a reserved internal-form name,
+ defined by the implementation.
+
+ When presented to gss_display_name, this reserved internal-form name
+ will result in a printable name that is syntactically distinguishable
+ from any valid principal name supported by the implementation,
+ associated with a name-type object identifier with the value
+ GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The
+ printable form of an anonymous name should be chosen such that it
+ implies anonymity, since this name may appear in, for example, audit
+ logs. For example, the string "<anonymous>" might be a good choice,
+ if no valid printable names supported by the implementation can begin
+ with "<" and end with ">".
+
+4.5. Confidentiality
+
+ If a context supports the confidentiality service, gss_wrap may be
+ used to encrypt application messages. Messages are selectively
+ encrypted, under the control of the conf_req_flag input parameter to
+ gss_wrap.
+
+
+
+Wray Standards Track [Page 24]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+4.6. Inter-process context transfer
+
+ GSS-API V2 provides routines (gss_export_sec_context and
+ gss_import_sec_context) which allow a security context to be
+ transferred between processes on a single machine. The most common
+ use for such a feature is a client-server design where the server is
+ implemented as a single process that accepts incoming security
+ contexts, which then launches child processes to deal with the data
+ on these contexts. In such a design, the child processes must have
+ access to the security context data structure created within the
+ parent by its call to gss_accept_sec_context so that they can use
+ per-message protection services and delete the security context when
+ the communication session ends.
+
+ Since the security context data structure is expected to contain
+ sequencing information, it is impractical in general to share a
+ context between processes. Thus GSS-API provides a call
+ (gss_export_sec_context) that the process which currently owns the
+ context can call to declare that it has no intention to use the
+ context subsequently, and to create an inter-process token containing
+ information needed by the adopting process to successfully import the
+ context. After successful completion of gss_export_sec_context, the
+ original security context is made inaccessible to the calling process
+ by GSS-API, and any context handles referring to this context are no
+ longer valid. The originating process transfers the inter-process
+ token to the adopting process, which passes it to
+ gss_import_sec_context, and a fresh gss_ctx_id_t is created such that
+ it is functionally identical to the original context.
+
+ The inter-process token may contain sensitive data from the original
+ security context (including cryptographic keys). Applications using
+ inter-process tokens to transfer security contexts must take
+ appropriate steps to protect these tokens in transit.
+
+ Implementations are not required to support the inter-process
+ transfer of security contexts. The ability to transfer a security
+ context is indicated when the context is created, by
+ gss_init_sec_context or gss_accept_sec_context setting the
+ GSS_C_TRANS_FLAG bit in their ret_flags parameter.
+
+4.7. The use of incomplete contexts
+
+ Some mechanisms may allow the per-message services to be used before
+ the context establishment process is complete. For example, a
+ mechanism may include sufficient information in its initial context-
+ level token for the context acceptor to immediately decode messages
+ protected with gss_wrap or gss_get_mic. For such a mechanism, the
+ initiating application need not wait until subsequent context-level
+
+
+
+Wray Standards Track [Page 25]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ tokens have been sent and received before invoking the per-message
+ protection services.
+
+ The ability of a context to provide per-message services in advance
+ of complete context establishment is indicated by the setting of the
+ GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from
+ gss_init_sec_context and gss_accept_sec_context. Applications wishing
+ to use per-message protection services on partially-established
+ contexts should check this flag before attempting to invoke gss_wrap
+ or gss_get_mic.
+
+5. GSS-API Routine Descriptions
+
+ In addition to the explicit major status codes documented here, the
+ code GSS_S_FAILURE may be returned by any routine, indicating an
+ implementation-specific or mechanism-specific error condition,
+ further details of which are reported via the minor_status parameter.
+
+5.1. gss_accept_sec_context
+
+ OM_uint32 gss_accept_sec_context (
+ OM_uint32 *minor_status,
+ gss_ctx_id_t *context_handle,
+ const gss_cred_id_t acceptor_cred_handle,
+ const gss_buffer_t input_token_buffer,
+ const gss_channel_bindings_t input_chan_bindings,
+ const gss_name_t *src_name,
+ gss_OID *mech_type,
+ gss_buffer_t output_token,
+ OM_uint32 *ret_flags,
+ OM_uint32 *time_rec,
+ gss_cred_id_t *delegated_cred_handle)
+
+ Purpose:
+
+ Allows a remotely initiated security context between the application
+ and a remote peer to be established. The routine may return a
+ output_token which should be transferred to the peer application,
+ where the peer application will present it to gss_init_sec_context.
+ If no token need be sent, gss_accept_sec_context will indicate this
+ by setting the length field of the output_token argument to zero. To
+ complete the context establishment, one or more reply tokens may be
+ required from the peer application; if so, gss_accept_sec_context
+ will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it
+ should be called again when the reply token is received from the peer
+ application, passing the token to gss_accept_sec_context via the
+ input_token parameters.
+
+
+
+
+Wray Standards Track [Page 26]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Portable applications should be constructed to use the token length
+ and return status to determine whether a token needs to be sent or
+ waited for. Thus a typical portable caller should always invoke
+ gss_accept_sec_context within a loop:
+
+ gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
+
+ do {
+ receive_token_from_peer(input_token);
+ maj_stat = gss_accept_sec_context(&min_stat,
+ &context_hdl,
+ cred_hdl,
+ input_token,
+ input_bindings,
+ &client_name,
+ &mech_type,
+ output_token,
+ &ret_flags,
+ &time_rec,
+ &deleg_cred);
+ if (GSS_ERROR(maj_stat)) {
+ report_error(maj_stat, min_stat);
+ };
+ if (output_token->length != 0) {
+ send_token_to_peer(output_token);
+
+ gss_release_buffer(&min_stat, output_token);
+ };
+ if (GSS_ERROR(maj_stat)) {
+ if (context_hdl != GSS_C_NO_CONTEXT)
+ gss_delete_sec_context(&min_stat,
+ &context_hdl,
+ GSS_C_NO_BUFFER);
+ break;
+ };
+ } while (maj_stat & GSS_S_CONTINUE_NEEDED);
+
+ Whenever the routine returns a major status that includes the value
+ GSS_S_CONTINUE_NEEDED, the context is not fully established and the
+ following restrictions apply to the output parameters:
+
+ The value returned via the time_rec parameter is undefined Unless the
+ accompanying ret_flags parameter contains the bit
+ GSS_C_PROT_READY_FLAG, indicating that per-message services may be
+ applied in advance of a successful completion status, the value
+ returned via the mech_type parameter may be undefined until the
+ routine returns a major status value of GSS_S_COMPLETE.
+
+
+
+
+Wray Standards Track [Page 27]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ The values of the GSS_C_DELEG_FLAG,
+ GSS_C_MUTUAL_FLAG,GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG,
+ GSS_C_CONF_FLAG,GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned
+ via the ret_flags parameter should contain the values that the
+ implementation expects would be valid if context establishment were
+ to succeed.
+
+ The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
+ within ret_flags should indicate the actual state at the time
+ gss_accept_sec_context returns, whether or not the context is fully
+ established.
+
+ Although this requires that GSS-API implementations set the
+ GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
+ (i.e. when accompanied by a GSS_S_COMPLETE status code), applications
+ should not rely on this behavior as the flag was not defined in
+ Version 1 of the GSS-API. Instead, applications should be prepared to
+ use per-message services after a successful context establishment,
+ according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
+
+ All other bits within the ret_flags argument should be set to zero.
+ While the routine returns GSS_S_CONTINUE_NEEDED, the values returned
+ via the ret_flags argument indicate the services that the
+ implementation expects to be available from the established context.
+
+ If the initial call of gss_accept_sec_context() fails, the
+ implementation should not create a context object, and should leave
+ the value of the context_handle parameter set to GSS_C_NO_CONTEXT to
+ indicate this. In the event of a failure on a subsequent call, the
+ implementation is permitted to delete the "half-built" security
+ context (in which case it should set the context_handle parameter to
+ GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
+ security context (and the context_handle parameter) untouched for the
+ application to delete (using gss_delete_sec_context).
+
+ During context establishment, the informational status bits
+ GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
+ GSS-API mechanisms should always return them in association with a
+ routine error of GSS_S_FAILURE. This requirement for pairing did not
+ exist in version 1 of the GSS-API specification, so applications that
+ wish to run over version 1 implementations must special-case these
+ codes.
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 28]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ context_handle gss_ctx_id_t, read/modify context handle for new
+ context. Supply GSS_C_NO_CONTEXT for first
+ call; use value returned in subsequent calls.
+ Once gss_accept_sec_context() has returned a
+ value via this parameter, resources have been
+ assigned to the corresponding context, and must
+ be freed by the application after use with a
+ call to gss_delete_sec_context().
+
+
+ acceptor_cred_handle gss_cred_id_t, read Credential handle claimed
+ by context acceptor. Specify
+ GSS_C_NO_CREDENTIAL to accept the context as a
+ default principal. If GSS_C_NO_CREDENTIAL is
+ specified, but no default acceptor principal is
+ defined, GSS_S_NO_CRED will be returned.
+
+ input_token_buffer buffer, opaque, read token obtained from remote
+ application.
+
+ input_chan_bindings channel bindings, read, optional Application-
+ specified bindings. Allows application to
+ securely bind channel identification information
+ to the security context. If channel bindings
+ are not used, specify GSS_C_NO_CHANNEL_BINDINGS.
+
+ src_name gss_name_t, modify, optional Authenticated name
+ of context initiator. After use, this name
+ should be deallocated by passing it to
+ gss_release_name(). If not required, specify
+ NULL.
+
+ mech_type Object ID, modify, optional Security mechanism
+ used. The returned OID value will be a pointer
+ into static storage, and should be treated as
+ read-only by the caller (in particular, it does
+ not need to be freed). If not required, specify
+ NULL.
+
+ output_token buffer, opaque, modify Token to be passed to
+ peer application. If the length field of the
+ returned token buffer is 0, then no token need
+ be passed to the peer application. If a non-
+ zero length field is returned, the associated
+ storage must be freed after use by the
+ application with a call to gss_release_buffer().
+
+
+
+Wray Standards Track [Page 29]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ ret_flags bit-mask, modify, optional Contains various
+ independent flags, each of which indicates that
+ the context supports a specific service option.
+ If not needed, specify NULL. Symbolic names are
+ provided for each flag, and the symbolic names
+ corresponding to the required flags should be
+ logically-ANDed with the ret_flags value to test
+ whether a given option is supported by the
+ context. The flags are:
+ GSS_C_DELEG_FLAG
+ True - Delegated credentials are available
+ via the delegated_cred_handle
+ parameter
+ False - No credentials were delegated
+ GSS_C_MUTUAL_FLAG
+ True - Remote peer asked for mutual
+ authentication
+ False - Remote peer did not ask for mutual
+ authentication
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will not
+ be detected
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be
+ invoked by calling the gss_wrap
+ routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or
+ gss_wrap routines.
+ False - Per-message integrity service
+ unavailable.
+ GSS_C_ANON_FLAG
+ True - The initiator does not wish to
+ be authenticated; the src_name
+ parameter (if requested) contains
+
+
+
+Wray Standards Track [Page 30]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ an anonymous internal name.
+ False - The initiator has been
+ authenticated normally.
+ GSS_C_PROT_READY_FLAG
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ if the accompanying major status
+ return value is either GSS_S_COMPLETE
+ or GSS_S_CONTINUE_NEEDED.
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the accompanying major status
+ return value is GSS_S_COMPLETE.
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferable.
+ All other bits should be set to zero.
+
+ time_rec Integer, modify, optional
+ number of seconds for which the context will
+ remain valid. Specify NULL if not required.
+
+ delegated_cred_handle
+ gss_cred_id_t, modify, optional credential
+ handle for credentials received from context
+ initiator. Only valid if deleg_flag in
+ ret_flags is true, in which case an explicit
+ credential handle (i.e. not GSS_C_NO_CREDENTIAL)
+ will be returned; if deleg_flag is false,
+ gss_accept_context() will set this parameter to
+ GSS_C_NO_CREDENTIAL. If a credential handle is
+ returned, the associated resources must be
+ released by the application after use with a
+ call to gss_release_cred(). Specify NULL if not
+ required.
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ GSS_S_CONTINUE_NEEDED Indicates that a token from the peer
+ application is required to complete the
+ context, and that gss_accept_sec_context must
+ be called again with that token.
+
+
+
+Wray Standards Track [Page 31]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on
+ the input_token failed.
+
+ GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks
+ performed on the credential failed.
+
+ GSS_S_NO_CRED The supplied credentials were not valid for context
+ acceptance, or the credential handle did not
+ reference any credentials.
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
+
+ GSS_S_BAD_BINDINGS The input_token contains different channel
+ bindings to those specified via the
+ input_chan_bindings parameter.
+
+ GSS_S_NO_CONTEXT Indicates that the supplied context handle did not
+ refer to a valid context.
+
+ GSS_S_BAD_SIG The input_token contains an invalid MIC.
+
+ GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error
+ during context establishment.
+
+ GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of
+ a token already processed. This is a fatal
+ error during context establishment.
+
+ GSS_S_BAD_MECH The received token specified a mechanism that is
+ not supported by the implementation or the
+ provided credential.
+
+5.2. gss_acquire_cred
+
+ OM_uint32 gss_acquire_cred (
+ OM_uint32 *minor_status,
+ const gss_name_t desired_name,
+ OM_uint32 time_req,
+ const gss_OID_set desired_mechs,
+ gss_cred_usage_t cred_usage,
+ gss_cred_id_t *output_cred_handle,
+ gss_OID_set *actual_mechs,
+ OM_uint32 *time_rec)
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 32]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Purpose:
+
+ Allows an application to acquire a handle for a pre-existing
+ credential by name. GSS-API implementations must impose a local
+ access-control policy on callers of this routine to prevent
+ unauthorized callers from acquiring credentials to which they are not
+ entitled. This routine is not intended to provide a "login to the
+ network" function, as such a function would involve the creation of
+ new credentials rather than merely acquiring a handle to existing
+ credentials. Such functions, if required, should be defined in
+ implementation-specific extensions to the API.
+
+ If desired_name is GSS_C_NO_NAME, the call is interpreted as a
+ request for a credential handle that will invoke default behavior
+ when passed to gss_init_sec_context() (if cred_usage is
+ GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if
+ cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).
+
+ Mechanisms should honor the desired_mechs parameter, and return a
+ credential that is suitable to use only with the requested
+ mechanisms. An exception to this is the case where one underlying
+ credential element can be shared by multiple mechanisms; in this case
+ it is permissible for an implementation to indicate all mechanisms
+ with which the credential element may be used. If desired_mechs is
+ an empty set, behavior is undefined.
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways
+ of obtaining GSS-API initiator credentials from the system login
+ process. Some implementations may therefore not support the
+ acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
+ gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name
+ produced by applying either gss_inquire_cred to a valid credential,
+ or gss_inquire_context to an active context.
+
+ If credential acquisition is time-consuming for a mechanism, the
+ mechanism may choose to delay the actual acquisition until the
+ credential is required (e.g. by gss_init_sec_context or
+ gss_accept_sec_context). Such mechanism-specific implementation
+ decisions should be invisible to the calling application; thus a call
+ of gss_inquire_cred immediately following the call of
+ gss_acquire_cred must return valid credential data, and may therefore
+ incur the overhead of a deferred credential acquisition.
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 33]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ desired_name gss_name_t, read
+ Name of principal whose credential
+ should be acquired
+
+ time_req Integer, read, optional
+ number of seconds that credentials
+ should remain valid. Specify GSS_C_INDEFINITE
+ to request that the credentials have the maximum
+ permitted lifetime.
+
+ desired_mechs Set of Object IDs, read, optional
+ set of underlying security mechanisms that
+ may be used. GSS_C_NO_OID_SET may be used
+ to obtain an implementation-specific default.
+
+ cred_usage gss_cred_usage_t, read
+ GSS_C_BOTH - Credentials may be used
+ either to initiate or accept
+ security contexts.
+ GSS_C_INITIATE - Credentials will only be
+ used to initiate security contexts.
+ GSS_C_ACCEPT - Credentials will only be used to
+ accept security contexts.
+
+ output_cred_handle gss_cred_id_t, modify
+ The returned credential handle. Resources
+ associated with this credential handle must
+ be released by the application after use
+ with a call to gss_release_cred().
+
+ actual_mechs Set of Object IDs, modify, optional
+ The set of mechanisms for which the
+ credential is valid. Storage associated
+ with the returned OID-set must be released by
+ the application after use with a call to
+ gss_release_oid_set(). Specify NULL if not
+ required.
+
+ time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid. If the
+ implementation does not support expiration of
+ credentials, the value GSS_C_INDEFINITE will
+ be returned. Specify NULL if not required
+
+
+
+
+
+Wray Standards Track [Page 34]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_MECH Unavailable mechanism requested
+
+ GSS_S_BAD_NAMETYPE Type contained within desired_name parameter
+ is not supported
+
+ GSS_S_BAD_NAME Value supplied for desired_name parameter is ill
+ formed.
+
+ GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired
+ Because they have expired.
+
+ GSS_S_NO_CRED No credentials were found for the specified name.
+
+5.3. gss_add_cred
+
+ OM_uint32 gss_add_cred (
+ OM_uint32 *minor_status,
+ const gss_cred_id_t input_cred_handle,
+ const gss_name_t desired_name,
+ const gss_OID desired_mech,
+ gss_cred_usage_t cred_usage,
+ OM_uint32 initiator_time_req,
+ OM_uint32 acceptor_time_req,
+ gss_cred_id_t *output_cred_handle,
+ gss_OID_set *actual_mechs,
+ OM_uint32 *initiator_time_rec,
+ OM_uint32 *acceptor_time_rec)
+
+ Purpose:
+
+ Adds a credential-element to a credential. The credential-element is
+ identified by the name of the principal to which it refers. GSS-API
+ implementations must impose a local access-control policy on callers
+ of this routine to prevent unauthorized callers from acquiring
+ credential-elements to which they are not entitled. This routine is
+ not intended to provide a "login to the network" function, as such a
+ function would involve the creation of new mechanism-specific
+ authentication data, rather than merely acquiring a GSS-API handle to
+ existing data. Such functions, if required, should be defined in
+ implementation-specific extensions to the API.
+
+
+
+
+Wray Standards Track [Page 35]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ If desired_name is GSS_C_NO_NAME, the call is interpreted as a
+ request to add a credential element that will invoke default behavior
+ when passed to gss_init_sec_context() (if cred_usage is
+ GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if
+ cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways
+ of obtaining GSS-API initiator credentials from the system login
+ process. Some implementations may therefore not support the
+ acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
+ gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name
+ produced by applying either gss_inquire_cred to a valid credential,
+ or gss_inquire_context to an active context.
+
+ If credential acquisition is time-consuming for a mechanism, the
+ mechanism may choose to delay the actual acquisition until the
+ credential is required (e.g. by gss_init_sec_context or
+ gss_accept_sec_context). Such mechanism-specific implementation
+ decisions should be invisible to the calling application; thus a call
+ of gss_inquire_cred immediately following the call of gss_add_cred
+ must return valid credential data, and may therefore incur the
+ overhead of a deferred credential acquisition.
+
+ This routine can be used to either compose a new credential
+ containing all credential-elements of the original in addition to the
+ newly-acquire credential-element, or to add the new credential-
+ element to an existing credential. If NULL is specified for the
+ output_cred_handle parameter argument, the new credential-element
+ will be added to the credential identified by input_cred_handle; if a
+ valid pointer is specified for the output_cred_handle parameter, a
+ new credential handle will be created.
+
+ If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle,
+ gss_add_cred will compose a credential (and set the
+ output_cred_handle parameter accordingly) based on default behavior.
+ That is, the call will have the same effect as if the application had
+ first made a call to gss_acquire_cred(), specifying the same usage
+ and passing GSS_C_NO_NAME as the desired_name parameter to obtain an
+ explicit credential handle embodying default behavior, passed this
+ credential handle to gss_add_cred(), and finally called
+ gss_release_cred() on the first credential handle.
+
+ If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle
+ parameter, a non-NULL output_cred_handle must be supplied.
+
+
+
+
+
+
+Wray Standards Track [Page 36]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ input_cred_handle gss_cred_id_t, read, optional
+ The credential to which a credential-element
+ will be added. If GSS_C_NO_CREDENTIAL is
+ specified, the routine will compose the new
+ credential based on default behavior (see
+ description above). Note that, while the
+ credential-handle is not modified by
+ gss_add_cred(), the underlying credential
+ will be modified if output_credential_handle
+ is NULL.
+
+ desired_name gss_name_t, read.
+ Name of principal whose credential
+ should be acquired.
+
+ desired_mech Object ID, read
+ Underlying security mechanism with which the
+ credential may be used.
+
+ cred_usage gss_cred_usage_t, read
+ GSS_C_BOTH - Credential may be used
+ either to initiate or accept
+ security contexts.
+ GSS_C_INITIATE - Credential will only be
+ used to initiate security
+ contexts.
+ GSS_C_ACCEPT - Credential will only be used to
+ accept security contexts.
+
+ initiator_time_req Integer, read, optional
+ number of seconds that the credential
+ should remain valid for initiating security
+ contexts. This argument is ignored if the
+ composed credentials are of type GSS_C_ACCEPT.
+ Specify GSS_C_INDEFINITE to request that the
+ credentials have the maximum permitted
+ initiator lifetime.
+
+ acceptor_time_req Integer, read, optional
+ number of seconds that the credential
+ should remain valid for accepting security
+ contexts. This argument is ignored if the
+ composed credentials are of type GSS_C_INITIATE.
+
+
+
+Wray Standards Track [Page 37]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Specify GSS_C_INDEFINITE to request that the
+ credentials have the maximum permitted initiator
+ lifetime.
+
+ output_cred_handle gss_cred_id_t, modify, optional
+ The returned credential handle, containing
+ the new credential-element and all the
+ credential-elements from input_cred_handle.
+ If a valid pointer to a gss_cred_id_t is
+ supplied for this parameter, gss_add_cred
+ creates a new credential handle containing all
+ credential-elements from the input_cred_handle
+ and the newly acquired credential-element; if
+ NULL is specified for this parameter, the newly
+ acquired credential-element will be added
+ to the credential identified by input_cred_handle.
+
+ The resources associated with any credential
+ handle returned via this parameter must be
+ released by the application after use with a
+ call to gss_release_cred().
+
+ actual_mechs Set of Object IDs, modify, optional
+ The complete set of mechanisms for which
+ the new credential is valid. Storage for
+ the returned OID-set must be freed by the
+ application after use with a call to
+ gss_release_oid_set(). Specify NULL if
+ not required.
+
+ initiator_time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid for
+ initiating contexts using the specified
+ mechanism. If the implementation or mechanism
+ does not support expiration of credentials, the
+ value GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required
+
+ acceptor_time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid for
+ accepting security contexts using the specified
+ mechanism. If the implementation or mechanism
+ does not support expiration of credentials, the
+ value GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required
+
+
+
+
+Wray Standards Track [Page 38]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_MECH Unavailable mechanism requested
+
+ GSS_S_BAD_NAMETYPE Type contained within desired_name parameter
+ is not supported
+
+ GSS_S_BAD_NAME Value supplied for desired_name parameter is
+ ill-formed.
+
+ GSS_S_DUPLICATE_ELEMENT The credential already contains an element
+ for the requested mechanism with overlapping
+ usage and validity period.
+
+ GSS_S_CREDENTIALS_EXPIRED The required credentials could not be
+ added because they have expired.
+
+ GSS_S_NO_CRED No credentials were found for the specified name.
+
+5.4. gss_add_oid_set_member
+
+ OM_uint32 gss_add_oid_set_member (
+ OM_uint32 *minor_status,
+ const gss_OID member_oid,
+ gss_OID_set *oid_set)
+
+ Purpose:
+
+ Add an Object Identifier to an Object Identifier set. This routine
+ is intended for use in conjunction with gss_create_empty_oid_set when
+ constructing a set of mechanism OIDs for input to gss_acquire_cred.
+ The oid_set parameter must refer to an OID-set that was created by
+ GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API
+ creates a copy of the member_oid and inserts this copy into the set,
+ expanding the storage allocated to the OID-set's elements array if
+ necessary. The routine may add the new member OID anywhere within
+ the elements array, and implementations should verify that the new
+ member_oid is not already contained within the elements array; if the
+ member_oid is already present, the oid_set should remain unchanged.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+
+
+
+
+Wray Standards Track [Page 39]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ member_oid Object ID, read
+ The object identifier to copied into
+ the set.
+
+ oid_set Set of Object ID, modify
+ The set in which the object identifier
+ should be inserted.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.5. gss_canonicalize_name
+
+ OM_uint32 gss_canonicalize_name (
+ OM_uint32 *minor_status,
+ const gss_name_t input_name,
+ const gss_OID mech_type,
+ gss_name_t *output_name)
+
+ Purpose:
+
+ Generate a canonical mechanism name (MN) from an arbitrary internal
+ name. The mechanism name is the name that would be returned to a
+ context acceptor on successful authentication of a context where the
+ initiator used the input_name in a successful call to
+ gss_acquire_cred, specifying an OID set containing <mech_type> as its
+ only member, followed by a call to gss_init_sec_context, specifying
+ <mech_type> as the authentication mechanism.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name gss_name_t, read
+ The name for which a canonical form is
+ desired
+
+ mech_type Object ID, read
+ The authentication mechanism for which the
+ canonical form of the name is desired. The
+ desired mechanism must be specified explicitly;
+ no default is provided.
+
+
+
+
+
+
+
+Wray Standards Track [Page 40]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ output_name gss_name_t, modify
+ The resultant canonical name. Storage
+ associated with this name must be freed by
+ the application after use with a call to
+ gss_release_name().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion.
+
+ GSS_S_BAD_MECH The identified mechanism is not supported.
+
+ GSS_S_BAD_NAMETYPE The provided internal name contains no elements
+ that could be processed by the specified
+ mechanism.
+
+ GSS_S_BAD_NAME The provided internal name was ill-formed.
+
+5.6. gss_compare_name
+
+ OM_uint32 gss_compare_name (
+ OM_uint32 *minor_status,
+ const gss_name_t name1,
+ const gss_name_t name2,
+ int *name_equal)
+
+ Purpose:
+
+ Allows an application to compare two internal-form names to determine
+ whether they refer to the same entity.
+
+ If either name presented to gss_compare_name denotes an anonymous
+ principal, the routines should indicate that the two names do not
+ refer to the same identity.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ name1 gss_name_t, read
+ internal-form name
+
+ name2 gss_name_t, read
+ internal-form name
+
+
+
+
+
+
+Wray Standards Track [Page 41]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ name_equal boolean, modify
+ non-zero - names refer to same entity
+ zero - names refer to different entities
+ (strictly, the names are not known
+ to refer to the same identity).
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAMETYPE The two names were of incomparable types.
+
+ GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed.
+
+5.7. gss_context_time
+
+ OM_uint32 gss_context_time (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ OM_uint32 *time_rec)
+
+ Purpose:
+
+ Determines the number of seconds for which the specified context will
+ remain valid.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ Identifies the context to be interrogated.
+
+ time_rec Integer, modify
+ Number of seconds that the context will remain
+ valid. If the context has already expired,
+ zero will be returned.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTEXT_EXPIRED The context has already expired
+
+ GSS_S_NO_CONTEXT The context_handle parameter did not identify
+ a valid context
+
+
+
+
+Wray Standards Track [Page 42]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.8. gss_create_empty_oid_set
+
+ OM_uint32 gss_create_empty_oid_set (
+ OM_uint32 *minor_status,
+ gss_OID_set *oid_set)
+
+ Purpose:
+
+ Create an object-identifier set containing no object identifiers, to
+ which members may be subsequently added using the
+ gss_add_oid_set_member() routine. These routines are intended to be
+ used to construct sets of mechanism object identifiers, for input to
+ gss_acquire_cred.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ oid_set Set of Object IDs, modify
+ The empty object identifier set.
+ The routine will allocate the
+ gss_OID_set_desc object, which the
+ application must free after use with
+ a call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.9. gss_delete_sec_context
+
+ OM_uint32 gss_delete_sec_context (
+ OM_uint32 *minor_status,
+ gss_ctx_id_t *context_handle,
+ gss_buffer_t output_token)
+
+ Purpose:
+
+ Delete a security context. gss_delete_sec_context will delete the
+ local data structures associated with the specified security context,
+ and may generate an output_token, which when passed to the peer
+ gss_process_context_token will instruct it to do likewise. If no
+ token is required by the mechanism, the GSS-API should set the length
+ field of the output_token (if provided) to zero. No further security
+ services may be obtained using the context specified by
+ context_handle.
+
+
+
+
+Wray Standards Track [Page 43]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ In addition to deleting established security contexts,
+ gss_delete_sec_context must also be able to delete "half-built"
+ security contexts resulting from an incomplete sequence of
+ gss_init_sec_context()/gss_accept_sec_context() calls.
+
+ The output_token parameter is retained for compatibility with version
+ 1 of the GSS-API. It is recommended that both peer applications
+ invoke gss_delete_sec_context passing the value GSS_C_NO_BUFFER for
+ the output_token parameter, indicating that no token is required, and
+ that gss_delete_sec_context should simply delete local context data
+ structures. If the application does pass a valid buffer to
+ gss_delete_sec_context, mechanisms are encouraged to return a zero-
+ length token, indicating that no peer action is necessary, and that
+ no token should be transferred by the application.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ context_handle gss_ctx_id_t, modify
+ context handle identifying context to delete.
+ After deleting the context, the GSS-API will set
+ this context handle to GSS_C_NO_CONTEXT.
+
+ output_token buffer, opaque, modify, optional
+ token to be sent to remote application to
+ instruct it to also delete the context. It
+ is recommended that applications specify
+ GSS_C_NO_BUFFER for this parameter, requesting
+ local deletion only. If a buffer parameter is
+ provided by the application, the mechanism may
+ return a token in it; mechanisms that implement
+ only local deletion should set the length field of
+ this token to zero to indicate to the application
+ that no token is to be sent to the peer.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CONTEXT No valid context was supplied
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 44]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.10.gss_display_name
+
+ OM_uint32 gss_display_name (
+ OM_uint32 *minor_status,
+ const gss_name_t input_name,
+ gss_buffer_t output_name_buffer,
+ gss_OID *output_name_type)
+
+ Purpose:
+
+ Allows an application to obtain a textual representation of an opaque
+ internal-form name for display purposes. The syntax of a printable
+ name is defined by the GSS-API implementation.
+
+ If input_name denotes an anonymous principal, the implementation
+ should return the gss_OID value GSS_C_NT_ANONYMOUS as the
+ output_name_type, and a textual name that is syntactically distinct
+ from all valid supported printable names in output_name_buffer.
+
+ If input_name was created by a call to gss_import_name, specifying
+ GSS_C_NO_OID as the name-type, implementations that employ lazy
+ conversion between name types may return GSS_C_NO_OID via the
+ output_name_type parameter.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ input_name gss_name_t, read
+ name to be displayed
+
+ output_name_buffer buffer, character-string, modify
+ buffer to receive textual name string.
+ The application must free storage associated
+ with this name after use with a call to
+ gss_release_buffer().
+
+ output_name_type Object ID, modify, optional
+ The type of the returned name. The returned
+ gss_OID will be a pointer into static storage,
+ and should be treated as read-only by the caller
+ (in particular, the application should not attempt
+ to free it). Specify NULL if not required.
+
+
+
+
+
+
+
+Wray Standards Track [Page 45]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME input_name was ill-formed
+
+5.11.gss_display_status
+
+ OM_uint32 gss_display_status (
+ OM_uint32 *minor_status,
+ OM_uint32 status_value,
+ int status_type,
+ const gss_OID mech_type,
+ OM_uint32 *message_context,
+ gss_buffer_t status_string)
+
+ Purpose:
+
+ Allows an application to obtain a textual representation of a GSS-API
+ status code, for display to the user or for logging purposes. Since
+ some status values may indicate multiple conditions, applications may
+ need to call gss_display_status multiple times, each call generating
+ a single text string. The message_context parameter is used by
+ gss_display_status to store state information about which error
+ messages have already been extracted from a given status_value;
+ message_context must be initialized to 0 by the application prior to
+ the first call, and gss_display_status will return a non-zero value
+ in this parameter if there are further messages to extract.
+
+ The message_context parameter contains all state information required
+ by gss_display_status in order to extract further messages from the
+ status_value; even when a non-zero value is returned in this
+ parameter, the application is not required to call gss_display_status
+ again unless subsequent messages are desired. The following code
+ extracts all messages from a given status code and prints them to
+ stderr:
+
+ OM_uint32 message_context;
+ OM_uint32 status_code;
+ OM_uint32 maj_status;
+ OM_uint32 min_status;
+ gss_buffer_desc status_string;
+
+ ...
+
+ message_context = 0;
+
+ do {
+
+
+
+Wray Standards Track [Page 46]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ maj_status = gss_display_status (
+ &min_status,
+ status_code,
+ GSS_C_GSS_CODE,
+ GSS_C_NO_OID,
+ &message_context,
+ &status_string)
+
+ fprintf(stderr,
+ "%.*s\n",
+ (int)status_string.length,
+
+ (char *)status_string.value);
+
+ gss_release_buffer(&min_status, &status_string);
+
+ } while (message_context != 0);
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ status_value Integer, read
+ Status value to be converted
+
+ status_type Integer, read
+ GSS_C_GSS_CODE - status_value is a GSS status
+ code
+
+ GSS_C_MECH_CODE - status_value is a mechanism
+ status code
+
+ mech_type Object ID, read, optional
+ Underlying mechanism (used to interpret a
+ minor status value) Supply GSS_C_NO_OID to
+ obtain the system default.
+
+ message_context Integer, read/modify
+ Should be initialized to zero by the
+ application prior to the first call.
+ On return from gss_display_status(),
+ a non-zero status_value parameter indicates
+ that additional messages may be extracted
+ from the status code via subsequent calls
+
+
+
+
+
+Wray Standards Track [Page 47]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ to gss_display_status(), passing the same
+ status_value, status_type, mech_type, and
+ message_context parameters.
+
+ status_string buffer, character string, modify
+ textual interpretation of the status_value.
+ Storage associated with this parameter must
+ be freed by the application after use with
+ a call to gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_MECH Indicates that translation in accordance with
+ an unsupported mechanism type was requested
+
+ GSS_S_BAD_STATUS The status value was not recognized, or the
+ status type was neither GSS_C_GSS_CODE nor
+ GSS_C_MECH_CODE.
+
+5.12. gss_duplicate_name
+
+ OM_uint32 gss_duplicate_name (
+ OM_uint32 *minor_status,
+ const gss_name_t src_name,
+ gss_name_t *dest_name)
+
+ Purpose:
+
+ Create an exact duplicate of the existing internal name src_name.
+ The new dest_name will be independent of src_name (i.e. src_name and
+ dest_name must both be released, and the release of one shall not
+ affect the validity of the other).
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ src_name gss_name_t, read
+ internal name to be duplicated.
+
+ dest_name gss_name_t, modify
+ The resultant copy of <src_name>.
+ Storage associated with this name must
+ be freed by the application after use
+ with a call to gss_release_name().
+
+
+
+Wray Standards Track [Page 48]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The src_name parameter was ill-formed.
+
+5.13. gss_export_name
+
+ OM_uint32 gss_export_name (
+ OM_uint32 *minor_status,
+ const gss_name_t input_name,
+ gss_buffer_t exported_name)
+
+ Purpose:
+
+ To produce a canonical contiguous string representation of a
+ mechanism name (MN), suitable for direct comparison (e.g. with
+ memcmp) for use in authorization functions (e.g. matching entries in
+ an access-control list). The <input_name> parameter must specify a
+ valid MN (i.e. an internal name generated by gss_accept_sec_context
+ or by gss_canonicalize_name).
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name gss_name_t, read
+ The MN to be exported
+
+ exported_name gss_buffer_t, octet-string, modify
+ The canonical contiguous string form of
+ <input_name>. Storage associated with
+ this string must freed by the application
+ after use with gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NAME_NOT_MN The provided internal name was not a mechanism
+ name.
+
+ GSS_S_BAD_NAME The provided internal name was ill-formed.
+
+ GSS_S_BAD_NAMETYPE The internal name was of a type not supported
+ by the GSS-API implementation.
+
+
+
+
+Wray Standards Track [Page 49]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.14. gss_export_sec_context
+
+ OM_uint32 gss_export_sec_context (
+ OM_uint32 *minor_status,
+ gss_ctx_id_t *context_handle,
+ gss_buffer_t interprocess_token)
+
+ Purpose:
+
+ Provided to support the sharing of work between multiple processes.
+ This routine will typically be used by the context-acceptor, in an
+ application where a single process receives incoming connection
+ requests and accepts security contexts over them, then passes the
+ established context to one or more other processes for message
+ exchange. gss_export_sec_context() deactivates the security context
+ for the calling process and creates an interprocess token which, when
+ passed to gss_import_sec_context in another process, will re-activate
+ the context in the second process. Only a single instantiation of a
+ given context may be active at any one time; a subsequent attempt by
+ a context exporter to access the exported security context will fail.
+
+ The implementation may constrain the set of processes by which the
+ interprocess token may be imported, either as a function of local
+ security policy, or as a result of implementation decisions. For
+ example, some implementations may constrain contexts to be passed
+ only between processes that run under the same account, or which are
+ part of the same process group.
+
+ The interprocess token may contain security-sensitive information
+ (for example cryptographic keys). While mechanisms are encouraged to
+ either avoid placing such sensitive information within interprocess
+ tokens, or to encrypt the token before returning it to the
+ application, in a typical object-library GSS-API implementation this
+ may not be possible. Thus the application must take care to protect
+ the interprocess token, and ensure that any process to which the
+ token is transferred is trustworthy.
+
+ If creation of the interprocess token is successful, the
+ implementation shall deallocate all process-wide resources associated
+ with the security context, and set the context_handle to
+ GSS_C_NO_CONTEXT. In the event of an error that makes it impossible
+ to complete the export of the security context, the implementation
+ must not return an interprocess token, and should strive to leave the
+ security context referenced by the context_handle parameter
+ untouched. If this is impossible, it is permissible for the
+ implementation to delete the security context, providing it also sets
+ the context_handle parameter to GSS_C_NO_CONTEXT.
+
+
+
+
+Wray Standards Track [Page 50]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ context_handle gss_ctx_id_t, modify
+ context handle identifying the context to
+ transfer.
+
+ interprocess_token buffer, opaque, modify
+ token to be transferred to target process.
+ Storage associated with this token must be
+ freed by the application after use with a
+ call to gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTEXT_EXPIRED The context has expired
+
+ GSS_S_NO_CONTEXT The context was invalid
+
+ GSS_S_UNAVAILABLE The operation is not supported.
+
+5.15. gss_get_mic
+
+ OM_uint32 gss_get_mic (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ gss_qop_t qop_req,
+ const gss_buffer_t message_buffer,
+ gss_buffer_t msg_token)
+
+ Purpose:
+
+ Generates a cryptographic MIC for the supplied message, and places
+ the MIC in a token for transfer to the peer application. The qop_req
+ parameter allows a choice between several cryptographic algorithms,
+ if supported by the chosen mechanism.
+
+ Since some application-level protocols may wish to use tokens emitted
+ by gss_wrap() to provide "secure framing", implementations must
+ support derivation of MICs from zero-length messages.
+
+
+
+
+
+
+
+Wray Standards Track [Page 51]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ identifies the context on which the message
+ will be sent
+
+ qop_req gss_qop_t, read, optional
+ Specifies requested quality of protection.
+ Callers are encouraged, on portability grounds,
+ to accept the default quality of protection
+ offered by the chosen mechanism, which may be
+ requested by specifying GSS_C_QOP_DEFAULT for
+ this parameter. If an unsupported protection
+ strength is requested, gss_get_mic will return a
+ major_status of GSS_S_BAD_QOP.
+
+ message_buffer buffer, opaque, read
+ message to be protected
+
+ msg_token buffer, opaque, modify
+ buffer to receive token. The application must
+ free storage associated with this buffer after
+ use with a call to gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTEXT_EXPIRED The context has already expired
+
+ GSS_S_NO_CONTEXT The context_handle parameter did not identify
+ a valid context
+
+ GSS_S_BAD_QOP The specified QOP is not supported by the
+ mechanism.
+
+5.16. gss_import_name
+
+ OM_uint32 gss_import_name (
+ OM_uint32 *minor_status,
+ const gss_buffer_t input_name_buffer,
+ const gss_OID input_name_type,
+ gss_name_t *output_name)
+
+
+
+
+
+Wray Standards Track [Page 52]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Purpose:
+
+ Convert a contiguous string name to internal form. In general, the
+ internal name returned (via the <output_name> parameter) will not be
+ an MN; the exception to this is if the <input_name_type> indicates
+ that the contiguous string provided via the <input_name_buffer>
+ parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned
+ internal name will be an MN for the mechanism that exported the name.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name_buffer buffer, octet-string, read
+ buffer containing contiguous string name to convert
+
+ input_name_type Object ID, read, optional
+ Object ID specifying type of printable
+ name. Applications may specify either
+ GSS_C_NO_OID to use a mechanism-specific
+ default printable syntax, or an OID recognized
+ by the GSS-API implementation to name a
+ specific namespace.
+
+ output_name gss_name_t, modify
+ returned name in internal form. Storage
+ associated with this name must be freed
+ by the application after use with a call
+ to gss_release_name().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAMETYPE The input_name_type was unrecognized
+
+ GSS_S_BAD_NAME The input_name parameter could not be interpreted
+ as a name of the specified type
+
+ GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME,
+ but the mechanism contained within the
+ input-name is not supported
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 53]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.17. gss_import_sec_context
+
+ OM_uint32 gss_import_sec_context (
+ OM_uint32 *minor_status,
+ const gss_buffer_t interprocess_token,
+ gss_ctx_id_t *context_handle)
+
+ Purpose:
+
+ Allows a process to import a security context established by another
+ process. A given interprocess token may be imported only once. See
+ gss_export_sec_context.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ interprocess_token buffer, opaque, modify
+ token received from exporting process
+
+ context_handle gss_ctx_id_t, modify
+ context handle of newly reactivated context.
+ Resources associated with this context handle
+ must be released by the application after use
+ with a call to gss_delete_sec_context().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion.
+
+ GSS_S_NO_CONTEXT The token did not contain a valid context
+ reference.
+
+ GSS_S_DEFECTIVE_TOKEN The token was invalid.
+
+ GSS_S_UNAVAILABLE The operation is unavailable.
+
+ GSS_S_UNAUTHORIZED Local policy prevents the import of this context
+ by the current process.
+
+5.18. gss_indicate_mechs
+
+ OM_uint32 gss_indicate_mechs (
+ OM_uint32 *minor_status,
+ gss_OID_set *mech_set)
+
+
+
+
+
+Wray Standards Track [Page 54]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Purpose:
+
+ Allows an application to determine which underlying security
+ mechanisms are available.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ mech_set set of Object IDs, modify
+ set of implementation-supported mechanisms.
+ The returned gss_OID_set value will be a
+ dynamically-allocated OID set, that should
+ be released by the caller after use with a
+ call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.19. gss_init_sec_context
+
+ OM_uint32 gss_init_sec_context (
+ OM_uint32 *minor_status,
+ const gss_cred_id_t initiator_cred_handle,
+ gss_ctx_id_t *context_handle,\
+ const gss_name_t target_name,
+ const gss_OID mech_type,
+ OM_uint32 req_flags,
+ OM_uint32 time_req,
+ const gss_channel_bindings_t input_chan_bindings,
+ const gss_buffer_t input_token
+ gss_OID *actual_mech_type,
+ gss_buffer_t output_token,
+ OM_uint32 *ret_flags,
+ OM_uint32 *time_rec )
+
+ Purpose:
+
+ Initiates the establishment of a security context between the
+ application and a remote peer. Initially, the input_token parameter
+ should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
+ gss_buffer_desc object whose length field contains the value zero.
+ The routine may return a output_token which should be transferred to
+ the peer application, where the peer application will present it to
+ gss_accept_sec_context. If no token need be sent,
+ gss_init_sec_context will indicate this by setting the length field
+
+
+
+Wray Standards Track [Page 55]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ of the output_token argument to zero. To complete the context
+ establishment, one or more reply tokens may be required from the peer
+ application; if so, gss_init_sec_context will return a status
+ containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
+ In this case, gss_init_sec_context should be called again when the
+ reply token is received from the peer application, passing the reply
+ token to gss_init_sec_context via the input_token parameters.
+
+ Portable applications should be constructed to use the token length
+ and return status to determine whether a token needs to be sent or
+ waited for. Thus a typical portable caller should always invoke
+ gss_init_sec_context within a loop:
+
+ int context_established = 0;
+ gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
+ ...
+ input_token->length = 0;
+
+ while (!context_established) {
+ maj_stat = gss_init_sec_context(&min_stat,
+ cred_hdl,
+ &context_hdl,
+ target_name,
+ desired_mech,
+ desired_services,
+ desired_time,
+ input_bindings,
+ input_token,
+ &actual_mech,
+ output_token,
+ &actual_services,
+ &actual_time);
+ if (GSS_ERROR(maj_stat)) {
+ report_error(maj_stat, min_stat);
+ };
+
+ if (output_token->length != 0) {
+ send_token_to_peer(output_token);
+ gss_release_buffer(&min_stat, output_token)
+ };
+ if (GSS_ERROR(maj_stat)) {
+
+ if (context_hdl != GSS_C_NO_CONTEXT)
+ gss_delete_sec_context(&min_stat,
+ &context_hdl,
+ GSS_C_NO_BUFFER);
+ break;
+ };
+
+
+
+Wray Standards Track [Page 56]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ if (maj_stat & GSS_S_CONTINUE_NEEDED) {
+ receive_token_from_peer(input_token);
+ } else {
+ context_established = 1;
+ };
+ };
+
+ Whenever the routine returns a major status that includes the value
+ GSS_S_CONTINUE_NEEDED, the context is not fully established and the
+ following restrictions apply to the output parameters:
+
+ The value returned via the time_rec parameter is undefined Unless
+ the accompanying ret_flags parameter contains the bit
+ GSS_C_PROT_READY_FLAG, indicating that per-message services may be
+ applied in advance of a successful completion status, the value
+ returned via the actual_mech_type parameter is undefined until the
+ routine returns a major status value of GSS_S_COMPLETE.
+
+ The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
+ GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
+ GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
+ ret_flags parameter should contain the values that the
+ implementation expects would be valid if context establishment
+ were to succeed. In particular, if the application has requested
+ a service such as delegation or anonymous authentication via the
+ req_flags argument, and such a service is unavailable from the
+ underlying mechanism, gss_init_sec_context should generate a token
+ that will not provide the service, and indicate via the ret_flags
+ argument that the service will not be supported. The application
+ may choose to abort the context establishment by calling
+ gss_delete_sec_context (if it cannot continue in the absence of
+ the service), or it may choose to transmit the token and continue
+ context establishment (if the service was merely desired but not
+ mandatory).
+
+ The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
+ within ret_flags should indicate the actual state at the time
+ gss_init_sec_context returns, whether or not the context is fully
+ established.
+
+ GSS-API implementations that support per-message protection are
+ encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags
+ returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE
+ status code). However, applications should not rely on this
+ behavior as the flag was not defined in Version 1 of the GSS-API.
+ Instead, applications should determine what per-message services
+ are available after a successful context establishment according
+ to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
+
+
+
+Wray Standards Track [Page 57]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ All other bits within the ret_flags argument should be set to
+ zero.
+
+ If the initial call of gss_init_sec_context() fails, the
+ implementation should not create a context object, and should leave
+ the value of the context_handle parameter set to GSS_C_NO_CONTEXT to
+ indicate this. In the event of a failure on a subsequent call, the
+ implementation is permitted to delete the "half-built" security
+ context (in which case it should set the context_handle parameter to
+ GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
+ security context untouched for the application to delete (using
+ gss_delete_sec_context).
+
+ During context establishment, the informational status bits
+ GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
+ GSS-API mechanisms should always return them in association with a
+ routine error of GSS_S_FAILURE. This requirement for pairing did not
+ exist in version 1 of the GSS-API specification, so applications that
+ wish to run over version 1 implementations must special-case these
+ codes.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ initiator_cred_handle gss_cred_id_t, read, optional
+ handle for credentials claimed. Supply
+ GSS_C_NO_CREDENTIAL to act as a default
+ initiator principal. If no default
+ initiator is defined, the function will
+ return GSS_S_NO_CRED.
+
+ context_handle gss_ctx_id_t, read/modify
+ context handle for new context. Supply
+ GSS_C_NO_CONTEXT for first call; use value
+ returned by first call in continuation calls.
+ Resources associated with this context-handle
+ must be released by the application after use
+ with a call to gss_delete_sec_context().
+
+ target_name gss_name_t, read
+ Name of target
+
+ mech_type OID, read, optional
+ Object ID of desired mechanism. Supply
+ GSS_C_NO_OID to obtain an implementation
+ specific default
+
+
+
+Wray Standards Track [Page 58]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ req_flags bit-mask, read
+ Contains various independent flags, each of
+ which requests that the context support a
+ specific service option. Symbolic
+ names are provided for each flag, and the
+ symbolic names corresponding to the required
+ flags should be logically-ORed
+ together to form the bit-mask value. The
+ flags are:
+
+ GSS_C_DELEG_FLAG
+ True - Delegate credentials to remote peer
+ False - Don't delegate
+
+ GSS_C_MUTUAL_FLAG
+ True - Request that remote peer
+ authenticate itself
+ False - Authenticate self to remote peer
+ only
+
+ GSS_C_REPLAY_FLAG
+ True - Enable replay detection for
+ messages protected with gss_wrap
+ or gss_get_mic
+ False - Don't attempt to detect
+ replayed messages
+
+ GSS_C_SEQUENCE_FLAG
+ True - Enable detection of out-of-sequence
+ protected messages
+ False - Don't attempt to detect
+ out-of-sequence messages
+
+ GSS_C_CONF_FLAG
+ True - Request that confidentiality service
+ be made available (via gss_wrap)
+ False - No per-message confidentiality service
+ is required.
+
+ GSS_C_INTEG_FLAG
+ True - Request that integrity service be
+ made available (via gss_wrap or
+ gss_get_mic)
+ False - No per-message integrity service
+ is required.
+
+
+
+
+
+
+Wray Standards Track [Page 59]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_C_ANON_FLAG
+ True - Do not reveal the initiator's
+ identity to the acceptor.
+ False - Authenticate normally.
+
+ time_req Integer, read, optional
+ Desired number of seconds for which context
+ should remain valid. Supply 0 to request a
+ default validity period.
+
+ input_chan_bindings channel bindings, read, optional
+ Application-specified bindings. Allows
+ application to securely bind channel
+ identification information to the security
+ context. Specify GSS_C_NO_CHANNEL_BINDINGS
+ if channel bindings are not used.
+
+ input_token buffer, opaque, read, optional (see text)
+ Token received from peer application.
+ Supply GSS_C_NO_BUFFER, or a pointer to
+ a buffer containing the value GSS_C_EMPTY_BUFFER
+ on initial call.
+
+ actual_mech_type OID, modify, optional
+ Actual mechanism used. The OID returned via
+ this parameter will be a pointer to static
+ storage that should be treated as read-only;
+ In particular the application should not attempt
+ to free it. Specify NULL if not required.
+
+ output_token buffer, opaque, modify
+ token to be sent to peer application. If
+ the length field of the returned buffer is
+ zero, no token need be sent to the peer
+ application. Storage associated with this
+ buffer must be freed by the application
+ after use with a call to gss_release_buffer().
+
+ ret_flags bit-mask, modify, optional
+ Contains various independent flags, each of which
+ indicates that the context supports a specific
+ service option. Specify NULL if not
+ required. Symbolic names are provided
+ for each flag, and the symbolic names
+ corresponding to the required flags should be
+ logically-ANDed with the ret_flags value to test
+ whether a given option is supported by the
+ context. The flags are:
+
+
+
+Wray Standards Track [Page 60]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_C_DELEG_FLAG
+ True - Credentials were delegated to
+ the remote peer
+ False - No credentials were delegated
+
+ GSS_C_MUTUAL_FLAG
+ True - The remote peer has authenticated
+ itself.
+ False - Remote peer has not authenticated
+ itself.
+
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will
+ not be detected
+
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be
+ invoked by calling gss_wrap routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or gss_wrap
+ routines.
+ False - Per-message integrity service
+ unavailable.
+
+ GSS_C_ANON_FLAG
+ True - The initiator's identity has not been
+ revealed, and will not be revealed if
+ any emitted token is passed to the
+ acceptor.
+ False - The initiator's identity has been or
+ will be authenticated normally.
+
+ GSS_C_PROT_READY_FLAG
+
+
+
+Wray Standards Track [Page 61]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available for
+ use if the accompanying major status
+ return value is either GSS_S_COMPLETE or
+ GSS_S_CONTINUE_NEEDED.
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the accompanying major status
+ return value is GSS_S_COMPLETE.
+
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferable.
+
+ All other bits should be set to zero.
+
+ time_rec Integer, modify, optional
+ number of seconds for which the context
+ will remain valid. If the implementation does
+ not support context expiration, the value
+ GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTINUE_NEEDED Indicates that a token from the peer
+ application is required to complete the
+ context, and that gss_init_sec_context
+ must be called again with that token.
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
+ on the input_token failed
+
+ GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks
+ performed on the credential failed.
+
+ GSS_S_NO_CRED The supplied credentials were not valid for
+ context initiation, or the credential handle
+ did not reference any credentials.
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired
+
+
+
+Wray Standards Track [Page 62]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_S_BAD_BINDINGS The input_token contains different channel
+ bindings to those specified via the
+ input_chan_bindings parameter
+
+ GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC
+ that could not be verified
+
+ GSS_S_OLD_TOKEN The input_token was too old. This is a fatal
+ error during context establishment
+
+ GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate
+ of a token already processed. This is a
+ fatal error during context establishment.
+
+ GSS_S_NO_CONTEXT Indicates that the supplied context handle did
+ not refer to a valid context
+
+ GSS_S_BAD_NAMETYPE The provided target_name parameter contained an
+ invalid or unsupported type of name
+
+ GSS_S_BAD_NAME The provided target_name parameter was ill-formed.
+
+ GSS_S_BAD_MECH The specified mechanism is not supported by the
+ provided credential, or is unrecognized by the
+ implementation.
+
+5.20. gss_inquire_context
+
+ OM_uint32 gss_inquire_context (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ gss_name_t *src_name,
+ gss_name_t *targ_name,
+ OM_uint32 *lifetime_rec,
+ gss_OID *mech_type,
+ OM_uint32 *ctx_flags,
+ int *locally_initiated,
+ int *open )
+
+ Purpose:
+
+ 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.
+
+
+
+
+
+
+
+Wray Standards Track [Page 63]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ context_handle gss_ctx_id_t, read
+ A handle that refers to the security context.
+
+ src_name gss_name_t, modify, optional
+ The name of the context initiator.
+ If the context was established using anonymous
+ authentication, and if the application invoking
+ gss_inquire_context is the context acceptor,
+ an anonymous name will be returned. Storage
+ associated with this name must be freed by the
+ application after use with a call to
+ gss_release_name(). Specify NULL if not
+ required.
+
+ targ_name gss_name_t, modify, optional
+ The name of the context acceptor.
+ Storage associated with this name must be
+ freed by the application after use with a call
+ to gss_release_name(). If the context acceptor
+ did not authenticate itself, and if the initiator
+ did not specify a target name in its call to
+ gss_init_sec_context(), the value GSS_C_NO_NAME
+ will be returned. Specify NULL if not required.
+
+ lifetime_rec Integer, modify, optional
+ The number of seconds for which the context
+ will remain valid. If the context has
+ expired, this parameter will be set to zero.
+ If the implementation does not support
+ context expiration, the value
+ GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required.
+
+ mech_type gss_OID, modify, optional
+ The security mechanism providing the
+ context. The returned OID will be 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 NULL if not
+ required.
+
+
+
+
+
+Wray Standards Track [Page 64]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ ctx_flags bit-mask, modify, optional
+ Contains various independent flags, each of
+ which indicates that the context supports
+ (or is expected to support, if ctx_open is
+ false) a specific service option. If not
+ needed, specify NULL. Symbolic names are
+ provided for each flag, and the symbolic names
+ corresponding to the required flags
+ should be logically-ANDed with the ret_flags
+ value to test whether a given option is
+ supported by the context. The flags are:
+
+ GSS_C_DELEG_FLAG
+ True - Credentials were delegated from
+ the initiator to the acceptor.
+ False - No credentials were delegated
+
+ GSS_C_MUTUAL_FLAG
+ True - The acceptor was authenticated
+ to the initiator
+ False - The acceptor did not authenticate
+ itself.
+
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will not
+ be detected
+
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be invoked
+ by calling gss_wrap routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or gss_wrap
+ routines.
+
+
+
+Wray Standards Track [Page 65]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ False - Per-message integrity service
+ unavailable.
+
+ GSS_C_ANON_FLAG
+ True - The initiator's identity will not
+ be revealed to the acceptor.
+ The src_name parameter (if
+ requested) contains an anonymous
+ internal name.
+ False - The initiator has been
+ authenticated normally.
+
+ GSS_C_PROT_READY_FLAG
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ for use.
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the context is fully
+ established (i.e. if the open parameter
+ is non-zero).
+
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferable.
+
+ locally_initiated Boolean, modify
+ Non-zero if the invoking application is the
+ context initiator.
+ Specify NULL if not required.
+
+ open Boolean, modify
+ Non-zero if the context is fully established;
+ Zero if a context-establishment token
+ is expected from the peer application.
+ Specify NULL if not required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CONTEXT The referenced context could not be accessed.
+
+
+
+
+Wray Standards Track [Page 66]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.21. gss_inquire_cred
+
+ OM_uint32 gss_inquire_cred (
+ OM_uint32 *minor_status,
+ const gss_cred_id_t cred_handle,
+ gss_name_t *name,
+ OM_uint32 *lifetime,
+ gss_cred_usage_t *cred_usage,
+ gss_OID_set *mechanisms )
+
+ Purpose:
+
+ Obtains information about a credential.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ cred_handle gss_cred_id_t, read
+ A handle that refers to the target credential.
+ Specify GSS_C_NO_CREDENTIAL to inquire about
+ the default initiator principal.
+
+ name gss_name_t, modify, optional
+ The name whose identity the credential asserts.
+ Storage associated with this name should be freed
+ by the application after use with a call to
+ gss_release_name(). Specify NULL if not required.
+
+ lifetime Integer, modify, optional
+ The number of seconds for which the credential
+ will remain valid. If the credential has
+ expired, this parameter will be set to zero.
+ If the implementation does not support
+ credential expiration, the value
+ GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required.
+
+ cred_usage gss_cred_usage_t, modify, optional
+ How the credential may be used. One of the
+ following:
+ GSS_C_INITIATE
+ GSS_C_ACCEPT
+ GSS_C_BOTH
+ Specify NULL if not required.
+
+
+
+
+
+Wray Standards Track [Page 67]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ mechanisms gss_OID_set, modify, optional
+ Set of mechanisms supported by the credential.
+ Storage associated with this OID set must be
+ freed by the application after use with a call
+ to gss_release_oid_set(). Specify NULL if not
+ required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CRED The referenced credentials could not be accessed.
+
+ GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
+ If the lifetime parameter was not passed as NULL,
+ it will be set to 0.
+
+5.22. gss_inquire_cred_by_mech
+
+ OM_uint32 gss_inquire_cred_by_mech (
+ OM_uint32 *minor_status,
+ const gss_cred_id_t cred_handle,
+ const gss_OID mech_type,
+ gss_name_t *name,
+ OM_uint32 *initiator_lifetime,
+ OM_uint32 *acceptor_lifetime,
+ gss_cred_usage_t *cred_usage )
+
+ Purpose:
+
+ Obtains per-mechanism information about a credential.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ cred_handle gss_cred_id_t, read
+ A handle that refers to the target credential.
+ Specify GSS_C_NO_CREDENTIAL to inquire about
+ the default initiator principal.
+
+ mech_type gss_OID, read
+ The mechanism for which information should be
+ returned.
+
+
+
+
+Wray Standards Track [Page 68]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ name gss_name_t, modify, optional
+ The name whose identity the credential asserts.
+ Storage associated with this name must be
+ freed by the application after use with a call
+ to gss_release_name(). Specify NULL if not
+ required.
+
+ initiator_lifetime Integer, modify, optional
+ The number of seconds for which the credential
+ will remain capable of initiating security contexts
+ under the specified mechanism. If the credential
+ can no longer be used to initiate contexts, or if
+ the credential usage for this mechanism is
+ GSS_C_ACCEPT, this parameter will be set to zero.
+ If the implementation does not support expiration
+ of initiator credentials, the value
+ GSS_C_INDEFINITE will be returned. Specify NULL
+ if not required.
+
+ acceptor_lifetime Integer, modify, optional
+ The number of seconds for which the credential
+ will remain capable of accepting security contexts
+ under the specified mechanism. If the credential
+ can no longer be used to accept contexts, or if
+ the credential usage for this mechanism is
+ GSS_C_INITIATE, this parameter will be set to zero.
+
+ If the implementation does not support expiration
+ of acceptor credentials, the value GSS_C_INDEFINITE
+ will be returned. Specify NULL if not required.
+
+ cred_usage gss_cred_usage_t, modify, optional
+ How the credential may be used with the specified
+ mechanism. One of the following:
+ GSS_C_INITIATE
+ GSS_C_ACCEPT
+ GSS_C_BOTH
+ Specify NULL if not required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CRED The referenced credentials could not be accessed.
+
+ GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
+
+
+
+
+
+Wray Standards Track [Page 69]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
+ If the lifetime parameter was not passed as NULL,
+ it will be set to 0.
+
+5.23. gss_inquire_mechs_for_name
+
+ OM_uint32 gss_inquire_mechs_for_name (
+ OM_uint32 *minor_status,
+ const gss_name_t input_name,
+ gss_OID_set *mech_types )
+
+ Purpose:
+
+ Returns the set of mechanisms supported by the GSS-API implementation
+ that may be able to process the specified name.
+
+ Each mechanism returned will recognize at least one element within
+ the name. It is permissible for this routine to be implemented
+ within a mechanism-independent GSS-API layer, using the type
+ information contained within the presented name, and based on
+ registration information provided by individual mechanism
+ implementations. This means that the returned mech_types set may
+ indicate that a particular mechanism will understand the name when in
+ fact it would refuse to accept the name as input to
+ gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or
+ gss_add_cred (due to some property of the specific name, as opposed
+ to the name type). Thus this routine should be used only as a pre-
+ filter for a call to a subsequent mechanism-specific routine.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ input_name gss_name_t, read
+ The name to which the inquiry relates.
+
+ mech_types gss_OID_set, modify
+ Set of mechanisms that may support the
+ specified name. The returned OID set
+ must be freed by the caller after use
+ with a call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The input_name parameter was ill-formed.
+
+
+
+Wray Standards Track [Page 70]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or
+ unsupported type of name
+
+5.24. gss_inquire_names_for_mech
+
+ OM_uint32 gss_inquire_names_for_mech (
+ OM_uint32 *minor_status,
+ const gss_OID mechanism,
+ gss_OID_set *name_types)
+
+ Purpose:
+
+ Returns the set of nametypes supported by the specified mechanism.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ mechanism gss_OID, read
+ The mechanism to be interrogated.
+
+ name_types gss_OID_set, modify
+ Set of name-types supported by the specified
+ mechanism. The returned OID set must be
+ freed by the application after use with a
+ call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.25. gss_process_context_token
+
+ OM_uint32 gss_process_context_token (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ const gss_buffer_t token_buffer)
+
+ Purpose:
+
+ Provides a way to pass an asynchronous token to the security service.
+ Most context-level tokens are emitted and processed synchronously by
+ gss_init_sec_context and gss_accept_sec_context, and the application
+ is informed as to whether further tokens are expected by the
+ GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism
+ may need to emit a context-level token at a point when the peer
+ entity is not expecting a token. For example, the initiator's final
+
+
+
+Wray Standards Track [Page 71]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ call to gss_init_sec_context may emit a token and return a status of
+ GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may
+ fail. The acceptor's mechanism may wish to send a token containing
+ an error indication to the initiator, but the initiator is not
+ expecting a token at this point, believing that the context is fully
+ established. Gss_process_context_token provides a way to pass such a
+ token to the mechanism at any time.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ context handle of context on which token is to
+ be processed
+
+ token_buffer buffer, opaque, read
+ token to process
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
+ on the token failed
+
+ GSS_S_NO_CONTEXT The context_handle did not refer to a valid context
+
+5.26. gss_release_buffer
+
+ OM_uint32 gss_release_buffer (
+ OM_uint32 *minor_status,
+ gss_buffer_t buffer)
+
+ Purpose:
+
+ Free storage associated with a buffer. The storage must have been
+ allocated by a GSS-API routine. In addition to freeing the
+ associated storage, the routine will zero the length field in the
+ descriptor to which the buffer parameter refers, and implementations
+ are encouraged to additionally set the pointer field in the
+ descriptor to NULL. Any buffer object returned by a GSS-API routine
+ may be passed to gss_release_buffer (even if there is no storage
+ associated with the buffer).
+
+
+
+
+
+
+Wray Standards Track [Page 72]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ buffer buffer, modify
+ The storage associated with the buffer will be
+ deleted. The gss_buffer_desc object will not
+ be freed, but its length field will be zeroed.
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.27. gss_release_cred
+
+ OM_uint32 gss_release_cred (
+ OM_uint32 *minor_status,
+ gss_cred_id_t *cred_handle)
+
+ Purpose:
+
+ Informs GSS-API that the specified credential handle is no longer
+ required by the application, and frees associated resources.
+ Implementations are encouraged to set the cred_handle to
+ GSS_C_NO_CREDENTIAL on successful completion of this call.
+
+ Parameters:
+
+ cred_handle gss_cred_id_t, modify, optional
+ Opaque handle identifying credential
+ to be released. If GSS_C_NO_CREDENTIAL
+ is supplied, the routine will complete
+ successfully, but will do nothing.
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CRED Credentials could not be accessed.
+
+
+
+
+
+
+
+Wray Standards Track [Page 73]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.28. gss_release_name
+
+ OM_uint32 gss_release_name (
+ OM_uint32 *minor_status,
+ gss_name_t *name)
+
+ Purpose:
+
+ Free GSSAPI-allocated storage associated with an internal-form name.
+ Implementations are encouraged to set the name to GSS_C_NO_NAME on
+ successful completion of this call.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ name gss_name_t, modify
+ The name to be deleted
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The name parameter did not contain a valid name
+
+5.29. gss_release_oid_set
+
+ OM_uint32 gss_release_oid_set (
+ OM_uint32 *minor_status,
+ gss_OID_set *set)
+
+ Purpose:
+
+ Free storage associated with a GSSAPI-generated gss_OID_set object.
+ The set parameter must refer to an OID-set that was returned from a
+ GSS-API routine. gss_release_oid_set() will free the storage
+ associated with each individual member OID, the OID set's elements
+ array, and the gss_OID_set_desc.
+
+ Implementations are encouraged to set the gss_OID_set parameter to
+ GSS_C_NO_OID_SET on successful completion of this routine.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+
+
+
+Wray Standards Track [Page 74]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ set Set of Object IDs, modify
+ The storage associated with the gss_OID_set
+ will be deleted.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+5.30. gss_test_oid_set_member
+
+ OM_uint32 gss_test_oid_set_member (
+ OM_uint32 *minor_status,
+ const gss_OID member,
+ const gss_OID_set set,
+ int *present)
+
+ Purpose:
+
+ Interrogate an Object Identifier set to determine whether a specified
+ Object Identifier is a member. This routine is intended to be used
+ with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(),
+ and gss_inquire_cred(), but will also work with user-generated sets.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ member Object ID, read
+ The object identifier whose presence
+ is to be tested.
+
+ set Set of Object ID, read
+ The Object Identifier set.
+
+ present Boolean, modify
+ non-zero if the specified OID is a member
+ of the set, zero if not.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 75]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.31. gss_unwrap
+
+ OM_uint32 gss_unwrap (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ const gss_buffer_t input_message_buffer,
+ gss_buffer_t output_message_buffer,
+ int *conf_state,
+ gss_qop_t *qop_state)
+
+ Purpose:
+
+ Converts a message previously protected by gss_wrap back to a usable
+ form, verifying the embedded MIC. The conf_state parameter indicates
+ whether the message was encrypted; the qop_state parameter indicates
+ the strength of protection that was used to provide the
+ confidentiality and integrity services.
+
+ Since some application-level protocols may wish to use tokens emitted
+ by gss_wrap() to provide "secure framing", implementations must
+ support the wrapping and unwrapping of zero-length messages.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ context_handle gss_ctx_id_t, read
+ Identifies the context on which the message
+ arrived
+
+ input_message_buffer buffer, opaque, read
+ protected message
+
+ output_message_buffer buffer, opaque, modify
+ Buffer to receive unwrapped message.
+ Storage associated with this buffer must
+ be freed by the application after use use
+ with a call to gss_release_buffer().
+
+ conf_state boolean, modify, optional
+ Non-zero - Confidentiality and integrity
+ protection were used
+ Zero - Integrity service only was used
+ Specify NULL if not required
+
+
+
+
+
+
+Wray Standards Track [Page 76]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ qop_state gss_qop_t, modify, optional
+ Quality of protection provided.
+ Specify NULL if not required
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
+
+ GSS_S_BAD_SIG The MIC was incorrect
+
+ GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
+ MIC for the message, but it had already been
+ processed
+
+ GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC
+ for the message, but it is too old to check for
+ duplication.
+
+ GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
+ for the message, but has been verified out of
+ sequence; a later token has already been
+ received.
+
+ GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC
+ for the message, but has been verified out of
+ sequence; an earlier expected token has not yet
+ been received.
+
+ GSS_S_CONTEXT_EXPIRED The context has already expired
+
+ GSS_S_NO_CONTEXT The context_handle parameter did not identify
+ a valid context
+
+5.32. gss_verify_mic
+
+ OM_uint32 gss_verify_mic (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ const gss_buffer_t message_buffer,
+ const gss_buffer_t token_buffer,
+ gss_qop_t *qop_state)
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 77]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Purpose:
+
+ Verifies that a cryptographic MIC, contained in the token parameter,
+ fits the supplied message. The qop_state parameter allows a message
+ recipient to determine the strength of protection that was applied to
+ the message.
+
+ Since some application-level protocols may wish to use tokens emitted
+ by gss_wrap() to provide "secure framing", implementations must
+ support the calculation and verification of MICs over zero-length
+ messages.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ context_handle gss_ctx_id_t, read
+ Identifies the context on which the message
+ arrived
+
+ message_buffer buffer, opaque, read
+ Message to be verified
+
+ token_buffer buffer, opaque, read
+ Token associated with message
+
+ qop_state gss_qop_t, modify, optional
+ quality of protection gained from MIC
+ Specify NULL if not required
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
+
+ GSS_S_BAD_SIG The MIC was incorrect
+
+ GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
+ MIC for the message, but it had already been
+ processed
+
+ GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC
+ for the message, but it is too old to check for
+ duplication.
+
+
+
+
+
+Wray Standards Track [Page 78]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
+ for the message, but has been verified out of
+ sequence; a later token has already been received.
+
+ GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC
+ for the message, but has been verified out of
+ sequence; an earlier expected token has not yet
+ been received.
+
+ GSS_S_CONTEXT_EXPIRED The context has already expired
+
+ GSS_S_NO_CONTEXT The context_handle parameter did not identify a
+ valid context
+
+5.33. gss_wrap
+
+ OM_uint32 gss_wrap (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ int conf_req_flag,
+ gss_qop_t qop_req
+ const gss_buffer_t input_message_buffer,
+ int *conf_state,
+ gss_buffer_t output_message_buffer )
+
+ Purpose:
+
+ Attaches a cryptographic MIC and optionally encrypts the specified
+ input_message. The output_message contains both the MIC and the
+ message. The qop_req parameter allows a choice between several
+ cryptographic algorithms, if supported by the chosen mechanism.
+
+ Since some application-level protocols may wish to use tokens emitted
+ by gss_wrap() to provide "secure framing", implementations must
+ support the wrapping of zero-length messages.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ context_handle gss_ctx_id_t, read
+ Identifies the context on which the message
+ will be sent
+
+
+
+
+
+
+
+Wray Standards Track [Page 79]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ conf_req_flag boolean, read
+ Non-zero - Both confidentiality and integrity
+ services are requested
+ Zero - Only integrity service is requested
+
+ qop_req gss_qop_t, read, optional
+ Specifies required quality of protection. A
+ mechanism-specific default may be requested by
+ setting qop_req to GSS_C_QOP_DEFAULT. If an
+ unsupported protection strength is requested,
+ gss_wrap will return a major_status of
+ GSS_S_BAD_QOP.
+
+ input_message_buffer buffer, opaque, read
+ Message to be protected
+
+ conf_state boolean, modify, optional
+ Non-zero - Confidentiality, data origin
+ authentication and integrity
+ services have been applied
+ Zero - Integrity and data origin services only
+ has been applied.
+ Specify NULL if not required
+
+ output_message_buffer buffer, opaque, modify
+ Buffer to receive protected message.
+ Storage associated with this message must
+ be freed by the application after use with
+ a call to gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTEXT_EXPIRED The context has already expired
+
+ GSS_S_NO_CONTEXT The context_handle parameter did not identify a
+ valid context
+
+ GSS_S_BAD_QOP The specified QOP is not supported by the
+ mechanism.
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 80]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+5.34. gss_wrap_size_limit
+
+ OM_uint32 gss_wrap_size_limit (
+ OM_uint32 *minor_status,
+ const gss_ctx_id_t context_handle,
+ int conf_req_flag,
+ gss_qop_t qop_req,
+ OM_uint32 req_output_size,
+ OM_uint32 *max_input_size)
+
+ Purpose:
+
+ Allows an application to determine the maximum message size that, if
+ presented to gss_wrap with the same conf_req_flag and qop_req
+ parameters, will result in an output token containing no more than
+ req_output_size bytes.
+
+ This call is intended for use by applications that communicate over
+ protocols that impose a maximum message size. It enables the
+ application to fragment messages prior to applying protection.
+
+ GSS-API implementations are recommended but not required to detect
+ invalid QOP values when gss_wrap_size_limit() is called. This routine
+ guarantees only a maximum message size, not the availability of
+ specific QOP values for message protection.
+
+ Successful completion of this call does not guarantee that gss_wrap
+ will be able to protect a message of length max_input_size bytes,
+ since this ability may depend on the availability of system resources
+ at the time that gss_wrap is called. However, if the implementation
+ itself imposes an upper limit on the length of messages that may be
+ processed by gss_wrap, the implementation should not return a value
+ via max_input_bytes that is greater than this length.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ context_handle gss_ctx_id_t, read
+ A handle that refers to the security over
+ which the messages will be sent.
+
+ conf_req_flag Boolean, read
+ Indicates whether gss_wrap will be asked
+ to apply confidentiality protection in
+
+
+
+
+
+Wray Standards Track [Page 81]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ addition to integrity protection. See
+ the routine description for gss_wrap
+ for more details.
+
+ qop_req gss_qop_t, read
+ Indicates the level of protection that
+ gss_wrap will be asked to provide. See
+ the routine description for gss_wrap for
+ more details.
+
+ req_output_size Integer, read
+ The desired maximum size for tokens emitted
+ by gss_wrap.
+
+ max_input_size Integer, modify
+ The maximum input message size that may
+ be presented to gss_wrap in order to
+ guarantee that the emitted token shall
+ be no larger than req_output_size bytes.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CONTEXT The referenced context could not be accessed.
+
+ GSS_S_CONTEXT_EXPIRED The context has expired.
+
+ GSS_S_BAD_QOP The specified QOP is not supported by the
+ mechanism.
+
+6. Security Considerations
+
+ This document specifies a service interface for security facilities
+ and services; as such, security considerations appear throughout the
+ specification. Nonetheless, it is appropriate to summarize certain
+ specific points relevant to GSS-API implementors and calling
+ applications. Usage of the GSS-API interface does not in itself
+ provide security services or assurance; instead, these attributes are
+ dependent on the underlying mechanism(s) which support a GSS-API
+ implementation. Callers must be attentive to the requests made to
+ GSS-API calls and to the status indicators returned by GSS-API, as
+ these specify the security service characteristics which GSS-API will
+ provide. When the interprocess context transfer facility is used,
+ appropriate local controls should be applied to constrain access to
+ interprocess tokens and to the sensitive data which they contain.
+
+
+
+
+
+Wray Standards Track [Page 82]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ Appendix A. GSS-API C header file gssapi.h
+
+ C-language GSS-API implementations should include a copy of the
+ following header-file.
+
+ #ifndef GSSAPI_H_
+ #define GSSAPI_H_
+
+
+
+ /*
+ * First, include stddef.h to get size_t defined.
+ */
+ #include <stddef.h>
+
+ /*
+ * If the platform supports the xom.h header file, it should be
+ * included here.
+ */
+ #include <xom.h>
+
+
+ /*
+ * Now define the three implementation-dependent types.
+ */
+ typedef <platform-specific> gss_ctx_id_t;
+ typedef <platform-specific> gss_cred_id_t;
+ typedef <platform-specific> gss_name_t;
+
+ /*
+ * The following type must be defined as the smallest natural
+ * unsigned integer supported by the platform that has at least
+ * 32 bits of precision.
+ */
+ typedef <platform-specific> gss_uint32;
+
+
+ #ifdef OM_STRING
+ /*
+ * We have included the xom.h header file. Verify that OM_uint32
+ * is defined correctly.
+ */
+
+ #if sizeof(gss_uint32) != sizeof(OM_uint32)
+ #error Incompatible definition of OM_uint32 from xom.h
+ #endif
+
+ typedef OM_object_identifier gss_OID_desc, *gss_OID;
+
+
+
+Wray Standards Track [Page 83]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ #else
+
+ /*
+ * We can't use X/Open definitions, so roll our own.
+ */
+
+ typedef gss_uint32 OM_uint32;
+
+ typedef struct gss_OID_desc_struct {
+ OM_uint32 length;
+ void *elements;
+ } gss_OID_desc, *gss_OID;
+
+ #endif
+
+ typedef struct gss_OID_set_desc_struct {
+ size_t count;
+ gss_OID elements;
+ } gss_OID_set_desc, *gss_OID_set;
+
+ typedef struct gss_buffer_desc_struct {
+ size_t length;
+ void *value;
+ } gss_buffer_desc, *gss_buffer_t;
+
+ typedef struct gss_channel_bindings_struct {
+ OM_uint32 initiator_addrtype;
+ gss_buffer_desc initiator_address;
+ OM_uint32 acceptor_addrtype;
+ gss_buffer_desc acceptor_address;
+ gss_buffer_desc application_data;
+ } *gss_channel_bindings_t;
+
+ /*
+ * For now, define a QOP-type as an OM_uint32
+ */
+ typedef OM_uint32 gss_qop_t;
+
+ typedef int gss_cred_usage_t;
+
+ /*
+ * Flag bits for context-level services.
+ */
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 84]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ #define GSS_C_DELEG_FLAG 1
+ #define GSS_C_MUTUAL_FLAG 2
+ #define GSS_C_REPLAY_FLAG 4
+ #define GSS_C_SEQUENCE_FLAG 8
+ #define GSS_C_CONF_FLAG 16
+ #define GSS_C_INTEG_FLAG 32
+ #define GSS_C_ANON_FLAG 64
+ #define GSS_C_PROT_READY_FLAG 128
+ #define GSS_C_TRANS_FLAG 256
+
+ /*
+ * Credential usage options
+ */
+ #define GSS_C_BOTH 0
+ #define GSS_C_INITIATE 1
+ #define GSS_C_ACCEPT 2
+
+ /*
+ * Status code types for gss_display_status
+ */
+ #define GSS_C_GSS_CODE 1
+ #define GSS_C_MECH_CODE 2
+
+ /*
+ * The constant definitions for channel-bindings address families
+ */
+ #define GSS_C_AF_UNSPEC 0
+ #define GSS_C_AF_LOCAL 1
+ #define GSS_C_AF_INET 2
+ #define GSS_C_AF_IMPLINK 3
+ #define GSS_C_AF_PUP 4
+ #define GSS_C_AF_CHAOS 5
+ #define GSS_C_AF_NS 6
+ #define GSS_C_AF_NBS 7
+ #define GSS_C_AF_ECMA 8
+ #define GSS_C_AF_DATAKIT 9
+ #define GSS_C_AF_CCITT 10
+ #define GSS_C_AF_SNA 11
+ #define GSS_C_AF_DECnet 12
+ #define GSS_C_AF_DLI 13
+ #define GSS_C_AF_LAT 14
+ #define GSS_C_AF_HYLINK 15
+ #define GSS_C_AF_APPLETALK 16
+ #define GSS_C_AF_BSC 17
+ #define GSS_C_AF_DSS 18
+ #define GSS_C_AF_OSI 19
+ #define GSS_C_AF_X25 21
+
+
+
+
+Wray Standards Track [Page 85]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ #define GSS_C_AF_NULLADDR 255
+
+ /*
+ * Various Null values
+ */
+ #define GSS_C_NO_NAME ((gss_name_t) 0)
+ #define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
+ #define GSS_C_NO_OID ((gss_OID) 0)
+ #define GSS_C_NO_OID_SET ((gss_OID_set) 0)
+ #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0)
+ #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0)
+ #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0)
+ #define GSS_C_EMPTY_BUFFER {0, NULL}
+
+ /*
+ * Some alternate names for a couple of the above
+ * values. These are defined for V1 compatibility.
+ */
+ #define GSS_C_NULL_OID GSS_C_NO_OID
+ #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET
+
+ /*
+ * Define the default Quality of Protection for per-message
+ * services. Note that an implementation that offers multiple
+ * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero
+ * (as done here) to mean "default protection", or to a specific
+ * explicit QOP value. However, a value of 0 should always be
+ * interpreted by a GSS-API implementation as a request for the
+ * default protection level.
+ */
+ #define GSS_C_QOP_DEFAULT 0
+
+ /*
+ * Expiration time of 2^32-1 seconds means infinite lifetime for a
+ * credential or security context
+ */
+ #define GSS_C_INDEFINITE 0xfffffffful
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
+ * "\x01\x02\x01\x01"},
+ * corresponding to an object-identifier value of
+ * {iso(1) member-body(2) United States(840) mit(113554)
+ * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant
+ * GSS_C_NT_USER_NAME should be initialized to point
+ * to that gss_OID_desc.
+
+
+
+Wray Standards Track [Page 86]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ */
+ extern gss_OID GSS_C_NT_USER_NAME;
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
+ * "\x01\x02\x01\x02"},
+ * corresponding to an object-identifier value of
+ * {iso(1) member-body(2) United States(840) mit(113554)
+ * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}.
+ * The constant GSS_C_NT_MACHINE_UID_NAME should be
+ * initialized to point to that gss_OID_desc.
+ */
+ extern gss_OID GSS_C_NT_MACHINE_UID_NAME;
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
+ * "\x01\x02\x01\x03"},
+ * corresponding to an object-identifier value of
+ * {iso(1) member-body(2) United States(840) mit(113554)
+ * infosys(1) gssapi(2) generic(1) string_uid_name(3)}.
+ * The constant GSS_C_NT_STRING_UID_NAME should be
+ * initialized to point to that gss_OID_desc.
+ */
+ extern gss_OID GSS_C_NT_STRING_UID_NAME;
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {6, (void *)"\x2b\x06\x01\x05\x06\x02"},
+ * corresponding to an object-identifier value of
+ * {iso(1) org(3) dod(6) internet(1) security(5)
+ * nametypes(6) gss-host-based-services(2)). The constant
+ * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point
+ * to that gss_OID_desc. This is a deprecated OID value, and
+ * implementations wishing to support hostbased-service names
+ * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID,
+ * defined below, to identify such names;
+ * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym
+ * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input
+ * parameter, but should not be emitted by GSS-API
+ * implementations
+ */
+ extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X;
+
+
+
+
+Wray Standards Track [Page 87]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
+ * "\x01\x02\x01\x04"}, corresponding to an
+ * object-identifier value of {iso(1) member-body(2)
+ * Unites States(840) mit(113554) infosys(1) gssapi(2)
+ * generic(1) service_name(4)}. The constant
+ * GSS_C_NT_HOSTBASED_SERVICE should be initialized
+ * to point to that gss_OID_desc.
+ */
+ extern gss_OID GSS_C_NT_HOSTBASED_SERVICE;
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {6, (void *)"\x2b\x06\01\x05\x06\x03"},
+ * corresponding to an object identifier value of
+ * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
+ * 6(nametypes), 3(gss-anonymous-name)}. The constant
+ * and GSS_C_NT_ANONYMOUS should be initialized to point
+ * to that gss_OID_desc.
+ */
+ extern gss_OID GSS_C_NT_ANONYMOUS;
+
+
+ /*
+ * The implementation must reserve static storage for a
+ * gss_OID_desc object containing the value
+ * {6, (void *)"\x2b\x06\x01\x05\x06\x04"},
+ * corresponding to an object-identifier value of
+ * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
+ * 6(nametypes), 4(gss-api-exported-name)}. The constant
+ * GSS_C_NT_EXPORT_NAME should be initialized to point
+ * to that gss_OID_desc.
+ */
+ extern gss_OID GSS_C_NT_EXPORT_NAME;
+
+
+ /* Major status codes */
+
+ #define GSS_S_COMPLETE 0
+
+ /*
+ * Some "helper" definitions to make the status code macros obvious.
+ */
+ #define GSS_C_CALLING_ERROR_OFFSET 24
+ #define GSS_C_ROUTINE_ERROR_OFFSET 16
+
+
+
+Wray Standards Track [Page 88]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ #define GSS_C_SUPPLEMENTARY_OFFSET 0
+ #define GSS_C_CALLING_ERROR_MASK 0377ul
+ #define GSS_C_ROUTINE_ERROR_MASK 0377ul
+ #define GSS_C_SUPPLEMENTARY_MASK 0177777ul
+
+ /*
+ * The macros that test status codes for error conditions.
+ * Note that the GSS_ERROR() macro has changed slightly from
+ * the V1 GSS-API so that it now evaluates its argument
+ * only once.
+ */
+ #define GSS_CALLING_ERROR(x) \
+ (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET))
+ #define GSS_ROUTINE_ERROR(x) \
+ (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))
+ #define GSS_SUPPLEMENTARY_INFO(x) \
+ (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET))
+ #define GSS_ERROR(x) \
+ (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \
+ (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)))
+
+ /*
+ * Now the actual status code definitions
+ */
+
+ /*
+ * Calling errors:
+
+ */
+ #define GSS_S_CALL_INACCESSIBLE_READ \
+ (1ul << GSS_C_CALLING_ERROR_OFFSET)
+ #define GSS_S_CALL_INACCESSIBLE_WRITE \
+ (2ul << GSS_C_CALLING_ERROR_OFFSET)
+ #define GSS_S_CALL_BAD_STRUCTURE \
+ (3ul << GSS_C_CALLING_ERROR_OFFSET)
+
+ /*
+ * Routine errors:
+ */
+ #define GSS_S_BAD_MECH (1ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_NAME (2ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_NAMETYPE (3ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_BINDINGS (4ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_STATUS (5ul <<
+
+
+
+Wray Standards Track [Page 89]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_SIG (6ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_MIC GSS_S_BAD_SIG
+ #define GSS_S_NO_CRED (7ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_NO_CONTEXT (8ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_DEFECTIVE_TOKEN (9ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_DEFECTIVE_CREDENTIAL (10ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_CREDENTIALS_EXPIRED (11ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_CONTEXT_EXPIRED (12ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_FAILURE (13ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_BAD_QOP (14ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_UNAUTHORIZED (15ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_UNAVAILABLE (16ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_DUPLICATE_ELEMENT (17ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+ #define GSS_S_NAME_NOT_MN (18ul <<
+ GSS_C_ROUTINE_ERROR_OFFSET)
+
+ /*
+ * Supplementary info bits:
+ */
+ #define GSS_S_CONTINUE_NEEDED \
+ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0))
+ #define GSS_S_DUPLICATE_TOKEN \
+ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1))
+ #define GSS_S_OLD_TOKEN \
+ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2))
+ #define GSS_S_UNSEQ_TOKEN \
+ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3))
+ #define GSS_S_GAP_TOKEN \
+ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4))
+
+ /*
+ * Finally, function prototypes for the GSS-API routines.
+ */
+
+
+
+
+
+Wray Standards Track [Page 90]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_acquire_cred
+ (OM_uint32 , /* minor_status */
+ const gss_name_t, /* desired_name */
+ OM_uint32, /* time_req */
+ const gss_OID_set, /* desired_mechs */
+ gss_cred_usage_t, /* cred_usage */
+ gss_cred_id_t , /* output_cred_handle */
+ gss_OID_set , /* actual_mechs */
+ OM_uint32 * /* time_rec */
+ );
+
+ OM_uint32 gss_release_cred
+ (OM_uint32 , /* minor_status */
+ gss_cred_id_t * /* cred_handle */
+ );
+
+ OM_uint32 gss_init_sec_context
+ (OM_uint32 , /* minor_status */
+ const gss_cred_id_t, /* initiator_cred_handle */
+ gss_ctx_id_t , /* context_handle */
+ const gss_name_t, /* target_name */
+ const gss_OID, /* mech_type */
+ OM_uint32, /* req_flags */
+ OM_uint32, /* time_req */
+ const gss_channel_bindings_t,
+ /* input_chan_bindings */
+ const gss_buffer_t, /* input_token */
+ gss_OID , /* actual_mech_type */
+ gss_buffer_t, /* output_token */
+ OM_uint32 , /* ret_flags */
+ OM_uint32 * /* time_rec */
+ );
+
+ OM_uint32 gss_accept_sec_context
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t , /* context_handle */
+ const gss_cred_id_t, /* acceptor_cred_handle */
+ const gss_buffer_t, /* input_token_buffer */
+ const gss_channel_bindings_t,
+ /* input_chan_bindings */
+ gss_name_t , /* src_name */
+ gss_OID , /* mech_type */
+ gss_buffer_t, /* output_token */
+ OM_uint32 , /* ret_flags */
+ OM_uint32 , /* time_rec */
+ gss_cred_id_t * /* delegated_cred_handle */
+ );
+
+
+
+
+Wray Standards Track [Page 91]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_process_context_token
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ const gss_buffer_t /* token_buffer */
+ );
+
+ OM_uint32 gss_delete_sec_context
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t , /* context_handle */
+ gss_buffer_t /* output_token */
+ );
+
+ OM_uint32 gss_context_time
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ OM_uint32 * /* time_rec */
+ );
+
+ OM_uint32 gss_get_mic
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ gss_qop_t, /* qop_req */
+ const gss_buffer_t, /* message_buffer */
+ gss_buffer_t /* message_token */
+ );
+
+ OM_uint32 gss_verify_mic
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ const gss_buffer_t, /* message_buffer */
+ const gss_buffer_t, /* token_buffer */
+ gss_qop_t * /* qop_state */
+ );
+
+ OM_uint32 gss_wrap
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ int, /* conf_req_flag */
+ gss_qop_t, /* qop_req */
+ const gss_buffer_t, /* input_message_buffer */
+ int , /* conf_state */
+ gss_buffer_t /* output_message_buffer */
+ );
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 92]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_unwrap
+ (OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ const gss_buffer_t, /* input_message_buffer */
+ gss_buffer_t, /* output_message_buffer */
+ int , /* conf_state */
+ gss_qop_t * /* qop_state */
+ );
+
+
+
+ OM_uint32 gss_display_status
+ (OM_uint32 , /* minor_status */
+ OM_uint32, /* status_value */
+ int, /* status_type */
+ const gss_OID, /* mech_type */
+ OM_uint32 , /* message_context */
+ gss_buffer_t /* status_string */
+ );
+
+ OM_uint32 gss_indicate_mechs
+ (OM_uint32 , /* minor_status */
+ gss_OID_set * /* mech_set */
+ );
+
+ OM_uint32 gss_compare_name
+ (OM_uint32 , /* minor_status */
+ const gss_name_t, /* name1 */
+ const gss_name_t, /* name2 */
+ int * /* name_equal */
+ );
+
+ OM_uint32 gss_display_name
+ (OM_uint32 , /* minor_status */
+ const gss_name_t, /* input_name */
+ gss_buffer_t, /* output_name_buffer */
+ gss_OID * /* output_name_type */
+ );
+
+ OM_uint32 gss_import_name
+ (OM_uint32 , /* minor_status */
+ const gss_buffer_t, /* input_name_buffer */
+ const gss_OID, /* input_name_type */
+ gss_name_t * /* output_name */
+ );
+
+
+
+
+
+
+Wray Standards Track [Page 93]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_export_name
+ (OM_uint32, /* minor_status */
+ const gss_name_t, /* input_name */
+ gss_buffer_t /* exported_name */
+ );
+
+ OM_uint32 gss_release_name
+ (OM_uint32 *, /* minor_status */
+ gss_name_t * /* input_name */
+ );
+
+ OM_uint32 gss_release_buffer
+ (OM_uint32 , /* minor_status */
+ gss_buffer_t /* buffer */
+ );
+
+ OM_uint32 gss_release_oid_set
+ (OM_uint32 , /* minor_status */
+ gss_OID_set * /* set */
+ );
+
+ OM_uint32 gss_inquire_cred
+ (OM_uint32 , /* minor_status */
+ const gss_cred_id_t, /* cred_handle */
+ gss_name_t , /* name */
+ OM_uint32 , /* lifetime */
+ gss_cred_usage_t , /* cred_usage */
+ gss_OID_set * /* mechanisms */
+ );
+
+ OM_uint32 gss_inquire_context (
+ OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ gss_name_t , /* src_name */
+ gss_name_t , /* targ_name */
+ OM_uint32 , /* lifetime_rec */
+ gss_OID , /* mech_type */
+ OM_uint32 , /* ctx_flags */
+ int , /* locally_initiated */
+ int * /* open */
+ );
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 94]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_wrap_size_limit (
+ OM_uint32 , /* minor_status */
+ const gss_ctx_id_t, /* context_handle */
+ int, /* conf_req_flag */
+ gss_qop_t, /* qop_req */
+ OM_uint32, /* req_output_size */
+ OM_uint32 * /* max_input_size */
+ );
+
+ OM_uint32 gss_add_cred (
+ OM_uint32 , /* minor_status */
+ const gss_cred_id_t, /* input_cred_handle */
+ const gss_name_t, /* desired_name */
+ const gss_OID, /* desired_mech */
+ gss_cred_usage_t, /* cred_usage */
+ OM_uint32, /* initiator_time_req */
+ OM_uint32, /* acceptor_time_req */
+ gss_cred_id_t , /* output_cred_handle */
+ gss_OID_set , /* actual_mechs */
+ OM_uint32 , /* initiator_time_rec */
+ OM_uint32 * /* acceptor_time_rec */
+ );
+
+ OM_uint32 gss_inquire_cred_by_mech (
+ OM_uint32 , /* minor_status */
+ const gss_cred_id_t, /* cred_handle */
+ const gss_OID, /* mech_type */
+ gss_name_t , /* name */
+ OM_uint32 , /* initiator_lifetime */
+ OM_uint32 , /* acceptor_lifetime */
+ gss_cred_usage_t * /* cred_usage */
+ );
+
+ OM_uint32 gss_export_sec_context (
+ OM_uint32 , /* minor_status */
+ gss_ctx_id_t , /* context_handle */
+ gss_buffer_t /* interprocess_token */
+ );
+
+ OM_uint32 gss_import_sec_context (
+ OM_uint32 , /* minor_status */
+ const gss_buffer_t, /* interprocess_token */
+ gss_ctx_id_t * /* context_handle */
+ );
+
+
+
+
+
+
+
+Wray Standards Track [Page 95]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ OM_uint32 gss_create_empty_oid_set (
+ OM_uint32 , /* minor_status */
+ gss_OID_set * /* oid_set */
+ );
+
+ OM_uint32 gss_add_oid_set_member (
+ OM_uint32 , /* minor_status */
+ const gss_OID, /* member_oid */
+ gss_OID_set * /* oid_set */
+ );
+
+ OM_uint32 gss_test_oid_set_member (
+ OM_uint32 , /* minor_status */
+ const gss_OID, /* member */
+ const gss_OID_set, /* set */
+ int * /* present */
+ );
+
+ OM_uint32 gss_inquire_names_for_mech (
+ OM_uint32 , /* minor_status */
+ const gss_OID, /* mechanism */
+ gss_OID_set * /* name_types */
+ );
+
+ OM_uint32 gss_inquire_mechs_for_name (
+ OM_uint32 , /* minor_status */
+ const gss_name_t, /* input_name */
+ gss_OID_set * /* mech_types */
+ );
+
+ OM_uint32 gss_canonicalize_name (
+ OM_uint32 , /* minor_status */
+ const gss_name_t, /* input_name */
+ const gss_OID, /* mech_type */
+ gss_name_t * /* output_name */
+ );
+
+ OM_uint32 gss_duplicate_name (
+ OM_uint32 , /* minor_status */
+ const gss_name_t, /* src_name */
+ gss_name_t * /* dest_name */
+ );
+
+ /*
+ * The following routines are obsolete variants of gss_get_mic,
+ * gss_verify_mic, gss_wrap and gss_unwrap. They should be
+ * provided by GSS-API V2 implementations for backwards
+ * compatibility with V1 applications. Distinct entrypoints
+
+
+
+Wray Standards Track [Page 96]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ * (as opposed to #defines) should be provided, both to allow
+ * GSS-API V1 applications to link against GSS-API V2
+ implementations,
+ * and to retain the slight parameter type differences between the
+ * obsolete versions of these routines and their current forms.
+ */
+
+ OM_uint32 gss_sign
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t, /* context_handle */
+ int, /* qop_req */
+ gss_buffer_t, /* message_buffer */
+ gss_buffer_t /* message_token */
+ );
+
+
+ OM_uint32 gss_verify
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t, /* context_handle */
+ gss_buffer_t, /* message_buffer */
+ gss_buffer_t, /* token_buffer */
+ int * /* qop_state */
+ );
+
+ OM_uint32 gss_seal
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t, /* context_handle */
+ int, /* conf_req_flag */
+ int, /* qop_req */
+ gss_buffer_t, /* input_message_buffer */
+ int , /* conf_state */
+ gss_buffer_t /* output_message_buffer */
+ );
+
+
+ OM_uint32 gss_unseal
+ (OM_uint32 , /* minor_status */
+ gss_ctx_id_t, /* context_handle */
+ gss_buffer_t, /* input_message_buffer */
+ gss_buffer_t, /* output_message_buffer */
+ int , /* conf_state */
+ int * /* qop_state */
+ );
+
+ #endif /* GSSAPI_H_ */
+
+
+
+
+
+
+Wray Standards Track [Page 97]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+Appendix B. Additional constraints for application binary portability
+
+ The purpose of this C-bindings document is to encourage source-level
+ portability of applications across GSS-API implementations on
+ different platforms and atop different mechanisms. Additional goals
+ that have not been explicitly addressed by this document are link-
+ time and run-time portability.
+
+ Link-time portability provides the ability to compile an application
+ against one implementation of GSS-API, and then link it against a
+ different implementation on the same platform. It is a stricter
+ requirement than source-level portability.
+
+ Run-time portability differs from link-time portability only on those
+ platforms that implement dynamically loadable GSS-API
+ implementations, but do not offer load-time symbol resolution. On
+ such platforms, run-time portability is a stricter requirement than
+ link-time portability, and will typically include the precise
+ placement of the various GSS-API routines within library entrypoint
+ vectors.
+
+ Individual platforms will impose their own rules that must be
+ followed to achieve link-time (and run-time, if different)
+ portability. In order to ensure either form of binary portability,
+ an ABI specification must be written for GSS-API implementations on
+ that platform. However, it is recognized that there are some issues
+ that are likely to be common to all such ABI specifications. This
+ appendix is intended to be a repository for such common issues, and
+ contains some suggestions that individual ABI specifications may
+ choose to reference. Since machine architectures vary greatly, it may
+ not be possible or desirable to follow these suggestions on all
+ platforms.
+
+B.1. Pointers
+
+ While ANSI-C provides a single pointer type for each declared type,
+ plus a single (void *) type, some platforms (notably those using
+ segmented memory architectures) augment this with various modified
+ pointer types (e.g. far pointers, near pointers). These language
+ bindings assume ANSI-C, and thus do not address such non-standard
+ implementations. GSS-API implementations for such platforms must
+ choose an appropriate memory model, and should use it consistently
+ throughout. For example, if a memory model is chosen that requires
+ the use of far pointers when passing routine parameters, then far
+ pointers should also be used within the structures defined by GSS-
+ API.
+
+
+
+
+
+Wray Standards Track [Page 98]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+B.2. Internal structure alignment
+
+ GSS-API defines several data-structures containing differently-sized
+ fields. An ABI specification should include a detailed description
+ of how the fields of such structures are aligned, and if there is any
+ internal padding in these data structures. The use of compiler
+ defaults for the platform is recommended.
+
+B.3. Handle types
+
+ The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types
+ should be implemented as either pointer or arithmetic types, and that
+ if pointer types are used, care should be taken to ensure that two
+ handles may be compared with the == operator. Note that ANSI-C does
+ not guarantee that two pointer values may be compared with the ==
+ operator unless either the two pointers point to members of a single
+ array, or at least one of the pointers contains a NULL value.
+
+ For binary portability, additional constraints are required. The
+ following is an attempt at defining platform-independent constraints.
+
+ The size of the handle type must be the same as sizeof(void *), using
+ the appropriate memory model.
+
+ The == operator for the chosen type must be a simple bit-wise
+ comparison. That is, for two in-memory handle objects h1 and h2, the
+ boolean value of the expression
+
+ (h1 == h2)
+
+ should always be the same as the boolean value of the expression
+
+ (memcmp(&h1, &h2, sizeof(h1)) == 0)
+
+ The actual use of the type (void *) for handle types is discouraged,
+ not for binary portability reasons, but since it effectively disables
+ much of the compile-time type-checking that the compiler can
+ otherwise perform, and is therefore not "programmer-friendly". If a
+ pointer implementation is desired, and if the platform's
+ implementation of pointers permits, the handles should be implemented
+ as pointers to distinct implementation-defined types.
+
+B.4. The gss_name_t type
+
+ The gss_name_t type, representing the internal name object, should be
+ implemented as a pointer type. The use of the (void *) type is
+ discouraged as it does not allow the compiler to perform strong
+ type-checking. However, the pointer type chosen should be of the
+
+
+
+Wray Standards Track [Page 99]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+ same size as the (void *) type. Provided this rule is obeyed, ABI
+ specifications need not further constrain the implementation of
+ gss_name_t objects.
+
+B.5. The int and size_t types
+
+ Some platforms may support differently sized implementations of the
+ "int" and "size_t" types, perhaps chosen through compiler switches,
+ and perhaps dependent on memory model. An ABI specification for such
+ a platform should include required implementations for these types.
+ It is recommended that the default implementation (for the chosen
+ memory model, if appropriate) is chosen.
+
+B.6. Procedure-calling conventions
+
+ Some platforms support a variety of different binary conventions for
+ calling procedures. Such conventions cover things like the format of
+ the stack frame, the order in which the routine parameters are pushed
+ onto the stack, whether or not a parameter count is pushed onto the
+ stack, whether some argument(s) or return values are to be passed in
+ registers, and whether the called routine or the caller is
+ responsible for removing the stack frame on return. For such
+ platforms, an ABI specification should specify which calling
+ convention is to be used for GSS-API implementations.
+
+References
+
+ [GSSAPI] Linn, J., "Generic Security Service Application Program
+ Interface Version 2, Update 1", RFC 2743, January 2000.
+
+ [XOM] OSI Object Management API Specification, Version 2.0 t",
+ X.400 API Association & X/Open Company Limited, August
+ 24, 1990 Specification of datatypes and routines for
+ manipulating information objects.
+
+Author's Address
+
+ John Wray
+ Iris Associates
+ 5 Technology Park Drive,
+ Westford, MA 01886
+ USA
+
+ Phone: +1-978-392-6689
+ EMail: John_Wray@Iris.com
+
+
+
+
+
+
+Wray Standards Track [Page 100]
+
+RFC 2744 GSS-API V2: C-bindings January 2000
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wray Standards Track [Page 101]
+
diff --git a/crypto/heimdal/kdc/config.c b/crypto/heimdal/kdc/config.c
index ba76432..3db7173 100644
--- a/crypto/heimdal/kdc/config.c
+++ b/crypto/heimdal/kdc/config.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997-1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997-2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -35,24 +35,33 @@
#include <getarg.h>
#include <parse_bytes.h>
-RCSID("$Id: config.c,v 1.28 1999/12/02 17:04:58 joda Exp $");
+RCSID("$Id: config.c,v 1.30 2000/02/11 17:47:19 assar Exp $");
+
+static char *config_file; /* location of kdc config file */
+
+int require_preauth = -1; /* 1 == require preauth for all principals */
+
+size_t max_request; /* maximal size of a request */
+
+static char *max_request_str; /* `max_request' as a string */
+
+time_t kdc_warn_pwexpire; /* time before expiration to print a warning */
-static char *config_file;
-int require_preauth = -1;
-char *keyfile;
-static char *max_request_str;
-size_t max_request;
-time_t kdc_warn_pwexpire;
struct dbinfo *databases;
HDB **db;
int num_db;
+
char *port_str;
+
int enable_http = -1;
krb5_boolean encode_as_rep_as_tgs_rep; /* bug compatibility */
krb5_boolean check_ticket_addresses;
krb5_boolean allow_null_ticket_addresses;
+static struct getarg_strings addresses_str; /* addresses to listen on */
+krb5_addresses explicit_addresses;
+
#ifdef KRB4
char *v4_realm;
#endif
@@ -73,10 +82,6 @@ static struct getargs args[] = {
"don't require pa-data in as-reqs"
},
{
- "key-file", 'k', arg_string, &keyfile,
- "location of master key file", "file"
- },
- {
"max-request", 0, arg_string, &max_request,
"max size for a kdc-request", "size"
},
@@ -102,6 +107,8 @@ static struct getargs args[] = {
{ "ports", 'P', arg_string, &port_str,
"ports to listen to"
},
+ { "addresses", 0, arg_strings, &addresses_str,
+ "addresses to listen on", "list of addresses" },
{ "help", 'h', arg_flag, &help_flag },
{ "version", 'v', arg_flag, &version_flag }
};
@@ -190,6 +197,22 @@ get_dbinfo(krb5_config_section *cf)
}
}
+static void
+add_one_address (const char *str, int first)
+{
+ krb5_error_code ret;
+ krb5_addresses tmp;
+
+ ret = krb5_parse_address (context, str, &tmp);
+ if (ret)
+ krb5_err (context, 1, ret, "parse_address `%s'", str);
+ if (first)
+ krb5_copy_addresses(context, &tmp, &explicit_addresses);
+ else
+ krb5_append_addresses(context, &explicit_addresses, &tmp);
+ krb5_free_addresses (context, &tmp);
+}
+
void
configure(int argc, char **argv)
{
@@ -221,16 +244,6 @@ configure(int argc, char **argv)
if(krb5_config_parse_file(config_file, &cf))
cf = NULL;
- if(keyfile == NULL){
- p = krb5_config_get_string (context, cf,
- "kdc",
- "key-file",
- NULL);
- if(p)
- keyfile = strdup(p);
- }
-
-
get_dbinfo(cf);
if(max_request_str){
@@ -256,6 +269,25 @@ configure(int argc, char **argv)
if (p != NULL)
port_str = strdup(p);
}
+
+ explicit_addresses.len = 0;
+
+ if (addresses_str.num_strings) {
+ int i;
+
+ for (i = 0; i < addresses_str.num_strings; ++i)
+ add_one_address (addresses_str.strings[i], i == 0);
+ } else {
+ char **foo = krb5_config_get_strings (context, cf,
+ "kdc", "addresses", NULL);
+
+ if (foo != NULL) {
+ add_one_address (*foo++, TRUE);
+ while (*foo)
+ add_one_address (*foo++, FALSE);
+ }
+ }
+
if(enable_http == -1)
enable_http = krb5_config_get_bool(context, cf, "kdc",
"enable-http", NULL);
diff --git a/crypto/heimdal/kdc/connect.c b/crypto/heimdal/kdc/connect.c
index 62b5bea..a1bbdcb 100644
--- a/crypto/heimdal/kdc/connect.c
+++ b/crypto/heimdal/kdc/connect.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997-1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997-2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,7 +33,11 @@
#include "kdc_locl.h"
-RCSID("$Id: connect.c,v 1.68 1999/12/02 17:04:58 joda Exp $");
+RCSID("$Id: connect.c,v 1.69 2000/02/11 17:45:45 assar Exp $");
+
+/*
+ * a tuple describing on what to listen
+ */
struct port_desc{
int family;
@@ -41,9 +45,15 @@ struct port_desc{
int port;
};
+/* the current ones */
+
static struct port_desc *ports;
static int num_ports;
+/*
+ * add `family, port, protocol' to the list with duplicate suppresion.
+ */
+
static void
add_port(int family, int port, const char *protocol)
{
@@ -63,12 +73,19 @@ add_port(int family, int port, const char *protocol)
return;
}
ports = realloc(ports, (num_ports + 1) * sizeof(*ports));
+ if (ports == NULL)
+ krb5_err (context, 1, errno, "realloc");
ports[num_ports].family = family;
ports[num_ports].type = type;
ports[num_ports].port = port;
num_ports++;
}
+/*
+ * add a triple but with service -> port lookup
+ * (this prints warnings for stuff that does not exist)
+ */
+
static void
add_port_service(int family, const char *service, int port,
const char *protocol)
@@ -77,6 +94,11 @@ add_port_service(int family, const char *service, int port,
add_port (family, port, protocol);
}
+/*
+ * add the port with service -> port lookup or string -> number
+ * (no warning is printed)
+ */
+
static void
add_port_string (int family, const char *port_str, const char *protocol)
{
@@ -96,6 +118,10 @@ add_port_string (int family, const char *port_str, const char *protocol)
add_port (family, port, protocol);
}
+/*
+ * add the standard collection of ports for `family'
+ */
+
static void
add_standard_ports (int family)
{
@@ -113,6 +139,12 @@ add_standard_ports (int family)
#endif
}
+/*
+ * parse the set of space-delimited ports in `str' and add them.
+ * "+" => all the standard ones
+ * otherwise it's port|service[/protocol]
+ */
+
static void
parse_ports(const char *str)
{
@@ -150,6 +182,10 @@ parse_ports(const char *str)
free (str_copy);
}
+/*
+ * every socket we listen on
+ */
+
struct descr {
int s;
int type;
@@ -176,7 +212,7 @@ init_socket(struct descr *d, krb5_address *a, int family, int type, int port)
ret = krb5_addr2sockaddr (a, sa, &sa_size, port);
if (ret) {
- krb5_warn(context, ret, "krb5_anyaddr");
+ krb5_warn(context, ret, "krb5_addr2sockaddr");
close(d->s);
d->s = -1;
return;
@@ -200,14 +236,23 @@ init_socket(struct descr *d, krb5_address *a, int family, int type, int port)
d->type = type;
if(bind(d->s, sa, sa_size) < 0){
- krb5_warn(context, errno, "bind(%d)", ntohs(port));
+ char a_str[256];
+ size_t len;
+
+ krb5_print_address (a, a_str, sizeof(a_str), &len);
+ krb5_warn(context, errno, "bind %s/%d", a_str, ntohs(port));
close(d->s);
d->s = -1;
return;
}
if(type == SOCK_STREAM && listen(d->s, SOMAXCONN) < 0){
- krb5_warn(context, errno, "listen");
+ char a_str[256];
+ size_t len;
+
+ krb5_print_address (a, a_str, sizeof(a_str), &len);
+ krb5_warn(context, errno, "listen %s/%d", a_str, ntohs(port));
close(d->s);
+ d->s = -1;
return;
}
}
@@ -226,9 +271,13 @@ init_sockets(struct descr **desc)
int num = 0;
krb5_addresses addresses;
- ret = krb5_get_all_server_addrs (context, &addresses);
- if (ret)
- krb5_err (context, 1, ret, "krb5_get_all_server_addrs");
+ if (explicit_addresses.len) {
+ addresses = explicit_addresses;
+ } else {
+ ret = krb5_get_all_server_addrs (context, &addresses);
+ if (ret)
+ krb5_err (context, 1, ret, "krb5_get_all_server_addrs");
+ }
parse_ports(port_str);
d = malloc(addresses.len * num_ports * sizeof(*d));
if (d == NULL)
@@ -262,7 +311,11 @@ init_sockets(struct descr **desc)
return num;
}
-
+/*
+ * handle the request in `buf, len', from `addr' (or `from' as a string),
+ * sending a reply in `reply'.
+ */
+
static int
process_request(unsigned char *buf,
size_t len,
@@ -711,7 +764,8 @@ loop(void)
case 0:
break;
case -1:
- krb5_warn(context, errno, "select");
+ if (errno != EINTR)
+ krb5_warn(context, errno, "select");
break;
default:
for(i = 0; i < ndescr; i++)
diff --git a/crypto/heimdal/kdc/kaserver.c b/crypto/heimdal/kdc/kaserver.c
index dc155fa..64121eb 100644
--- a/crypto/heimdal/kdc/kaserver.c
+++ b/crypto/heimdal/kdc/kaserver.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,7 +33,7 @@
#include "kdc_locl.h"
-RCSID("$Id: kaserver.c,v 1.9 1999/12/02 17:04:59 joda Exp $");
+RCSID("$Id: kaserver.c,v 1.10 2000/02/13 19:21:22 assar Exp $");
#ifdef KASERVER
@@ -468,7 +468,7 @@ do_authenticate (struct rx_header *hdr,
create_reply_ticket (hdr, skey,
name, instance, v4_realm,
- addr, life, client_entry->kvno,
+ addr, life, server_entry->kvno,
max_seq_len,
"krbtgt", v4_realm,
chal + 1, "tgsT",
diff --git a/crypto/heimdal/kdc/kdc.8 b/crypto/heimdal/kdc/kdc.8
index 8925111..181a3ce 100644
--- a/crypto/heimdal/kdc/kdc.8
+++ b/crypto/heimdal/kdc/kdc.8
@@ -1,4 +1,4 @@
-.\" $Id: kdc.8,v 1.3 1997/08/09 00:20:38 joda Exp $
+.\" $Id: kdc.8,v 1.5 2000/02/13 21:04:32 assar Exp $
.\"
.Dd July 27, 1997
.Dt KDC 8
@@ -11,12 +11,16 @@ Kerberos 5 server
.Nm
.Op Fl c Ar file
.Op Fl -config-file= Ns Ar file
-.Op Fl k Ar file
-.Op Fl -key-file= Ns Ar file
-.Op Fl p
-.Op Fl -no-require-preauth
+.Op Fl p | Fl -no-require-preauth
+.Op Fl -max-request= Ns Ar size
+.Op Fl H | Fl -enable-http
+.Op Fl K | Fl -no-kaserver
.Op Fl r Ar realm
.Op Fl -v4-realm= Ns Ar realm
+.Oo Fl P Ar string \*(Ba Xo
+.Fl -ports= Ns Ar string Oc
+.Xc
+.Op Fl -addresses= Ns Ar list of addresses
.Sh DESCRIPTION
.Nm
@@ -31,21 +35,32 @@ Options supported:
Specifies the location of the config file, the default is
.Pa /var/heimdal/kdc.conf .
This is the only value that can't be specified in the config file.
-.It Fl k Ar file
-.It Fl -key-file= Ns Ar file
-The location of the master-key file. All keys in the database is
-encrypted with this master key. The use of a master key is currently
-optional, so there is no default.
-.Em "Don't specify a master key file if your database is not encrypted."
.It Fl p
.It Fl -no-require-preauth
-Turn off the requirement for pre-autentication in the initial
-AS-REQ. The use of pre-authentication makes it more difficult to do
-offline password attacks. You might want to turn it off if you have
-clients that doesn't do pre-authentication. Since the version 4
-protocol doesn't support any pre-authentication, so serving version 4
-clients is just about the same as not requiring pre-athentication. The
-default is to require pre-authentication.
+Turn off the requirement for pre-autentication in the initial AS-REQ
+for all principals. The use of pre-authentication makes it more
+difficult to do offline password attacks. You might want to turn it
+off if you have clients that doesn't do pre-authentication. Since the
+version 4 protocol doesn't support any pre-authentication, so serving
+version 4 clients is just about the same as not requiring
+pre-athentication. The default is to require
+pre-authentication. Adding the require-preauth per principal is a more
+flexible way of handling this.
+.It Xo
+.Fl -max-request= Ns Ar size
+.Xc
+Gives an upper limit on the size of the requests that the kdc is
+willing to handle.
+.It Xo
+.Fl H Ns ,
+.Fl -enable-http
+.Xc
+Makes the kdc listen on port 80 and handle requests encapsulated in HTTP.
+.It Xo
+.Fl K Ns ,
+.Fl -no-kaserver
+.Xc
+Disables kaserver emulation (in case it's compiled in).
.It Fl r Ar realm
.It Fl -v4-realm= Ns Ar realm
What realm this server should act as when dealing with version 4
@@ -55,6 +70,18 @@ explicitly specified. The default is whatever is returned by
.Fn krb_get_lrealm .
This option is only availabe if the KDC has been compiled with version
4 support.
+.It Xo
+.Fl P Ar string Ns ,
+.Fl -ports= Ns Ar string
+.Xc
+Specifies the set of ports the KDC should listen on. It is given as a
+white-space separated list of services or port numbers.
+.It Xo
+.Fl -addresses= Ns Ar list of addresses
+.Xc
+The list of addresses to listen for requests on. By default, the kdc
+will listen on all the locally configured addresses. If only a subset
+is desired, or the automatic detection fails, this option might be used.
.El
.Pp
All activities , are logged to one or more destinations, see
diff --git a/crypto/heimdal/kdc/kdc_locl.h b/crypto/heimdal/kdc/kdc_locl.h
index 7275576..c703030 100644
--- a/crypto/heimdal/kdc/kdc_locl.h
+++ b/crypto/heimdal/kdc/kdc_locl.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997-1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997-2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -32,7 +32,7 @@
*/
/*
- * $Id: kdc_locl.h,v 1.39 1999/12/02 17:04:59 joda Exp $
+ * $Id: kdc_locl.h,v 1.40 2000/02/11 17:46:29 assar Exp $
*/
#ifndef __KDC_LOCL_H__
@@ -44,7 +44,6 @@ extern krb5_context context;
extern int require_preauth;
extern sig_atomic_t exit_flag;
-extern char *keyfile;
extern size_t max_request;
extern time_t kdc_warn_pwexpire;
extern struct dbinfo {
@@ -56,6 +55,8 @@ extern struct dbinfo {
extern HDB **db;
extern int num_db;
extern char *port_str;
+extern krb5_addresses explicit_addresses;
+
extern int enable_http;
extern krb5_boolean encode_as_rep_as_tgs_rep;
extern krb5_boolean check_ticket_addresses;
diff --git a/crypto/heimdal/kdc/kerberos4.c b/crypto/heimdal/kdc/kerberos4.c
index 29e28b3..23d59dd 100644
--- a/crypto/heimdal/kdc/kerberos4.c
+++ b/crypto/heimdal/kdc/kerberos4.c
@@ -33,7 +33,7 @@
#include "kdc_locl.h"
-RCSID("$Id: kerberos4.c,v 1.26 2000/02/02 01:26:41 assar Exp $");
+RCSID("$Id: kerberos4.c,v 1.27 2000/02/13 19:27:36 assar Exp $");
#ifdef KRB4
@@ -307,6 +307,10 @@ do_version4(unsigned char *buf,
}
if(tgt->kvno != kvno){
+ kdc_log(0, "tgs-req with old kvno %d (current %d) for "
+ "krbtgt.%s@%s", kvno, tgt->kvno, realm, v4_realm);
+ make_err_reply(reply, KDC_AUTH_EXP,
+ "old krbtgt kvno used");
goto out2;
}
diff --git a/crypto/heimdal/lib/gssapi/ChangeLog b/crypto/heimdal/lib/gssapi/ChangeLog
index d8f80f4..ba765ba 100644
--- a/crypto/heimdal/lib/gssapi/ChangeLog
+++ b/crypto/heimdal/lib/gssapi/ChangeLog
@@ -1,3 +1,27 @@
+2000-02-13 Assar Westerlund <assar@sics.se>
+
+ * Makefile.am: set version to 1:0:1
+
+2000-02-12 Assar Westerlund <assar@sics.se>
+
+ * gssapi_locl.h: add flags for import/export
+ * import_sec_context.c (import_sec_context: add flags for what
+ fields are included. do not include the authenticator for now.
+ * export_sec_context.c (export_sec_context: add flags for what
+ fields are included. do not include the authenticator for now.
+ * accept_sec_context.c (gss_accept_sec_context): set target in
+ context_handle
+
+2000-02-11 Assar Westerlund <assar@sics.se>
+
+ * delete_sec_context.c (gss_delete_sec_context): set context to
+ GSS_C_NO_CONTEXT
+
+ * Makefile.am: add {export,import}_sec_context.c
+ * export_sec_context.c: new file
+ * import_sec_context.c: new file
+ * accept_sec_context.c (gss_accept_sec_context): set trans flag
+
2000-02-07 Assar Westerlund <assar@sics.se>
* Makefile.am: set version to 0:5:0
diff --git a/crypto/heimdal/lib/gssapi/Makefile.am b/crypto/heimdal/lib/gssapi/Makefile.am
index 72bdf45..07d4e65 100644
--- a/crypto/heimdal/lib/gssapi/Makefile.am
+++ b/crypto/heimdal/lib/gssapi/Makefile.am
@@ -1,11 +1,11 @@
-# $Id: Makefile.am,v 1.19 2000/02/07 04:00:51 assar Exp $
+# $Id: Makefile.am,v 1.21 2000/02/13 20:34:49 assar Exp $
include $(top_srcdir)/Makefile.am.common
INCLUDES += -I$(srcdir)/../krb5
lib_LTLIBRARIES = libgssapi.la
-libgssapi_la_LDFLAGS = -version-info 0:5:0
+libgssapi_la_LDFLAGS = -version-info 1:0:1
include_HEADERS = gssapi.h
@@ -24,12 +24,14 @@ libgssapi_la_SOURCES = \
display_status.c \
duplicate_name.c \
encapsulate.c \
+ export_sec_context.c \
export_name.c \
external.c \
get_mic.c \
gssapi.h \
gssapi_locl.h \
import_name.c \
+ import_sec_context.c \
indicate_mechs.c \
init.c \
init_sec_context.c \
diff --git a/crypto/heimdal/lib/gssapi/Makefile.in b/crypto/heimdal/lib/gssapi/Makefile.in
index 2ecd970..31ea813 100644
--- a/crypto/heimdal/lib/gssapi/Makefile.in
+++ b/crypto/heimdal/lib/gssapi/Makefile.in
@@ -10,7 +10,7 @@
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
-# $Id: Makefile.am,v 1.19 2000/02/07 04:00:51 assar Exp $
+# $Id: Makefile.am,v 1.21 2000/02/13 20:34:49 assar Exp $
# $Id: Makefile.am.common,v 1.3 1999/04/01 14:58:43 joda Exp $
@@ -174,11 +174,11 @@ NROFF_MAN = groff -mandoc -Tascii
CHECK_LOCAL = $(PROGRAMS)
lib_LTLIBRARIES = libgssapi.la
-libgssapi_la_LDFLAGS = -version-info 0:5:0
+libgssapi_la_LDFLAGS = -version-info 1:0:1
include_HEADERS = gssapi.h
-libgssapi_la_SOURCES = 8003.c accept_sec_context.c acquire_cred.c add_oid_set_member.c canonicalize_name.c compare_name.c context_time.c create_emtpy_oid_set.c decapsulate.c delete_sec_context.c display_name.c display_status.c duplicate_name.c encapsulate.c export_name.c external.c get_mic.c gssapi.h gssapi_locl.h import_name.c indicate_mechs.c init.c init_sec_context.c inquire_context.c inquire_cred.c release_buffer.c release_cred.c release_name.c release_oid_set.c test_oid_set_member.c unwrap.c v1.c verify_mic.c wrap.c
+libgssapi_la_SOURCES = 8003.c accept_sec_context.c acquire_cred.c add_oid_set_member.c canonicalize_name.c compare_name.c context_time.c create_emtpy_oid_set.c decapsulate.c delete_sec_context.c display_name.c display_status.c duplicate_name.c encapsulate.c export_sec_context.c export_name.c external.c get_mic.c gssapi.h gssapi_locl.h import_name.c import_sec_context.c indicate_mechs.c init.c init_sec_context.c inquire_context.c inquire_cred.c release_buffer.c release_cred.c release_name.c release_oid_set.c test_oid_set_member.c unwrap.c v1.c verify_mic.c wrap.c
mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
CONFIG_HEADER = ../../include/config.h
@@ -199,11 +199,12 @@ libgssapi_la_OBJECTS = 8003.lo accept_sec_context.lo acquire_cred.lo \
add_oid_set_member.lo canonicalize_name.lo compare_name.lo \
context_time.lo create_emtpy_oid_set.lo decapsulate.lo \
delete_sec_context.lo display_name.lo display_status.lo \
-duplicate_name.lo encapsulate.lo export_name.lo external.lo get_mic.lo \
-import_name.lo indicate_mechs.lo init.lo init_sec_context.lo \
-inquire_context.lo inquire_cred.lo release_buffer.lo release_cred.lo \
-release_name.lo release_oid_set.lo test_oid_set_member.lo unwrap.lo \
-v1.lo verify_mic.lo wrap.lo
+duplicate_name.lo encapsulate.lo export_sec_context.lo export_name.lo \
+external.lo get_mic.lo import_name.lo import_sec_context.lo \
+indicate_mechs.lo init.lo init_sec_context.lo inquire_context.lo \
+inquire_cred.lo release_buffer.lo release_cred.lo release_name.lo \
+release_oid_set.lo test_oid_set_member.lo unwrap.lo v1.lo verify_mic.lo \
+wrap.lo
CFLAGS = @CFLAGS@
COMPILE = $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
LTCOMPILE = $(LIBTOOL) --mode=compile $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
diff --git a/crypto/heimdal/lib/gssapi/accept_sec_context.c b/crypto/heimdal/lib/gssapi/accept_sec_context.c
index 4d9a2b0..3f61ae1 100644
--- a/crypto/heimdal/lib/gssapi/accept_sec_context.c
+++ b/crypto/heimdal/lib/gssapi/accept_sec_context.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,7 +33,7 @@
#include "gssapi_locl.h"
-RCSID("$Id: accept_sec_context.c,v 1.15 1999/12/26 18:32:08 assar Exp $");
+RCSID("$Id: accept_sec_context.c,v 1.17 2000/02/12 21:24:08 assar Exp $");
static krb5_keytab gss_keytab;
@@ -53,7 +53,8 @@ gsskrb5_register_acceptor_identity (char *identity)
return GSS_S_COMPLETE;
}
-OM_uint32 gss_accept_sec_context
+OM_uint32
+gss_accept_sec_context
(OM_uint32 * minor_status,
gss_ctx_id_t * context_handle,
const gss_cred_id_t acceptor_cred_handle,
@@ -151,6 +152,14 @@ OM_uint32 gss_accept_sec_context
goto failure;
}
+ kret = krb5_copy_principal (gssapi_krb5_context,
+ ticket->server,
+ &(*context_handle)->target);
+ if (kret) {
+ ret = GSS_S_FAILURE;
+ goto failure;
+ }
+
if (src_name) {
kret = krb5_copy_principal (gssapi_krb5_context,
ticket->client,
@@ -182,6 +191,8 @@ OM_uint32 gss_accept_sec_context
}
}
+ flags |= GSS_C_TRANS_FLAG;
+
if (ret_flags)
*ret_flags = flags;
(*context_handle)->flags = flags;
diff --git a/crypto/heimdal/lib/gssapi/delete_sec_context.c b/crypto/heimdal/lib/gssapi/delete_sec_context.c
index faa77e4..15e3cfa 100644
--- a/crypto/heimdal/lib/gssapi/delete_sec_context.c
+++ b/crypto/heimdal/lib/gssapi/delete_sec_context.c
@@ -33,7 +33,7 @@
#include "gssapi_locl.h"
-RCSID("$Id: delete_sec_context.c,v 1.6 2000/01/26 00:45:46 assar Exp $");
+RCSID("$Id: delete_sec_context.c,v 1.7 2000/02/11 23:00:48 assar Exp $");
OM_uint32 gss_delete_sec_context
(OM_uint32 * minor_status,
@@ -60,5 +60,6 @@ OM_uint32 gss_delete_sec_context
krb5_free_ticket (gssapi_krb5_context,
(*context_handle)->ticket);
free (*context_handle);
+ *context_handle = GSS_C_NO_CONTEXT;
return GSS_S_COMPLETE;
}
diff --git a/crypto/heimdal/lib/gssapi/export_sec_context.c b/crypto/heimdal/lib/gssapi/export_sec_context.c
new file mode 100644
index 0000000..d982be7
--- /dev/null
+++ b/crypto/heimdal/lib/gssapi/export_sec_context.c
@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 1999 - 2000 Kungliga Tekniska Högskolan
+ * (Royal Institute of Technology, Stockholm, Sweden).
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the Institute nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#include "gssapi_locl.h"
+
+RCSID("$Id: export_sec_context.c,v 1.2 2000/02/12 21:25:24 assar Exp $");
+
+OM_uint32
+gss_export_sec_context (
+ OM_uint32 * minor_status,
+ gss_ctx_id_t * context_handle,
+ gss_buffer_t interprocess_token
+ )
+{
+ krb5_storage *sp;
+ krb5_auth_context ac;
+ unsigned char auth_buf[1024];
+ size_t sz;
+ int ret;
+ krb5_data data;
+ gss_buffer_desc buffer;
+ int flags;
+
+ gssapi_krb5_init ();
+ if (!((*context_handle)->flags & GSS_C_TRANS_FLAG))
+ return GSS_S_UNAVAILABLE;
+
+ sp = krb5_storage_emem ();
+ if (sp == NULL) {
+ *minor_status = ENOMEM;
+ return GSS_S_FAILURE;
+ }
+ ac = (*context_handle)->auth_context;
+
+ /* flagging included fields */
+
+ flags = 0;
+ if (ac->local_address)
+ flags |= SC_LOCAL_ADDRESS;
+ if (ac->remote_address)
+ flags |= SC_REMOTE_ADDRESS;
+ if (ac->keyblock)
+ flags |= SC_KEYBLOCK;
+ if (ac->local_subkey)
+ flags |= SC_LOCAL_SUBKEY;
+ if (ac->remote_subkey)
+ flags |= SC_REMOTE_SUBKEY;
+
+ krb5_store_int32 (sp, flags);
+
+ /* marshall auth context */
+
+ krb5_store_int32 (sp, ac->flags);
+ if (ac->local_address)
+ krb5_store_address (sp, *ac->local_address);
+ if (ac->remote_address)
+ krb5_store_address (sp, *ac->remote_address);
+ krb5_store_int16 (sp, ac->local_port);
+ krb5_store_int16 (sp, ac->remote_port);
+ if (ac->keyblock)
+ krb5_store_keyblock (sp, *ac->keyblock);
+ if (ac->local_subkey)
+ krb5_store_keyblock (sp, *ac->local_subkey);
+ if (ac->remote_subkey)
+ krb5_store_keyblock (sp, *ac->remote_subkey);
+ krb5_store_int32 (sp, ac->local_seqnumber);
+ krb5_store_int32 (sp, ac->remote_seqnumber);
+
+#if 0
+ ret = encode_Authenticator (auth_buf, sizeof(auth_buf),
+ ac->authenticator, &sz);
+ if (ret) {
+ krb5_storage_free (sp);
+ *minor_status = ret;
+ return GSS_S_FAILURE;
+ }
+ data.data = auth_buf;
+ data.length = sz;
+ krb5_store_data (sp, data);
+#endif
+ krb5_store_int32 (sp, ac->keytype);
+ krb5_store_int32 (sp, ac->cksumtype);
+
+ /* names */
+
+ gss_export_name (minor_status, (*context_handle)->source, &buffer);
+ data.data = buffer.value;
+ data.length = buffer.length;
+ krb5_store_data (sp, data);
+
+ gss_export_name (minor_status, (*context_handle)->target, &buffer);
+ data.data = buffer.value;
+ data.length = buffer.length;
+ krb5_store_data (sp, data);
+
+ krb5_store_int32 (sp, (*context_handle)->flags);
+ krb5_store_int32 (sp, (*context_handle)->more_flags);
+
+ ret = krb5_storage_to_data (sp, &data);
+ krb5_storage_free (sp);
+ if (ret) {
+ *minor_status = ret;
+ return GSS_S_FAILURE;
+ }
+ interprocess_token->length = data.length;
+ interprocess_token->value = data.data;
+ ret = gss_delete_sec_context (minor_status, context_handle,
+ GSS_C_NO_BUFFER);
+ if (ret != GSS_S_COMPLETE)
+ gss_release_buffer (NULL, interprocess_token);
+ return ret;
+}
diff --git a/crypto/heimdal/lib/gssapi/gssapi_locl.h b/crypto/heimdal/lib/gssapi/gssapi_locl.h
index f488a20..53f9cdc 100644
--- a/crypto/heimdal/lib/gssapi/gssapi_locl.h
+++ b/crypto/heimdal/lib/gssapi/gssapi_locl.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -31,7 +31,7 @@
* SUCH DAMAGE.
*/
-/* $Id: gssapi_locl.h,v 1.11 1999/12/02 17:05:03 joda Exp $ */
+/* $Id: gssapi_locl.h,v 1.12 2000/02/12 21:26:26 assar Exp $ */
#ifndef GSSAPI_LOCL_H
#define GSSAPI_LOCL_H
@@ -86,4 +86,12 @@ OM_uint32
gss_krb5_getsomekey(const gss_ctx_id_t context_handle,
des_cblock *key);
+/* sec_context flags */
+
+#define SC_LOCAL_ADDRESS 0x01
+#define SC_REMOTE_ADDRESS 0x02
+#define SC_KEYBLOCK 0x04
+#define SC_LOCAL_SUBKEY 0x08
+#define SC_REMOTE_SUBKEY 0x10
+
#endif
diff --git a/crypto/heimdal/lib/gssapi/import_sec_context.c b/crypto/heimdal/lib/gssapi/import_sec_context.c
new file mode 100644
index 0000000..2667637
--- /dev/null
+++ b/crypto/heimdal/lib/gssapi/import_sec_context.c
@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 1999 - 2000 Kungliga Tekniska Högskolan
+ * (Royal Institute of Technology, Stockholm, Sweden).
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the Institute nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#include "gssapi_locl.h"
+
+RCSID("$Id: import_sec_context.c,v 1.2 2000/02/12 21:26:00 assar Exp $");
+
+OM_uint32
+gss_import_sec_context (
+ OM_uint32 * minor_status,
+ const gss_buffer_t interprocess_token,
+ gss_ctx_id_t * context_handle
+ )
+{
+ OM_uint32 ret = GSS_S_FAILURE;
+ krb5_error_code kret;
+ krb5_storage *sp;
+ krb5_auth_context ac;
+ krb5_address local, remote;
+ krb5_address *localp, *remotep;
+ krb5_data data;
+ gss_buffer_desc buffer;
+ krb5_keyblock keyblock;
+ size_t sz;
+ int32_t tmp;
+ int32_t flags;
+
+ gssapi_krb5_init ();
+
+ sp = krb5_storage_from_mem (interprocess_token->value,
+ interprocess_token->length);
+ if (sp == NULL) {
+ *minor_status = ENOMEM;
+ return GSS_S_FAILURE;
+ }
+
+ *context_handle = malloc(sizeof(**context_handle));
+ if (*context_handle == NULL) {
+ *minor_status = ENOMEM;
+ krb5_storage_free (sp);
+ return GSS_S_FAILURE;
+ }
+
+ kret = krb5_auth_con_init (gssapi_krb5_context,
+ &(*context_handle)->auth_context);
+ if (kret) {
+ *minor_status = kret;
+ ret = GSS_S_FAILURE;
+ goto failure;
+ }
+
+ /* flags */
+
+ krb5_ret_int32 (sp, &flags);
+
+ /* retrieve the auth context */
+
+ ac = (*context_handle)->auth_context;
+ krb5_ret_int32 (sp, &ac->flags);
+ if (flags & SC_LOCAL_ADDRESS)
+ krb5_ret_address (sp, localp = &local);
+ else
+ localp = NULL;
+ if (flags & SC_REMOTE_ADDRESS)
+ krb5_ret_address (sp, remotep = &remote);
+ else
+ remotep = NULL;
+ krb5_auth_con_setaddrs (gssapi_krb5_context, ac, localp, remotep);
+ if (localp)
+ krb5_free_address (gssapi_krb5_context, localp);
+ if (remotep)
+ krb5_free_address (gssapi_krb5_context, remotep);
+ krb5_ret_int16 (sp, &ac->local_port);
+ krb5_ret_int16 (sp, &ac->remote_port);
+ if (flags & SC_KEYBLOCK) {
+ krb5_ret_keyblock (sp, &keyblock);
+ krb5_auth_con_setkey (gssapi_krb5_context, ac, &keyblock);
+ krb5_free_keyblock_contents (gssapi_krb5_context, &keyblock);
+ }
+ if (flags & SC_LOCAL_SUBKEY) {
+ krb5_ret_keyblock (sp, &keyblock);
+ krb5_auth_con_setlocalsubkey (gssapi_krb5_context, ac, &keyblock);
+ krb5_free_keyblock_contents (gssapi_krb5_context, &keyblock);
+ }
+ if (flags & SC_REMOTE_SUBKEY) {
+ krb5_ret_keyblock (sp, &keyblock);
+ krb5_auth_con_setremotesubkey (gssapi_krb5_context, ac, &keyblock);
+ krb5_free_keyblock_contents (gssapi_krb5_context, &keyblock);
+ }
+ krb5_ret_int32 (sp, &ac->local_seqnumber);
+ krb5_ret_int32 (sp, &ac->remote_seqnumber);
+
+#if 0
+ krb5_ret_data (sp, &data);
+ ac->authenticator = malloc (sizeof (*ac->authenticator));
+ if (ac->authenticator == NULL) {
+ *minor_status = ENOMEM;
+ ret = GSS_S_FAILURE;
+ goto failure;
+ }
+
+ kret = decode_Authenticator (data.data, data.length,
+ ac->authenticator, &sz);
+ krb5_data_free (&data);
+ if (kret) {
+ *minor_status = kret;
+ ret = GSS_S_FAILURE;
+ goto failure;
+ }
+#endif
+
+ krb5_ret_int32 (sp, &tmp);
+ ac->keytype = tmp;
+ krb5_ret_int32 (sp, &tmp);
+ ac->cksumtype = tmp;
+
+ /* names */
+
+ krb5_ret_data (sp, &data);
+ buffer.value = data.data;
+ buffer.length = data.length;
+
+ gss_import_name (minor_status, &buffer, GSS_C_NO_OID,
+ &(*context_handle)->source);
+ krb5_data_free (&data);
+
+ krb5_ret_data (sp, &data);
+ buffer.value = data.data;
+ buffer.length = data.length;
+
+ gss_import_name (minor_status, &buffer, GSS_C_NO_OID,
+ &(*context_handle)->target);
+ krb5_data_free (&data);
+
+ krb5_ret_int32 (sp, &tmp);
+ (*context_handle)->flags = tmp;
+ krb5_ret_int32 (sp, &tmp);
+ (*context_handle)->more_flags = tmp;
+
+ (*context_handle)->ticket = NULL;
+
+ return GSS_S_COMPLETE;
+
+failure:
+ krb5_auth_con_free (gssapi_krb5_context,
+ (*context_handle)->auth_context);
+ free (*context_handle);
+ *context_handle = GSS_C_NO_CONTEXT;
+ return ret;
+}
diff --git a/crypto/heimdal/lib/krb5/Makefile.am b/crypto/heimdal/lib/krb5/Makefile.am
index ab2182c..a5f60c0 100644
--- a/crypto/heimdal/lib/krb5/Makefile.am
+++ b/crypto/heimdal/lib/krb5/Makefile.am
@@ -1,4 +1,4 @@
-# $Id: Makefile.am,v 1.96 2000/02/07 03:26:21 assar Exp $
+# $Id: Makefile.am,v 1.97 2000/02/13 20:35:49 assar Exp $
include $(top_srcdir)/Makefile.am.common
@@ -119,7 +119,7 @@ libkrb5_la_SOURCES = \
EXTRA_libkrb5_la_SOURCES = keytab_krb4.c
-libkrb5_la_LDFLAGS = -version-info 8:0:0
+libkrb5_la_LDFLAGS = -version-info 9:0:0
$(libkrb5_la_OBJECTS): $(srcdir)/krb5-protos.h $(srcdir)/krb5-private.h
diff --git a/crypto/heimdal/lib/krb5/Makefile.in b/crypto/heimdal/lib/krb5/Makefile.in
index 33429d4..da4a0fb 100644
--- a/crypto/heimdal/lib/krb5/Makefile.in
+++ b/crypto/heimdal/lib/krb5/Makefile.in
@@ -10,7 +10,7 @@
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
-# $Id: Makefile.am,v 1.96 2000/02/07 03:26:21 assar Exp $
+# $Id: Makefile.am,v 1.97 2000/02/13 20:35:49 assar Exp $
# $Id: Makefile.am.common,v 1.3 1999/04/01 14:58:43 joda Exp $
@@ -195,7 +195,7 @@ libkrb5_la_SOURCES = add_et_list.c addr_families.c address.c aname_to_local
EXTRA_libkrb5_la_SOURCES = keytab_krb4.c
-libkrb5_la_LDFLAGS = -version-info 8:0:0
+libkrb5_la_LDFLAGS = -version-info 9:0:0
libkrb5_la_LIBADD = ../com_err/error.lo ../com_err/com_err.lo
diff --git a/crypto/heimdal/lib/krb5/changepw.c b/crypto/heimdal/lib/krb5/changepw.c
index fd94440..56c89a0 100644
--- a/crypto/heimdal/lib/krb5/changepw.c
+++ b/crypto/heimdal/lib/krb5/changepw.c
@@ -33,21 +33,17 @@
#include <krb5_locl.h>
-RCSID("$Id: changepw.c,v 1.19 1999/12/11 23:14:51 assar Exp $");
+RCSID("$Id: changepw.c,v 1.20 2000/02/07 13:40:18 joda Exp $");
static krb5_error_code
get_kdc_address (krb5_context context,
krb5_realm realm,
struct addrinfo **ai)
{
- struct addrinfo hints;
krb5_error_code ret;
char **hostlist;
int port = 0;
- char portstr[NI_MAXSERV];
int error;
- char *host;
- char *dot;
ret = krb5_get_krb_changepw_hst (context,
&realm,
@@ -55,24 +51,9 @@ get_kdc_address (krb5_context context,
if (ret)
return ret;
- host = *hostlist;
+ port = ntohs(krb5_getportbyname (context, "kpasswd", "udp", KPASSWD_PORT));
+ error = roken_getaddrinfo_hostspec(*hostlist, port, ai);
- dot = strchr (host, ':');
- if (dot != NULL) {
- char *end;
-
- *dot++ = '\0';
- port = strtol (dot, &end, 0);
- }
- if (port == 0)
- port = krb5_getportbyname (context, "kpasswd", "udp", KPASSWD_PORT);
- snprintf (portstr, sizeof(portstr), "%u", ntohs(port));
-
- memset (&hints, 0, sizeof(hints));
- hints.ai_socktype = SOCK_DGRAM;
- hints.ai_protocol = IPPROTO_UDP;
-
- error = getaddrinfo (host, portstr, &hints, ai);
krb5_free_krbhst (context, hostlist);
return error;
}
diff --git a/crypto/heimdal/lib/krb5/context.c b/crypto/heimdal/lib/krb5/context.c
index 1a7e941..fb3fb61 100644
--- a/crypto/heimdal/lib/krb5/context.c
+++ b/crypto/heimdal/lib/krb5/context.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,7 +33,7 @@
#include "krb5_locl.h"
-RCSID("$Id: context.c,v 1.52 2000/02/04 17:10:26 joda Exp $");
+RCSID("$Id: context.c,v 1.53 2000/02/11 17:43:43 assar Exp $");
#define INIT_FIELD(C, T, E, D, F) \
(C)->E = krb5_config_get_ ## T ## _default ((C), NULL, (D), \
@@ -318,7 +318,7 @@ krb5_add_extra_addresses(krb5_context context, krb5_addresses *addresses)
}
krb5_error_code
-krb5_set_extra_addresses(krb5_context context, krb5_addresses *addresses)
+krb5_set_extra_addresses(krb5_context context, const krb5_addresses *addresses)
{
if(context->extra_addresses) {
krb5_free_addresses(context, context->extra_addresses);
@@ -329,7 +329,7 @@ krb5_set_extra_addresses(krb5_context context, krb5_addresses *addresses)
if(context->extra_addresses == NULL)
return ENOMEM;
}
- return copy_HostAddresses(addresses, context->extra_addresses);
+ return krb5_copy_addresses(context, addresses, context->extra_addresses);
}
krb5_error_code
diff --git a/crypto/heimdal/lib/krb5/krb5-protos.h b/crypto/heimdal/lib/krb5/krb5-protos.h
index 1b0abdb..59402a7 100644
--- a/crypto/heimdal/lib/krb5/krb5-protos.h
+++ b/crypto/heimdal/lib/krb5/krb5-protos.h
@@ -449,6 +449,13 @@ krb5_change_password __P((
krb5_data *result_code_string,
krb5_data *result_string));
+krb5_error_code
+krb5_check_transited_realms __P((
+ krb5_context context,
+ const char *const *realms,
+ int num_realms,
+ int *bad_realm));
+
krb5_boolean
krb5_checksum_is_collision_proof __P((
krb5_context context,
@@ -1948,7 +1955,7 @@ krb5_set_default_realm __P((
krb5_error_code
krb5_set_extra_addresses __P((
krb5_context context,
- krb5_addresses *addresses));
+ const krb5_addresses *addresses));
krb5_error_code
krb5_set_fcache_version __P((
diff --git a/crypto/heimdal/lib/krb5/krb5_err.et b/crypto/heimdal/lib/krb5/krb5_err.et
index e8779df..895ae66 100644
--- a/crypto/heimdal/lib/krb5/krb5_err.et
+++ b/crypto/heimdal/lib/krb5/krb5_err.et
@@ -3,7 +3,7 @@
#
# This might look like a com_err file, but is not
#
-id "$Id: krb5_err.et,v 1.7 1999/02/11 21:03:40 joda Exp $"
+id "$Id: krb5_err.et,v 1.8 2000/02/07 12:54:17 joda Exp $"
error_table krb5
@@ -51,7 +51,7 @@ error_code ERR_BADVERSION, "Protocol version mismatch"
error_code ERR_MSG_TYPE, "Invalid message type"
error_code ERR_MODIFIED, "Message stream modified"
error_code ERR_BADORDER, "Message out of order"
-error_code ERR_ILL_CR_TKT, "Illegal cross-realm ticket"
+error_code ERR_ILL_CR_TKT, "Invalid cross-realm ticket"
error_code ERR_BADKEYVER, "Key version is not available"
error_code ERR_NOKEY, "Service key not available"
error_code ERR_MUT_FAIL, "Mutual authentication failed"
@@ -71,14 +71,14 @@ error_code FIELD_TOOLONG, "Field is too long for this implementation"
# 62-127 are reserved
index 128
prefix
-error_code KRB5_ERR_RCSID, "$Id: krb5_err.et,v 1.7 1999/02/11 21:03:40 joda Exp $"
+error_code KRB5_ERR_RCSID, "$Id: krb5_err.et,v 1.8 2000/02/07 12:54:17 joda Exp $"
error_code KRB5_LIBOS_BADLOCKFLAG, "Invalid flag for file lock mode"
error_code KRB5_LIBOS_CANTREADPWD, "Cannot read password"
error_code KRB5_LIBOS_BADPWDMATCH, "Password mismatch"
error_code KRB5_LIBOS_PWDINTR, "Password read interrupted"
-error_code KRB5_PARSE_ILLCHAR, "Illegal character in component name"
+error_code KRB5_PARSE_ILLCHAR, "Invalid character in component name"
error_code KRB5_PARSE_MALFORMED, "Malformed representation of principal"
error_code KRB5_CONFIG_CANTOPEN, "Can't open/find configuration file"
diff --git a/crypto/heimdal/lib/krb5/rd_req.c b/crypto/heimdal/lib/krb5/rd_req.c
index 236ecb4..bcf4ecf 100644
--- a/crypto/heimdal/lib/krb5/rd_req.c
+++ b/crypto/heimdal/lib/krb5/rd_req.c
@@ -33,7 +33,7 @@
#include <krb5_locl.h>
-RCSID("$Id: rd_req.c,v 1.40 2000/02/06 05:20:31 assar Exp $");
+RCSID("$Id: rd_req.c,v 1.41 2000/02/07 13:31:55 joda Exp $");
static krb5_error_code
decrypt_tkt_enc_part (krb5_context context,
@@ -188,6 +188,30 @@ out:
return ret;
}
+#if 0
+static krb5_error_code
+check_transited(krb5_context context,
+ krb5_ticket *ticket)
+{
+ char **realms;
+ int num_realms;
+ krb5_error_code ret;
+
+ if(ticket->ticket.transited.tr_type != DOMAIN_X500_COMPRESS)
+ return KRB5KDC_ERR_TRTYPE_NOSUPP;
+
+ ret = krb5_domain_x500_decode(ticket->ticket.transited.contents,
+ &realms, &num_realms,
+ ticket->client->realm,
+ ticket->server->realm);
+ if(ret)
+ return ret;
+ ret = krb5_check_transited_realms(context, realms, num_realms, NULL);
+ free(realms);
+ return ret;
+}
+#endif
+
krb5_error_code
krb5_verify_ap_req(krb5_context context,
krb5_auth_context *auth_context,
diff --git a/crypto/heimdal/lib/krb5/transited.c b/crypto/heimdal/lib/krb5/transited.c
index 2295551..1faf378 100644
--- a/crypto/heimdal/lib/krb5/transited.c
+++ b/crypto/heimdal/lib/krb5/transited.c
@@ -33,7 +33,7 @@
#include "krb5_locl.h"
-RCSID("$Id: transited.c,v 1.6 2000/02/07 03:19:43 assar Exp $");
+RCSID("$Id: transited.c,v 1.7 2000/02/07 13:30:41 joda Exp $");
/* this is an attempt at one of the most horrible `compression'
schemes that has ever been invented; it's so amazingly brain-dead
@@ -363,6 +363,35 @@ krb5_domain_x500_encode(char **realms, int num_realms, krb5_data *encoding)
return 0;
}
+krb5_error_code
+krb5_check_transited_realms(krb5_context context,
+ const char *const *realms,
+ int num_realms,
+ int *bad_realm)
+{
+ int i;
+ int ret = 0;
+ char **bad_realms = krb5_config_get_strings(context, NULL,
+ "libdefaults",
+ "transited_realms_reject",
+ NULL);
+ if(bad_realms == NULL)
+ return 0;
+
+ for(i = 0; i < num_realms; i++) {
+ char **p;
+ for(p = bad_realms; *p; p++)
+ if(strcmp(*p, realms[i]) == 0) {
+ ret = KRB5KRB_AP_ERR_ILL_CR_TKT;
+ if(bad_realm)
+ *bad_realm = i;
+ break;
+ }
+ }
+ krb5_config_free_strings(bad_realms);
+ return ret;
+}
+
#if 0
int
main(int argc, char **argv)
diff --git a/crypto/heimdal/lib/roken/ChangeLog b/crypto/heimdal/lib/roken/ChangeLog
index 4e7cd27..b157494 100644
--- a/crypto/heimdal/lib/roken/ChangeLog
+++ b/crypto/heimdal/lib/roken/ChangeLog
@@ -1,3 +1,11 @@
+2000-02-13 Assar Westerlund <assar@sics.se>
+
+ * Makefile.am: bump version to 7:0:2
+
+ * getarg.c (mandoc_template): also fix no- prefix in .Sh OPTIONS
+ * getarg.c (mandoc_template): better man-stuff for negative
+ options
+
2000-02-07 Assar Westerlund <assar@sics.se>
* Makefile.am: set version to 6:0:1
diff --git a/crypto/heimdal/lib/roken/Makefile.am b/crypto/heimdal/lib/roken/Makefile.am
index aea5099..d23fcb3 100644
--- a/crypto/heimdal/lib/roken/Makefile.am
+++ b/crypto/heimdal/lib/roken/Makefile.am
@@ -1,11 +1,11 @@
-# $Id: Makefile.am,v 1.67 2000/02/07 03:32:15 assar Exp $
+# $Id: Makefile.am,v 1.69 2000/02/13 20:34:03 assar Exp $
include $(top_srcdir)/Makefile.am.common
CLEANFILES = roken.h make-roken.c print_version.h
lib_LTLIBRARIES = libroken.la
-libroken_la_LDFLAGS = -version-info 6:0:1
+libroken_la_LDFLAGS = -version-info 7:0:2
noinst_PROGRAMS = make-roken make-print-version
@@ -32,6 +32,7 @@ libroken_la_SOURCES = \
erealloc.c \
estrdup.c \
ewrite.c \
+ getaddrinfo_hostspec.c \
get_default_username.c \
get_window_size.c \
getarg.c \
diff --git a/crypto/heimdal/lib/roken/Makefile.in b/crypto/heimdal/lib/roken/Makefile.in
index 3743418..65c3f99 100644
--- a/crypto/heimdal/lib/roken/Makefile.in
+++ b/crypto/heimdal/lib/roken/Makefile.in
@@ -10,7 +10,7 @@
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
-# $Id: Makefile.am,v 1.67 2000/02/07 03:32:15 assar Exp $
+# $Id: Makefile.am,v 1.69 2000/02/13 20:34:03 assar Exp $
# $Id: Makefile.am.common,v 1.3 1999/04/01 14:58:43 joda Exp $
@@ -176,7 +176,7 @@ CHECK_LOCAL = $(PROGRAMS)
CLEANFILES = roken.h make-roken.c print_version.h
lib_LTLIBRARIES = libroken.la
-libroken_la_LDFLAGS = -version-info 6:0:1
+libroken_la_LDFLAGS = -version-info 7:0:2
noinst_PROGRAMS = make-roken make-print-version
@@ -189,7 +189,7 @@ strpftime_test_SOURCES = strpftime-test.c strftime.c strptime.c snprintf.c
@KRB4_TRUE@@KRB5_TRUE@make_print_version_LDADD = $(LIB_krb4) -ldes
-libroken_la_SOURCES = base64.c concat.c emalloc.c eread.c erealloc.c estrdup.c ewrite.c get_default_username.c get_window_size.c getarg.c getnameinfo_verified.c issuid.c k_getpwnam.c k_getpwuid.c mini_inetd.c net_read.c net_write.c parse_bytes.c parse_time.c parse_units.c print_version.c resolve.c roken_gethostby.c signal.c simple_exec.c snprintf.c socket.c strcollect.c tm2time.c verify.c warnerr.c xdbm.h
+libroken_la_SOURCES = base64.c concat.c emalloc.c eread.c erealloc.c estrdup.c ewrite.c getaddrinfo_hostspec.c get_default_username.c get_window_size.c getarg.c getnameinfo_verified.c issuid.c k_getpwnam.c k_getpwuid.c mini_inetd.c net_read.c net_write.c parse_bytes.c parse_time.c parse_units.c print_version.c resolve.c roken_gethostby.c signal.c simple_exec.c snprintf.c socket.c strcollect.c tm2time.c verify.c warnerr.c xdbm.h
EXTRA_libroken_la_SOURCES = chown.c copyhostent.c daemon.c err.c err.h errx.c fchown.c flock.c fnmatch.c fnmatch.h freeaddrinfo.c freehostent.c gai_strerror.c getaddrinfo.c getdtablesize.c getegid.c geteuid.c getgid.c gethostname.c getipnodebyaddr.c getipnodebyname.c getnameinfo.c getopt.c gettimeofday.c getuid.c getusershell.c glob.h hstrerror.c inet_aton.c inet_ntop.c inet_pton.c initgroups.c innetgr.c iruserok.c lstat.c memmove.c mkstemp.c putenv.c rcmd.c readv.c recvmsg.c sendmsg.c setegid.c setenv.c seteuid.c strcasecmp.c strdup.c strerror.c strftime.c strlcat.c strlcpy.c strlwr.c strncasecmp.c strndup.c strnlen.c strptime.c strsep.c strtok_r.c strupr.c swab.c unsetenv.c verr.c verrx.c vsyslog.c vwarn.c vwarnx.c warn.c warnx.c writev.c
@@ -226,12 +226,13 @@ X_EXTRA_LIBS = @X_EXTRA_LIBS@
X_PRE_LIBS = @X_PRE_LIBS@
libroken_la_DEPENDENCIES = @LTLIBOBJS@
libroken_la_OBJECTS = base64.lo concat.lo emalloc.lo eread.lo \
-erealloc.lo estrdup.lo ewrite.lo get_default_username.lo \
-get_window_size.lo getarg.lo getnameinfo_verified.lo issuid.lo \
-k_getpwnam.lo k_getpwuid.lo mini_inetd.lo net_read.lo net_write.lo \
-parse_bytes.lo parse_time.lo parse_units.lo print_version.lo resolve.lo \
-roken_gethostby.lo signal.lo simple_exec.lo snprintf.lo socket.lo \
-strcollect.lo tm2time.lo verify.lo warnerr.lo
+erealloc.lo estrdup.lo ewrite.lo getaddrinfo_hostspec.lo \
+get_default_username.lo get_window_size.lo getarg.lo \
+getnameinfo_verified.lo issuid.lo k_getpwnam.lo k_getpwuid.lo \
+mini_inetd.lo net_read.lo net_write.lo parse_bytes.lo parse_time.lo \
+parse_units.lo print_version.lo resolve.lo roken_gethostby.lo signal.lo \
+simple_exec.lo snprintf.lo socket.lo strcollect.lo tm2time.lo verify.lo \
+warnerr.lo
check_PROGRAMS = parse_bytes-test$(EXEEXT) strpftime-test$(EXEEXT) \
getaddrinfo-test$(EXEEXT)
noinst_PROGRAMS = make-roken$(EXEEXT) make-print-version$(EXEEXT)
diff --git a/crypto/heimdal/lib/roken/getaddrinfo_hostspec.c b/crypto/heimdal/lib/roken/getaddrinfo_hostspec.c
new file mode 100644
index 0000000..76e5d2b
--- /dev/null
+++ b/crypto/heimdal/lib/roken/getaddrinfo_hostspec.c
@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2000 Kungliga Tekniska Högskolan
+ * (Royal Institute of Technology, Stockholm, Sweden).
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the Institute nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+RCSID("$Id: getaddrinfo_hostspec.c,v 1.1 2000/02/07 13:38:22 joda Exp $");
+#endif
+
+#include "roken.h"
+
+/* getaddrinfo via string specifying host and port */
+
+int
+roken_getaddrinfo_hostspec(const char *hostspec,
+ int port,
+ struct addrinfo **ai)
+{
+ const char *p;
+ char portstr[NI_MAXSERV];
+ char host[MAXHOSTNAMELEN];
+ struct addrinfo hints;
+
+ struct hst {
+ const char *prefix;
+ int socktype;
+ int protocol;
+ int port;
+ } *hstp, hst[] = {
+ { "http://", SOCK_STREAM, IPPROTO_TCP, 80 },
+ { "http/", SOCK_STREAM, IPPROTO_TCP, 80 },
+ { "tcp/", SOCK_STREAM, IPPROTO_TCP },
+ { "udp/", SOCK_DGRAM, IPPROTO_UDP },
+ { NULL }
+ };
+
+ memset(&hints, 0, sizeof(hints));
+
+ for(hstp = hst; hstp->prefix; hstp++) {
+ if(strncmp(hostspec, hstp->prefix, strlen(hstp->prefix)) == 0) {
+ hints.ai_socktype = hstp->socktype;
+ hints.ai_protocol = hstp->protocol;
+ if(port == 0)
+ port = hstp->port;
+ hostspec += strlen(hstp->prefix);
+ break;
+ }
+ }
+
+ p = strchr (hostspec, ':');
+ if (p != NULL) {
+ char *end;
+
+ port = strtol (p + 1, &end, 0);
+ }
+ snprintf (portstr, sizeof(portstr), "%u", port);
+
+ snprintf (host, sizeof(host), "%.*s", p - hostspec, hostspec);
+ return getaddrinfo (host, portstr, &hints, ai);
+}
diff --git a/crypto/heimdal/lib/roken/getarg.c b/crypto/heimdal/lib/roken/getarg.c
index 505e418..d9a03a5 100644
--- a/crypto/heimdal/lib/roken/getarg.c
+++ b/crypto/heimdal/lib/roken/getarg.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1997 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -33,7 +33,7 @@
#ifdef HAVE_CONFIG_H
#include <config.h>
-RCSID("$Id: getarg.c,v 1.32 1999/12/02 16:58:46 joda Exp $");
+RCSID("$Id: getarg.c,v 1.34 2000/02/13 21:06:43 assar Exp $");
#endif
#include <stdio.h>
@@ -125,7 +125,9 @@ mandoc_template(struct getargs *args,
}
if(args[i].long_name) {
print_arg(buf, sizeof(buf), 1, 1, args + i);
- printf("Fl -%s%s", args[i].long_name, buf);
+ printf("Fl -%s%s%s",
+ args[i].type == arg_negative_flag ? "no-" : "",
+ args[i].long_name, buf);
}
printf("\n");
} else {
@@ -155,7 +157,9 @@ mandoc_template(struct getargs *args,
printf("\n");
}
if(args[i].long_name){
- printf(".Fl -%s", args[i].long_name);
+ printf(".Fl -%s%s",
+ args[i].type == arg_negative_flag ? "no-" : "",
+ args[i].long_name);
print_arg(buf, sizeof(buf), 1, 1, args + i);
printf("%s\n", buf);
}
diff --git a/crypto/heimdal/lib/roken/roken-common.h b/crypto/heimdal/lib/roken/roken-common.h
index b972024..8bdc986 100644
--- a/crypto/heimdal/lib/roken/roken-common.h
+++ b/crypto/heimdal/lib/roken/roken-common.h
@@ -31,7 +31,7 @@
* SUCH DAMAGE.
*/
-/* $Id: roken-common.h,v 1.25 2000/01/09 10:58:34 assar Exp $ */
+/* $Id: roken-common.h,v 1.27 2000/02/14 02:24:44 assar Exp $ */
#ifndef __ROKEN_COMMON_H__
#define __ROKEN_COMMON_H__
@@ -290,4 +290,5 @@ vstrcollect(va_list *ap);
char **
strcollect(char *first, ...);
+
#endif /* __ROKEN_COMMON_H__ */
diff --git a/crypto/heimdal/lib/roken/roken.h.in b/crypto/heimdal/lib/roken/roken.h.in
index 03cfce4..3abe6eb 100644
--- a/crypto/heimdal/lib/roken/roken.h.in
+++ b/crypto/heimdal/lib/roken/roken.h.in
@@ -1,6 +1,6 @@
/* -*- C -*- */
/*
- * Copyright (c) 1995, 1996, 1997, 1998, 1999 Kungliga Tekniska Högskolan
+ * Copyright (c) 1995 - 2000 Kungliga Tekniska Högskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
@@ -32,7 +32,7 @@
* SUCH DAMAGE.
*/
-/* $Id: roken.h.in,v 1.133 1999/12/30 02:22:54 assar Exp $ */
+/* $Id: roken.h.in,v 1.135 2000/02/14 02:24:20 assar Exp $ */
#include <stdio.h>
#include <stdlib.h>
@@ -521,6 +521,9 @@ getnameinfo_verified(const struct sockaddr *sa, socklen_t salen,
char *serv, size_t servlen,
int flags);
+int
+roken_getaddrinfo_hostspec(const char *, int, struct addrinfo **);
+
#ifndef HAVE_STRFTIME
size_t
strftime (char *buf, size_t maxsize, const char *format,
OpenPOWER on IntegriCloud