From 69414e22b995b6d161fc19bcab66823585f1d394 Mon Sep 17 00:00:00 2001 From: markm Date: Thu, 24 Feb 2000 11:19:29 +0000 Subject: Vendor import of Heimdal 0.2o --- crypto/heimdal/ChangeLog | 40 + crypto/heimdal/NEWS | 11 + crypto/heimdal/appl/telnet/ChangeLog | 5 + crypto/heimdal/appl/telnet/telnet/commands.c | 4 +- crypto/heimdal/appl/test/common.c | 6 +- crypto/heimdal/appl/test/gss_common.c | 6 +- crypto/heimdal/appl/test/gssapi_client.c | 127 +- crypto/heimdal/appl/test/gssapi_server.c | 153 +- crypto/heimdal/appl/test/test_locl.h | 5 +- crypto/heimdal/configure | 4 +- crypto/heimdal/configure.in | 4 +- crypto/heimdal/doc/ack.texi | 2 + crypto/heimdal/doc/standardisation/rfc2743.txt | 5659 +++++++++++++++++++++++ crypto/heimdal/doc/standardisation/rfc2744.txt | 5659 +++++++++++++++++++++++ crypto/heimdal/kdc/config.c | 76 +- crypto/heimdal/kdc/connect.c | 74 +- crypto/heimdal/kdc/kaserver.c | 6 +- crypto/heimdal/kdc/kdc.8 | 63 +- crypto/heimdal/kdc/kdc_locl.h | 7 +- crypto/heimdal/kdc/kerberos4.c | 6 +- crypto/heimdal/lib/gssapi/ChangeLog | 24 + crypto/heimdal/lib/gssapi/Makefile.am | 6 +- crypto/heimdal/lib/gssapi/Makefile.in | 17 +- crypto/heimdal/lib/gssapi/accept_sec_context.c | 17 +- crypto/heimdal/lib/gssapi/delete_sec_context.c | 3 +- crypto/heimdal/lib/gssapi/export_sec_context.c | 142 + crypto/heimdal/lib/gssapi/gssapi_locl.h | 12 +- crypto/heimdal/lib/gssapi/import_sec_context.c | 180 + crypto/heimdal/lib/krb5/Makefile.am | 4 +- crypto/heimdal/lib/krb5/Makefile.in | 4 +- crypto/heimdal/lib/krb5/changepw.c | 25 +- crypto/heimdal/lib/krb5/context.c | 8 +- crypto/heimdal/lib/krb5/krb5-protos.h | 9 +- crypto/heimdal/lib/krb5/krb5_err.et | 8 +- crypto/heimdal/lib/krb5/rd_req.c | 26 +- crypto/heimdal/lib/krb5/transited.c | 31 +- crypto/heimdal/lib/roken/ChangeLog | 8 + crypto/heimdal/lib/roken/Makefile.am | 5 +- crypto/heimdal/lib/roken/Makefile.in | 19 +- crypto/heimdal/lib/roken/getaddrinfo_hostspec.c | 89 + crypto/heimdal/lib/roken/getarg.c | 12 +- crypto/heimdal/lib/roken/roken-common.h | 3 +- crypto/heimdal/lib/roken/roken.h.in | 7 +- 43 files changed, 12345 insertions(+), 231 deletions(-) create mode 100644 crypto/heimdal/doc/standardisation/rfc2743.txt create mode 100644 crypto/heimdal/doc/standardisation/rfc2744.txt create mode 100644 crypto/heimdal/lib/gssapi/export_sec_context.c create mode 100644 crypto/heimdal/lib/gssapi/import_sec_context.c create mode 100644 crypto/heimdal/lib/roken/getaddrinfo_hostspec.c (limited to 'crypto') 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 + + * Release 0.2o + +2000-02-13 Assar Westerlund + + * 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 + and Chaskiel M Grundman + 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 + + * 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 + + * 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 + + * lib/krb5/changepw.c: use roken_getaddrinfo_hostspec + 2000-02-07 Assar Westerlund * 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 + + * telnet/commands.c (tn): only set tos for AF_INET. From + itojun@iijlab.net + 2000-02-07 Assar Westerlund * 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 #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 #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 #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 @@ -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 "" 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 as its + only member, followed by a call to gss_init_sec_context, specifying + 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 . + 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 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 + . 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 parameter) will not be + an MN; the exception to this is if the indicates + that the contiguous string provided via the + 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 + + /* + * If the platform supports the xom.h header file, it should be + * included here. + */ + #include + + + /* + * Now define the three implementation-dependent types. + */ + typedef gss_ctx_id_t; + typedef gss_cred_id_t; + typedef 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 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 #include -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 + + * Makefile.am: set version to 1:0:1 + +2000-02-12 Assar Westerlund + + * 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 + + * 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 * 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 -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 -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 + + * 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 * 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 +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 -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 @@ -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 #include @@ -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, -- cgit v1.1