Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 2572d5d

Browse files
Low-level Documentation Updates
This commit updates the low-level documentation, introducing method signatures as well as fixing typos.
1 parent c758fd4 commit 2572d5d

17 files changed

+225
-99
lines changed

‎docs/source/gssapi.raw.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ Core RFC 2744
1919
Names
2020
~~~~~
2121

22+
.. note::
23+
Some functions in the following section will refer to
24+
"mechanism names". These are not names of mechanisms.
25+
Instead, they are a special form of name specific to
26+
a given mechanism.
27+
2228
.. automodule:: gssapi.raw.names
2329
:members:
2430
:undoc-members:

‎gssapi/raw/creds.pyx

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ cdef class Creds:
8282

8383
def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
8484
"""
85+
acquire_cred(name=None, lifetime=None, mechs=None, usage='both')
8586
Get GSSAPI credentials for the given name and mechanisms.
8687
8788
This method gets GSSAPI credentials corresponding to the given name
@@ -159,10 +160,15 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
159160

160161
def release_cred(Creds creds not None):
161162
"""
163+
release_cred(creds)
162164
Release GSSAPI Credentials.
163165
164166
This method releases GSSAPI credentials.
165167
168+
Warning:
169+
This method is deprecated. Credentials are
170+
automatically freed by Python.
171+
166172
Args:
167173
creds (Creds): the credentials in question
168174
@@ -180,7 +186,10 @@ def release_cred(Creds creds not None):
180186
def add_cred(Creds input_cred, Name name not None, OID mech not None,
181187
usage='initiate', init_lifetime=None,
182188
accept_lifetime=None, mutate_input=False):
183-
"""Add a credential element to a credential.
189+
"""
190+
add_cred(input_cred, name, mech, usage='initiate', init_lifetime=None, \
191+
accept_lifetime=None, mutate_input=False)
192+
Add a credential element to a credential.
184193
185194
This method can be used to either compose two credentials (i.e., original
186195
and new credential), or to add a new element to an existing credential.
@@ -264,7 +273,9 @@ def add_cred(Creds input_cred, Name name not None, OID mech not None,
264273

265274
def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
266275
mechs=True):
267-
"""Inspect credentials for information
276+
"""
277+
inquire_cred(creds, name=True, lifetime=True, usage=True, mechs=True)
278+
Inspect credentials for information.
268279
269280
This method inspects a :class:`Creds` object for information.
270281
@@ -343,10 +354,14 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
343354
def inquire_cred_by_mech(Creds creds not None, OID mech not None,
344355
name=True, init_lifetime=True,
345356
accept_lifetime=True, usage=True):
346-
"""Inspect credentials for mechanism-specific
357+
"""
358+
inquire_cred_by_mech(creds, mech, name=True, init_lifetime=True, \
359+
accept_lifetime=True, usage=True)
360+
Inspect credentials for mechanism-specific information.
347361
348362
This method inspects a :class:`Creds` object for information
349-
specific to a particular mechanism.
363+
specific to a particular mechanism. It functions similarly
364+
to :func:`inquire_cred`.
350365
351366
Args:
352367
creds (Creds): the credentials to inspect

‎gssapi/raw/ext_cred_imp_exp.pyx

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,11 @@ cdef extern from "python_gssapi_ext.h":
2222

2323

2424
def export_cred(Creds creds not None):
25-
"""Export GSSAPI credentials object
25+
"""
26+
export_cred(creds)
27+
Export GSSAPI credentials.
2628
27-
This method exports a GSSSAPI credentials object into a token
29+
This method exports GSSSAPI credentials into a token
2830
which may be transmitted between different processes.
2931
3032
Args:
@@ -54,7 +56,9 @@ def export_cred(Creds creds not None):
5456

5557

5658
def import_cred(token not None):
57-
"""Import GSSAPI credentials from a token
59+
"""
60+
import_cred(token)
61+
Import GSSAPI credentials from a token.
5862
5963
This method imports a credentials object from a token
6064
previously exported by :func:`export_cred`.

‎gssapi/raw/ext_cred_store.pyx

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,10 @@ cdef void c_free_key_value_set(gss_key_value_set_desc *kvset):
9595

9696
def acquire_cred_from(dict store=None, Name name=None, lifetime=None,
9797
mechs=None, usage='both'):
98-
"""Acquire credentials from the given store
98+
"""
99+
acquire_cred_from(store=None, name=None, lifetime=None, mechs=None, \
100+
usage='both')
101+
Acquire credentials from the given store.
99102
100103
This method acquires credentials from the store specified by the
101104
given credential store information.
@@ -183,12 +186,15 @@ def add_cred_from(dict store, Creds input_creds,
183186
Name name not None, OID mech not None,
184187
usage='both', init_lifetime=None,
185188
accept_lifetime=None):
186-
"""Acquire credentials to add to the current set from the given store
189+
"""
190+
add_cred_from(store, input_creds, name, mech, usage='both', \
191+
init_lifetime=None, accept_lifetime=None)
192+
Acquire credentials to add to the current set from the given store.
187193
188194
This method works like :func:`acquire_cred_from`, except that it
189195
adds the acquired credentials for a single mechanism to a copy of
190196
the current set, instead of creating a new set for multiple mechanisms.
191-
Unlike :meth:`acquire`, you cannot pass None desired name or
197+
Unlike :func:`acquire_cred`, you cannot pass None for the desired name or
192198
mechanism.
193199
194200
The credential store information is a dictionary containing
@@ -273,7 +279,10 @@ def add_cred_from(dict store, Creds input_creds,
273279
def store_cred_into(dict store, Creds creds not None,
274280
usage='both', OID mech=None, bint overwrite=False,
275281
bint set_default=False):
276-
"""Store credentials to the given store
282+
"""
283+
store_cred_into(store, creds, usage='both', mech=None, overwrite=False, \
284+
set_default=False)
285+
Store credentials into the given store.
277286
278287
This method stores the given credentials into the store specified
279288
by the given store information. They may then be retrieved later using

‎gssapi/raw/ext_dce.pyx

Lines changed: 35 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ IOVBuffer = namedtuple('IOVBuffer', ['type', 'allocate', 'value'])
9191

9292

9393
cdef class IOV:
94+
"""A GSSAPI IOV"""
9495
# defined in ext_dce.pxd
9596

9697
# cdef int iov_len
@@ -304,24 +305,28 @@ cdef class IOV:
304305
def wrap_iov(SecurityContext context not None, IOV message not None,
305306
confidential=True, qop=None):
306307
"""
307-
Wrap/Encrypt an IOV message
308+
wrap_iov(context, message, confidential=True, qop=None)
309+
Wrap/Encrypt an IOV message.
308310
309311
This method wraps or encrypts an IOV message. The allocate
310-
parameter of the :class:`IOVBuffer` indicates whether or
311-
not that particular buffer should be automatically allocated
312-
(for use with padding, header, and trailer buffers).
312+
parameter of the :class:`IOVBuffer` objects in the :class:`IOV`
313+
indicates whether or not that particular buffer should be
314+
automatically allocated (for use with padding, header, and
315+
trailer buffers).
316+
317+
Warning:
318+
This modifies the input :class:`IOV`.
313319
314320
Args:
315321
context (SecurityContext): the current security context
316-
message (list): a list of :class:`IOVBuffer` objects
322+
message (IOV): an :class:`IOV` containing the message
317323
confidential (bool): whether or not to encrypt the message (True),
318324
or just wrap it with a MIC (False)
319325
qop (int): the desired Quality of Protection
320326
(or None for the default QoP)
321327
322328
Returns:
323-
WrapResult: the wrapped/encrypted message (IOV list), and
324-
whether or not encryption was actually used
329+
bool: whether or not confidentiality was actually used
325330
326331
Raises:
327332
GSSError
@@ -348,26 +353,31 @@ def wrap_iov(SecurityContext context not None, IOV message not None,
348353

349354
def unwrap_iov(SecurityContext context not None, IOV message not None):
350355
"""
351-
Unwrap/Decrypt an IOV message
356+
unwrap_iov(context, message)
357+
Unwrap/Decrypt an IOV message.
352358
353-
This method unwraps or decrypts an IOV message. The allocate
354-
parameter of the :class:`IOVBuffer` indicates whether or
355-
not that particular buffer should be automatically allocated
356-
(for use with padding, header, and trailer buffers).
359+
This method uwraps or decrypts an IOV message. The allocate
360+
parameter of the :class:`IOVBuffer` objects in the :class:`IOV`
361+
indicates whether or not that particular buffer should be
362+
automatically allocated (for use with padding, header, and
363+
trailer buffers).
357364
358365
As a special case, you may pass an entire IOV message
359366
as a single 'stream'. In this case, pass a buffer type
360367
of :attr:`IOVBufferType.stream` followed by a buffer type of
361368
:attr:`IOVBufferType.data`. The former should contain the
362369
entire IOV message, while the latter should be empty.
363370
371+
Warning:
372+
This modifies the input :class:`IOV`.
373+
364374
Args:
365375
context (SecurityContext): the current security context
366-
message (list): a list of :class:`IOVBuffer` objects
376+
message (IOV): an :class:`IOV` containing the message
367377
368378
Returns:
369-
UnwrapResult: the unwrapped/decrypted message, whether or not
370-
encryption was used, and the QoP used
379+
IOVUnwrapResult: whether or not confidentiality was used,
380+
and the QoP used.
371381
372382
Raises:
373383
GSSError
@@ -393,7 +403,8 @@ def unwrap_iov(SecurityContext context not None, IOV message not None):
393403
def wrap_iov_length(SecurityContext context not None, IOV message not None,
394404
confidential=True, qop=None):
395405
"""
396-
Appropriately size padding, trailer, and header IOV buffers
406+
wrap_iov_length(context, message, confidential=True, qop=None)
407+
Appropriately size padding, trailer, and header IOV buffers.
397408
398409
This method sets the length values on the IOV buffers. You
399410
should already have data provided for the data (and sign-only)
@@ -402,9 +413,12 @@ def wrap_iov_length(SecurityContext context not None, IOV message not None,
402413
In Python terms, this will result in an appropriately sized
403414
`bytes` object consisting of all zeros.
404415
416+
Warning:
417+
This modifies the input :class:`IOV`.
418+
405419
Args:
406420
context (SecurityContext): the current security context
407-
message (list): a list of :class:`IOVBuffer` objects
421+
message (IOV): an :class:`IOV` containing the message
408422
409423
Returns:
410424
WrapResult: a list of :class:IOVBuffer` objects, and whether or not
@@ -437,7 +451,8 @@ def wrap_iov_length(SecurityContext context not None, IOV message not None,
437451
def wrap_aead(SecurityContext context not None, bytes message not None,
438452
bytes associated=None, confidential=True, qop=None):
439453
"""
440-
Wrap/Encrypt an AEAD Message
454+
wrap_aead(context, message, associated=None, confidential=True, qop=None)
455+
Wrap/Encrypt an AEAD message.
441456
442457
This method takes an input message and associated data,
443458
and outputs and AEAD message.
@@ -492,7 +507,8 @@ def wrap_aead(SecurityContext context not None, bytes message not None,
492507
def unwrap_aead(SecurityContext context not None, bytes message not None,
493508
bytes associated=None):
494509
"""
495-
Unwrap/Decrypt an AEAD Message
510+
unwrap_aead(context, message, associated=None)
511+
Unwrap/Decrypt an AEAD message.
496512
497513
This method takes an encrpyted/wrapped AEAD message and some associated
498514
data, and returns an unwrapped/decrypted message.

‎gssapi/raw/ext_iov_mic.pyx

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,15 +34,19 @@ IOV.AUTO_ALLOC_BUFFERS.add(IOVBufferType.mic_token)
3434
def get_mic_iov(SecurityContext context not None, IOV message not None,
3535
qop=None):
3636
"""
37-
Generate MIC tokens for the given IOV message
37+
get_mic_iov(context, message, qop=None)
38+
Generate MIC tokens for the given IOV message.
3839
3940
This method generates a MIC token for the given IOV message, and places it
4041
in the :attr:`IOVBufferType.mic_token` buffer in the IOV. This method
4142
operates entirely in-place, and returns nothing.
4243
44+
Warning:
45+
This modifies the input :class:`IOV`.
46+
4347
Args:
4448
context (SecurityContext): the current security context
45-
message (list): a list of :class:`IOVBuffer` objects
49+
message (IOV): the :class:`IOV` containing the message
4650
qop (int): the desired Quality of Protection
4751
(or None for the default QoP)
4852
@@ -70,14 +74,18 @@ def get_mic_iov(SecurityContext context not None, IOV message not None,
7074
def get_mic_iov_length(SecurityContext context not None, IOV message not None,
7175
qop=None):
7276
"""
73-
Allocate space for the MIC buffer in the given IOV message
77+
get_mic_iov_length(context, message, qop=None)
78+
Allocate space for the MIC buffer in the given IOV message.
7479
7580
This method allocates space for the MIC token buffer
7681
(:attr:`IOVBufferType.mic_token`) in the given IOV message.
7782
83+
Warning:
84+
This modifies the input :class:`IOV`.
85+
7886
Args:
7987
context (SecurityContext): the current security context
80-
message (list): a list of :class:`IOVBuffer` objects
88+
message (IOV): the :class:`IOV` containing the message
8189
qop (int): the desired Quality of Protection
8290
(or None for the default QoP)
8391
@@ -105,15 +113,16 @@ def get_mic_iov_length(SecurityContext context not None, IOV message not None,
105113
def verify_mic_iov(SecurityContext context not None, IOV message not None,
106114
qop=None):
107115
"""
108-
Verify that the MIC matches the data in the given IOV message
116+
verify_mic_iov(context, message, qop=None)
117+
Verify that the MIC matches the data in the given IOV message.
109118
110119
This method verifies that the MIC token in the MIC buffer
111120
(:attr:`IOVBufferType.mic_token`) match the data buffer(s)
112121
in the given IOV method.
113122
114123
Args:
115124
context (SecurityContext): the current security context
116-
message (list): a list of :class:`IOVBuffer` objects
125+
message (IOV): the :class:`IOV` containing the message
117126
118127
Returns:
119128
int: the QoP used to generate the MIC token

‎gssapi/raw/ext_password.pyx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,15 @@ cdef extern from "python_gssapi_ext.h":
3030
def acquire_cred_with_password(Name name not None, password not None,
3131
lifetime=None, mechs=None, usage="initiate"):
3232
"""
33+
acquire_cred_with_password(name, password, lifetime=None, mechs=None, \
34+
usage="initiate")
3335
Acquire credentials through provided password.
3436
3537
This function is originally from Solaris and is not documented by either
3638
MIT or Heimdal.
3739
40+
In general, it functions similarly to :func:`acquire_cred`.
41+
3842
Args:
3943
name (Name): the name to acquire credentials for
4044
password (bytes): the password used to acquire credentialss with

‎gssapi/raw/ext_password_add.pyx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,15 @@ def add_cred_with_password(Creds input_cred not None, Name name not None,
3737
accept_lifetime=None):
3838

3939
"""
40+
add_cred_with_password(input_cred, name, mech, password, \
41+
usage='initiate', init_lifetime=None, accept_lifetime=None)
4042
Add a credential-element to a credential using provided password.
4143
4244
This function is originally from Solaris and is not documented by either
4345
MIT or Heimdal.
4446
47+
In general, it functions similarly to :func:`add_cred`.
48+
4549
Args:
4650
input_cred (Creds): the credentials to add to
4751
name (Name): the name to acquire credentials for

‎gssapi/raw/ext_rfc5588.pyx

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,10 @@ cdef extern from "python_gssapi.h":
2424

2525
def store_cred(Creds creds not None, usage='both', OID mech=None,
2626
bint overwrite=False, bint set_default=False):
27-
"""Store credentials to the default store
27+
"""
28+
store_cred(creds, usage='both', mech=None, overwrite=False, \
29+
set_default=False)
30+
Store credentials into the default store.
2831
2932
This method stores the given credentials into the default store.
3033
They may then be retrieved later using :func:`acquire_cred`.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /