Skip Menu |
 

Download (untitled) / with headers
text/plain 11.2KiB
From hartmans@MIT.EDU Sun Oct 6 01:32:45 1996
Received: from MIT.EDU (SOUTH-STATION-ANNEX.MIT.EDU [18.72.1.2]) by rt-11.MIT.EDU (8.7.5/8.7.3) with SMTP id BAA01132 for <bugs@RT-11.MIT.EDU>; Sun, 6 Oct 1996 01:32:44 -0400
Received: from STARKILLER.MIT.EDU by MIT.EDU with SMTP
id AA10805; Sun, 6 Oct 96 01:32:42 EDT
Received: by starkiller.MIT.EDU (5.x/4.7) id AA17176; Sun, 6 Oct 1996 01:32:40 -0400
Message-Id: <9610060532.AA17176@starkiller.MIT.EDU>
Date: Sun, 6 Oct 1996 01:32:40 -0400
From: hartmans@MIT.EDU
Reply-To: hartmans@MIT.EDU
To: krb5-bugs@MIT.EDU
Cc: tytso@MIT.EDU
Subject: add API versioning before next release
X-Send-Pr-Version: 3.99

Show quoted text
>Number: 66
>Category: krb5-libs
>Synopsis: add API versioning before next release
>Confidential: no
>Severity: critical
>Priority: high
>Responsible: bjaspan
>State: closed
>Class: change-request
>Submitter-Id: unknown
>Arrival-Date: Sun Oct e 01:33:00 EDT 1996
>Last-Modified: Mon Nov e 14:48:34 EST 1996
>Originator: Sam Hartman
>Organization:
mit
Show quoted text
>Release: 1.0-development
>Environment:

System: SunOS starkiller 5.4 Generic_101945-37 sun4m sparc


Show quoted text
>Description:
In short order, the Kerberos Team should decide whether it
will implement API versioning and if it should do so, decide how to
maintain compatability with Beta 7 while allowing for future
extensions.

I consider this to be a critical issue because without a good
policy for API extensibility, the future utility of Kerberos is
limited.

If this is to be implemented, it should happen before the next
release.


Show quoted text
>How-To-Repeat:

Show quoted text
>Fix:

Show quoted text
>Audit-Trail:

From: Sam Hartman <hartmans@MIT.EDU>
To: tytso@MIT.EDU
Cc: krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: 10 Oct 1996 21:15:48 -0400

Show quoted text
>>>>> "ytso" == tytso <tytso@MIT.EDU> writes:

Show quoted text
ytso> API Versioning is utterly trivial to do, and we can even do
ytso> it without breaking compatibility with Beta 7.

Agreed, although I wanted to open a PR to remind us to do it.

Show quoted text
ytso> The simple way (which will break compatiiblity), is to
ytso> change krb5_init_context() to take an extra argument, which
ytso> is the API version number.

Show quoted text
ytso> And the way to solve the Beta7 compatibility issue is to
ytso> simply *add* a new function, krb5_api_version(context,
ytso> version_number), which allows the application to declare
ytso> what version of the API it is expecting.

I don't like this solution because it increases the length of
the krb5 initialization sequence; there is an additional operation
that all future applications should perform.

I would rather have some new function say krb5_init_api that
initialized a context, and took an API version. It might even
initialize the error tables while it was working.

Show quoted text
ytso> - Ted

From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: hartmans@MIT.EDU
Cc: krb5-bugs@MIT.EDU, tytso@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Tue, 22 Oct 1996 17:37:27 -0400

The following text appeared in [krb5-libs/76], a duplicate of this PR
which has now been closed:

From: hartmans@MIT.EDU
Date: Sun, 6 Oct 1996 01:32:40 -0400

In short order, the Kerberos Team should decide whether it
will implement API versioning and if it should do so, decide how to
maintain compatability with Beta 7 while allowing for future
extensions.

API Versioning is utterly trivial to do, and we can even do it without
breaking compatibility with Beta 7.

The simple way (which will break compatiiblity), is to change
krb5_init_context() to take an extra argument, which is the API version
number.

And the way to solve the Beta7 compatibility issue is to simply *add* a
new function, krb5_api_version(context, version_number), which allows
the application to declare what version of the API it is expecting.

See? Not hard. And we don't need to do anything now, if we wish to add
it later. (Just assume tht if krb5_api_version() is not called, that it
is the "1.0" version of the API.)

- Ted

From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: tytso@MIT.EDU
Cc: hartmans@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: pending/76: Re: add API versioning before next release
Date: Mon, 7 Oct 1996 15:53:44 -0400

API Versioning is utterly trivial to do, and we can even do it without
breaking compatibility with Beta 7.

The simple way (which will break compatiiblity), is to change
krb5_init_context() to take an extra argument, which is the API version
number.

I would suggest just replacing krb5_init_context with, say,
krb5_init_api(krb5_context *context, int api_version) that does
everthing that krb5_init_context does but also allows an api version
to be specified. krb5_init_context can remain as a compat function
that calls krb5_init_api(context, version_1) since all code that uses
it expects to use the current api (which will be declared version 1).
Just like with the cc functions, I see no reason to make it necessary
to call two separate functions to specify api version and to init the
context; in fact, doing so could introduce headaches later on.

Barry

From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: krbdev@MIT.EDU
Cc: krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Tue, 22 Oct 1996 18:01:24 -0400

I propose the following changes to the krb5 api, to be made before the
next release.

* New symbols

#define KRB5_API_VERSION_MASK 0x12345100
#define KRB5_API_VERSION_1 (KRB5_API_VERSION_MASK | 0x01)

* New error codes

KRB5_BAD_API_VERSION: The value specified for api_version is not a
KRB5_API_VERSION_n constant.

KRB5_OLD_API_VERSION: The value specified for api_version is legal but
is no longer supported by this implementation.

KRB5_NEW_API_VERSION: The value specfiied for api_version is legal but
is not yet supported by this implementation.

* Header file changes

The symbol USE_KRB5_API_VERSION is defined to contain the API version
number used by the current source code being compiled. If the symbol
is not defined, the header files automatically define it to be the
newest API version supported by the library. Each krb5 header file
containing information that changes based on API version decides which
version to use based on the value of this symbol.

The krb5 libraries are entitled to assume that callers invoking them
at a given API version were compiled with the appropriate value of
USE_KRB5_API_VERSION.

* Function changes

** krb5_error_code krb5_init_api(int api_version, krb5_context *context)

Initializes the context \funcparam{*context} and the API for the
application, using the API version specified in api_version. Currently
the context contains the API version, encryption types, a pointer to
operating specific data and the default realm. In the future, the
context may be also contain thread specific data. The data in the
context should be freed with \funcname{krb5_free_context}.

Returns system errors, and KRB5_BAD_API_VERSION, KRB5_OLD_API_VERSION,
and KRB5_NEW_API_VERSION.

** krb5_error_code krb5_init_context(krb5_context *context)

This function is obsolete. For backwards compatibility, it is the
same as a call to krb5_init_api(KRB5_API_VERSION_1, context).

** krb5_init_ets(krb5_context context)

This function is now called automatically by krb5_init_api.
Applications may still call it directly but do not need to do so.
This function has been integrated into krb5_init_api to solve a
chicken and egg problem: krb5_init_api can return error codes, but
com_err cannot be used on those error codes until krb5_init_ets is
invoked, and since krb5_init_ets requires a context argument it is
impossible to call it before callng krb5_init_api.

From: Ezra Peisach <epeisach@MIT.EDU>
To: "Barry Jaspan" <bjaspan@MIT.EDU>
Cc: krbdev@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Wed, 23 Oct 1996 15:08:23 EDT

I like the ideas that you mentioned. I would like to add one more suggestions...
We have a number of "functions" that are handled by dispatch tables in
krb5.hin (i.e. krb5_encrypt, krb5_cc_*, krb5_rc_*) - should these
be proper functions as well - or will a dispatch table be sufficient forever?

Ezra

From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: epeisach@MIT.EDU
Cc: krbdev@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Wed, 23 Oct 1996 15:22:21 -0400

We have a number of "functions" that are handled by dispatch tables in
krb5.hin (i.e. krb5_encrypt, krb5_cc_*, krb5_rc_*) - should these
be proper functions as well - or will a dispatch table be
sufficient forever?

Hmmm. Good question.

Off the top of my head, though, I don't think it matters. For now,
each of those macros (I presume) passes the context through the
dispatch table to the called function. So, if we change the interface
of a krb5_cc_* (for example), we will have to update every cc type's
corresponding function to know about it. As for the macro itself, the
header files can arrange for it to be correct (we may add another
argument, for example) based on the USE_KRB5_API_VERSION symbol. At
some point in the future, we may want to convert them to real
functions, but I don't think api versioning will have anything to do
with the decision.

Barry

From: Ezra Peisach <epeisach@MIT.EDU>
To: "Barry Jaspan" <bjaspan@MIT.EDU>
Cc: krbdev@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Wed, 23 Oct 1996 15:29:10 EDT

They all pass the context down except for the entrys to the crypto system.
Maybe because we did not want to have the crypto library depend on the
krb5 library and the krb5 library depend on the crypto library....
I do not know the historical reason.... I think it would be safe to add the
context to those defines and have them ignored by the library currently.

Ezra

From: "Theodore Y. Ts'o" <tytso@MIT.EDU>
To: Ezra Peisach <epeisach@MIT.EDU>
Cc: "Barry Jaspan" <bjaspan@MIT.EDU>, krbdev@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: krb5-libs/66: add API versioning before next release
Date: Wed, 23 Oct 1996 15:56:27 -0400

Date: Wed, 23 Oct 1996 15:08:23 EDT
From: Ezra Peisach <epeisach@MIT.EDU>

I like the ideas that you mentioned.

So do I; we should just go ahead and do it.

We have a number of "functions" that are handled by dispatch tables in
krb5.hin (i.e. krb5_encrypt, krb5_cc_*, krb5_rc_*) - should these
be proper functions as well - or will a dispatch table be sufficient
forever?

I'd very much like to make the current macros which call the dispatch
tables be proper functions; this will allow us to move a lot of
interfaces which *should* be private into k5-int.h. It's not an
absolute requirement for the 1.0 release, and it'll be harder to do than
the API versioning, but it would be nice to do if we can get to it.

- Ted

State-Changed-From-To: open-closed
State-Changed-By: tytso
State-Changed-When: Mon Nov 4 14:47:50 1996
State-Changed-Why: We're not going to do API versioning for this
release. It's somewhat dubious how well it works, and this is
always something we can always add later if we decide it's a
good thing.

Show quoted text
>Unformatted:
Download (untitled) / with headers
text/plain 3.4KiB
From tytso@MIT.EDU Sun Oct 6 20:36:35 1996
Received: from MIT.EDU (SOUTH-STATION-ANNEX.MIT.EDU [18.72.1.2]) by rt-11.MIT.EDU (8.7.5/8.7.3) with SMTP id UAA06108 for <bugs@RT-11.MIT.EDU>; Sun, 6 Oct 1996 20:36:35 -0400
Received: from BLUEBOX-77.MIT.EDU by MIT.EDU with SMTP
id AA01829; Sun, 6 Oct 96 20:36:31 EDT
Received: by rsts-11.mit.edu (8.6.10/4.7) id UAA02944; Sun, 6 Oct 1996 20:36:28 -0400
Message-Id: <199610070036.UAA02944@rsts-11.mit.edu>
Date: Sun, 6 Oct 1996 20:36:28 -0400
From: tytso@MIT.EDU
To: hartmans@MIT.EDU
Cc: krb5-bugs@MIT.EDU
In-Reply-To: <9610060532.AA17176@starkiller.MIT.EDU> (hartmans@MIT.EDU)
Subject: Re: add API versioning before next release

Show quoted text
>Number: 76
>Category: krb5-libs
>Synopsis: Re: add API versioning before next release
>Confidential: yes
>Severity: critical
>Priority: high
>Responsible: bjaspan
>State: closed
>Class: sw-bug
>Submitter-Id: unknown
>Arrival-Date: Sun Oct e 20:37:00 EDT 1996
>Last-Modified: Tue Oct e 17:37:48 EDT 1996
>Originator:
>Organization:
>Release:
>Environment:
>Description:
>How-To-Repeat:
>Fix:
>Audit-Trail:

From: "Barry Jaspan" <bjaspan@MIT.EDU>
To: tytso@MIT.EDU
Cc: hartmans@MIT.EDU, krb5-bugs@MIT.EDU
Subject: Re: pending/76: Re: add API versioning before next release
Date: Mon, 7 Oct 1996 15:53:44 -0400

API Versioning is utterly trivial to do, and we can even do it without
breaking compatibility with Beta 7.

The simple way (which will break compatiiblity), is to change
krb5_init_context() to take an extra argument, which is the API version
number.

I would suggest just replacing krb5_init_context with, say,
krb5_init_api(krb5_context *context, int api_version) that does
everthing that krb5_init_context does but also allows an api version
to be specified. krb5_init_context can remain as a compat function
that calls krb5_init_api(context, version_1) since all code that uses
it expects to use the current api (which will be declared version 1).
Just like with the cc functions, I see no reason to make it necessary
to call two separate functions to specify api version and to init the
context; in fact, doing so could introduce headaches later on.

Barry

Responsible-Changed-From-To: gnats-admin->bjaspan
Responsible-Changed-By: tlyu
Responsible-Changed-When: Wed Oct 9 12:52:55 1996
Responsible-Changed-Why:
really part of krb5-libs/66

State-Changed-From-To: open-closed
State-Changed-By: bjaspan
State-Changed-When: Tue Oct 22 17:37:31 1996
State-Changed-Why:

This is a duplicate of [krb5-libs/66].


Show quoted text
>Unformatted:
From: hartmans@MIT.EDU
Date: Sun, 6 Oct 1996 01:32:40 -0400

In short order, the Kerberos Team should decide whether it
will implement API versioning and if it should do so, decide how to
maintain compatability with Beta 7 while allowing for future
extensions.

API Versioning is utterly trivial to do, and we can even do it without
breaking compatibility with Beta 7.

The simple way (which will break compatiiblity), is to change
krb5_init_context() to take an extra argument, which is the API version
number.

And the way to solve the Beta7 compatibility issue is to simply *add* a
new function, krb5_api_version(context, version_number), which allows
the application to declare what version of the API it is expecting.

See? Not hard. And we don't need to do anything now, if we wish to add
it later. (Just assume tht if krb5_api_version() is not called, that it
is the "1.0" version of the API.)

- Ted