Difference between revisions of "Projects/APIs for keytab and cccol content"
m (→Description) |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | {{project- |
+ | {{project-rel|1.11}} |
| − | This project is to implement the Heimdal API krb5_kt_have_content(). |
+ | This project is to implement the Heimdal API krb5_kt_have_content() and a new API krb5_cccol_have_content(). |
==Background== |
==Background== |
||
| − | In certain situations, it is desirable to know whether |
+ | In certain situations, it is desirable to know whether any keytab keys or credentials are available to the current process. For example, acquiring GSS acceptor credentials with the krb5 mech should fail immediately if the default keytab file doesn't exist. krb5_kt_resolve() does not answer this question, as it returns successfully even if the file doesn't exist. Similarly, acquiring GSS initiator credentials with the krb5 mech should fail immediately if the ccache collection (including the default ccache) is devoid of krb5 credentials. |
==Description== |
==Description== |
||
| − | The API |
+ | The API signatures are: |
krb5_error_code krb5_kt_have_content(krb5_context context, krb5_keytab keytab); |
krb5_error_code krb5_kt_have_content(krb5_context context, krb5_keytab keytab); |
||
| + | krb5_error_code krb5_cccol_have_content(krb5_context context); |
||
| − | + | krb5_kt_have_content returns 0 if keytab exists and contains entries, or KRB5_KT_NOTFOUND if it does not. krb5_cccol_have_content returns 0 if the ccache collection contains any krb5 credentials, or KRB5_CC_NOTFOUND if it does not. |
|
==Implementation== |
==Implementation== |
||
| − | The Heimdal implementation begins iterating over the keytab and returns true if one entry can be retrieved. We can make the implementation somewhat more efficient using a vtable method; for instance, the FILE keytab type can stat the keytab and return true if the file size is larger than the size of a keytab header. But this optimization is probably not worth the code footprint. |
+ | The Heimdal implementation of krb5_kt_have_content begins iterating over the keytab and returns true if one entry can be retrieved. We can make the implementation somewhat more efficient using a vtable method; for instance, the FILE keytab type can stat the keytab and return true if the file size is larger than the size of a keytab header. But this optimization is probably not worth the code footprint. Similar reasoning applies for the implementation of krb5_cccol_have_content(). |
| − | The KDB keytab is not iterable. Since KDBs are almost never empty, it is |
+ | The KDB keytab is not iterable. Since KDBs are almost never empty, it is reasonable to return true unconditionally for non-iterable keytabs. |
==Testing== |
==Testing== |
||
| − | The existing t_keytab.c test program can be augmented to test krb5_kt_have_content(). |
+ | The existing t_keytab.c test program can be augmented to test krb5_kt_have_content(). The existing t_cccursor.c and t_cccol.py tests can be augmented to test krb5_cccol_have_content(). |
==Documentation== |
==Documentation== |
||
| − | Doxygen markup for krb5_kt_have_content() should be sufficient. It may be worth briefly mentioning this API in our application programmer |
+ | Doxygen markup for krb5_kt_have_content() and krb5_cccol_have_content() should be sufficient. It may be worth briefly mentioning this API in our application programmer sections on keytabs and ccache collections when we have them. |
==Release notes== |
==Release notes== |
||
| + | Developer experience: |
||
* Add a new API krb5_kt_have_content() to determine whether a keytab exists and contains any entries. |
* Add a new API krb5_kt_have_content() to determine whether a keytab exists and contains any entries. |
||
| + | * Add a new API krb5_cccol_have_content() to determine whether the ccache collection contains any credentials. |
||
Latest revision as of 13:34, 15 June 2012
This project is to implement the Heimdal API krb5_kt_have_content() and a new API krb5_cccol_have_content().
Background
In certain situations, it is desirable to know whether any keytab keys or credentials are available to the current process. For example, acquiring GSS acceptor credentials with the krb5 mech should fail immediately if the default keytab file doesn't exist. krb5_kt_resolve() does not answer this question, as it returns successfully even if the file doesn't exist. Similarly, acquiring GSS initiator credentials with the krb5 mech should fail immediately if the ccache collection (including the default ccache) is devoid of krb5 credentials.
Description
The API signatures are:
krb5_error_code krb5_kt_have_content(krb5_context context, krb5_keytab keytab); krb5_error_code krb5_cccol_have_content(krb5_context context);
krb5_kt_have_content returns 0 if keytab exists and contains entries, or KRB5_KT_NOTFOUND if it does not. krb5_cccol_have_content returns 0 if the ccache collection contains any krb5 credentials, or KRB5_CC_NOTFOUND if it does not.
Implementation
The Heimdal implementation of krb5_kt_have_content begins iterating over the keytab and returns true if one entry can be retrieved. We can make the implementation somewhat more efficient using a vtable method; for instance, the FILE keytab type can stat the keytab and return true if the file size is larger than the size of a keytab header. But this optimization is probably not worth the code footprint. Similar reasoning applies for the implementation of krb5_cccol_have_content().
The KDB keytab is not iterable. Since KDBs are almost never empty, it is reasonable to return true unconditionally for non-iterable keytabs.
Testing
The existing t_keytab.c test program can be augmented to test krb5_kt_have_content(). The existing t_cccursor.c and t_cccol.py tests can be augmented to test krb5_cccol_have_content().
Documentation
Doxygen markup for krb5_kt_have_content() and krb5_cccol_have_content() should be sufficient. It may be worth briefly mentioning this API in our application programmer sections on keytabs and ccache collections when we have them.
Release notes
Developer experience:
- Add a new API krb5_kt_have_content() to determine whether a keytab exists and contains any entries.
- Add a new API krb5_cccol_have_content() to determine whether the ccache collection contains any credentials.
