From 2890d78a8c833c7867aefea74e2404bdd475aa03 Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Fri, 6 Aug 2021 06:47:20 +1000 Subject: [PATCH] Tidy up docs and turn warnings into errors Signed-off-by: Jordan Borean --- README.txt | 4 ++ docs/source/_static/.keep | 0 docs/source/gssapi.raw.rst | 35 ++++++++++ gssapi/creds.py | 65 +++++++++--------- gssapi/mechs.py | 8 +-- gssapi/names.py | 28 ++++---- gssapi/raw/chan_bindings.pyx | 6 +- gssapi/raw/creds.pyx | 49 +++++++------- gssapi/raw/ext_cred_imp_exp.pyx | 4 +- gssapi/raw/ext_cred_store.pyx | 21 +++--- gssapi/raw/ext_dce.pyx | 19 +++--- gssapi/raw/ext_dce_aead.pyx | 14 ++-- gssapi/raw/ext_ggf.pyx | 27 ++++---- gssapi/raw/ext_iov_mic.pyx | 21 ++++-- gssapi/raw/ext_password.pyx | 8 +-- gssapi/raw/ext_password_add.pyx | 6 +- gssapi/raw/ext_rfc4178.pyx | 6 +- gssapi/raw/ext_rfc5587.pyx | 31 ++++----- gssapi/raw/ext_rfc5588.pyx | 13 ++-- gssapi/raw/ext_rfc5801.pyx | 10 +-- gssapi/raw/ext_rfc6680.pyx | 40 +++++------ gssapi/raw/ext_s4u.pyx | 14 ++-- gssapi/raw/ext_set_cred_opt.pyx | 5 +- gssapi/raw/message.pyx | 65 +++++++++--------- gssapi/raw/misc.pyx | 12 ++-- gssapi/raw/names.pyx | 46 ++++++------- gssapi/raw/sec_contexts.pyx | 99 ++++++++++++++------------- gssapi/sec_contexts.py | 114 ++++++++++++++++---------------- setup.cfg | 1 + 29 files changed, 424 insertions(+), 347 deletions(-) create mode 100644 docs/source/_static/.keep diff --git a/README.txt b/README.txt index 21b69bc4..fc44bf27 100644 --- a/README.txt +++ b/README.txt @@ -143,10 +143,14 @@ Extensions In addition to RFC 2743/2744, Python-GSSAPI also has support for: +* RFC 4178 (GSS-API Negotiation Mechanism) + * RFC 5587 (Extended GSS Mechanism Inquiry APIs) * RFC 5588 (GSS-API Extension for Storing Delegated Credentials) +* RFC 5801 (GSS-API SASL Extensions) + * (Additional) Credential Store Extension * Services4User diff --git a/docs/source/_static/.keep b/docs/source/_static/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/gssapi.raw.rst b/docs/source/gssapi.raw.rst index 0083826e..909d1bf0 100644 --- a/docs/source/gssapi.raw.rst +++ b/docs/source/gssapi.raw.rst @@ -77,6 +77,20 @@ The following is a list of GSSAPI extensions supported by the low-level API. be compiled, and will simply not be available in the :mod:`gssapi.raw` namespace. +:rfc:`4178` (GSS-API Negotiation Mechanism) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_rfc4178 + :members: + :undoc-members: + +:rfc:`5587` (GSS-API Extension for Mech Attributes) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_rfc5587 + :members: + :undoc-members: + :rfc:`5588` (GSS-API Extension for Storing Delegated Credentials) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -84,6 +98,13 @@ The following is a list of GSSAPI extensions supported by the low-level API. :members: :undoc-members: +:rfc:`5801` (GSS-API SASL Extensions) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_rfc5801 + :members: + :undoc-members: + Credential Store Extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -127,6 +148,13 @@ IOV MIC Extensions :members: :undoc-members: +Global Grid Forum (GGF) Extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_ggf + :members: + :undoc-members: + Services4User Extensions ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -145,6 +173,13 @@ Acquiring Credentials With a Password Extensions :members: :undoc-members: +Other Extensions +~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_set_cred_opt + :members: + :undoc-members: + Exceptions ---------- diff --git a/gssapi/creds.py b/gssapi/creds.py index 2082a1dc..888fea50 100644 --- a/gssapi/creds.py +++ b/gssapi/creds.py @@ -37,11 +37,11 @@ class Credentials(rcreds.Creds): :meth:`acquire` method. Raises: - BadMechanismError - BadNameTypeError - BadNameError - ExpiredCredentialsError - MissingCredentialsError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ __slots__ = () @@ -108,8 +108,8 @@ def acquire(cls, name=None, lifetime=None, mechs=None, usage='both', extension. Args: - name (Name): the name associated with the credentials, - or None for the default name + name (~gssapi.names.Name): the name associated with the + credentials, or None for the default name lifetime (int): the desired lifetime of the credentials, or None for indefinite mechs (list): the desired :class:`MechType` OIDs to be used @@ -125,11 +125,11 @@ def acquire(cls, name=None, lifetime=None, mechs=None, usage='both', them Raises: - BadMechanismError - BadNameTypeError - BadNameError - ExpiredCredentialsError - MissingCredentialsError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ if store is None: @@ -166,7 +166,7 @@ def store(self, store=None, usage='both', mech=None, or None for the default store. usage (str): the usage to store the credentials with -- either 'both', 'initiate', or 'accept' - mech (OID): the :class:`MechType` to associate with the + mech (~gssapi.OID): the :class:`MechType` to associate with the stored credentials overwrite (bool): whether or not to overwrite existing credentials stored with the same name, etc @@ -177,11 +177,11 @@ def store(self, store=None, usage='both', mech=None, StoreCredResult: the results of the credential storing operation Raises: - GSSError - ExpiredCredentialsError - MissingCredentialsError - OperationUnavailableError - DuplicateCredentialsElementError + ~gssapi.exceptions.GSSError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.OperationUnavailableError + ~gssapi.exceptions.DuplicateCredentialsElementError """ if store is None: @@ -212,7 +212,7 @@ def impersonate(self, name=None, lifetime=None, mechs=None, :requires-ext:`s4u` Args: - name (Name): the name to impersonate + name (~gssapi.names.Name): the name to impersonate lifetime (int): the desired lifetime of the new credentials, or None for indefinite mechs (list): the desired :class:`MechType` OIDs for the new @@ -251,9 +251,9 @@ def inquire(self, name=True, lifetime=True, usage=True, mechs=True): with None used when the corresponding argument was False Raises: - MissingCredentialsError - InvalidCredentialsError - ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.InvalidCredentialsError + ~gssapi.exceptions.ExpiredCredentialsError """ res = rcreds.inquire_cred(self, name, lifetime, usage, mechs) @@ -274,7 +274,8 @@ def inquire_by_mech(self, mech, name=True, init_lifetime=True, about them. Args: - mech (OID): the mechanism for which to retrive the information + mech (~gssapi.OID): the mechanism for which to retrive the + information name (bool): get the name associated with the credentials init_lifetime (bool): get the remaining initiate lifetime for the credentials @@ -327,10 +328,10 @@ def add(self, name, mech, usage='both', `impersonator` argument. Args: - name (Name): the name associated with the - credentials - mech (OID): the desired :class:`MechType` to be used with the + name (~gssapi.names.Name): the name associated with the credentials + mech (~gssapi.OID): the desired :class:`MechType` to be used with + the credentials usage (str): the usage for the credentials -- either 'both', 'initiate', or 'accept' init_lifetime (int): the desired initiate lifetime of the @@ -349,12 +350,12 @@ def add(self, name, mech, usage='both', and the newly acquired ones. Raises: - BadMechanismError - BadNameTypeError - BadNameError - DuplicateCredentialsElementError - ExpiredCredentialsError - MissingCredentialsError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.DuplicateCredentialsElementError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ if store is not None and impersonator is not None: diff --git a/gssapi/mechs.py b/gssapi/mechs.py index 5e6b6825..f22819da 100644 --- a/gssapi/mechs.py +++ b/gssapi/mechs.py @@ -121,13 +121,13 @@ def from_name(cls, name=None): Get a generator of mechanisms that may be able to process the name Args: - name (Name): a name to inquire about + name (~gssapi.names.Name): a name to inquire about Returns: [Mechanism]: a set of mechanisms which support this name Raises: - GSSError + ~gssapi.exceptions.GSSError """ return (cls(mech) for mech in rmisc.inquire_mechs_for_name(name)) @@ -143,7 +143,7 @@ def from_sasl_name(cls, name=None): Mechanism: the desired mechanism Raises: - GSSError + ~gssapi.exceptions.GSSError :requires-ext:`rfc5801` """ @@ -173,7 +173,7 @@ def from_attrs(cls, desired_attrs=None, except_attrs=None, [Mechanism]: A set of mechanisms having the desired features. Raises: - GSSError + ~gssapi.exceptions.GSSError :requires-ext:`rfc5587` """ diff --git a/gssapi/names.py b/gssapi/names.py index acd4b8bd..3cb2ff4b 100644 --- a/gssapi/names.py +++ b/gssapi/names.py @@ -91,9 +91,9 @@ def __init__(self, base=None, name_type=None, token=None, composite=False): name type. Raises: - BadNameTypeError - BadNameError - BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.BadMechanismError """ if rname_rfc6680 is not None: @@ -137,14 +137,14 @@ def display_as(self, name_type): :requires-ext:`rfc6680` Args: - name_type (OID): the :class:`NameType` to use to display the given - name + name_type (~gssapi.OID): the :class:`NameType` to use to display + the given name Returns: str: the displayed name Raises: - OperationUnavailableError + ~gssapi.exceptions.OperationUnavailableError """ if rname_rfc6680 is None: @@ -189,9 +189,9 @@ def export(self, composite=False): bytes: the exported name in token form Raises: - MechanismNameRequiredError - BadNameTypeError - BadNameError + ~gssapi.exceptions.MechanismNameRequiredError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError """ if composite: @@ -211,15 +211,15 @@ def canonicalize(self, mech): to the given mechanism. Args: - mech (OID): the :class:`MechType` to use + mech (~gssapi.OID): the :class:`MechType` to use Returns: Name: the canonicalized name Raises: - BadMechanismError - BadNameTypeError - BadNameError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError """ return type(self)(rname.canonicalize_name(self, mech)) @@ -249,7 +249,7 @@ def _inquire(self, **kwargs): fields set to None Raises: - GSSError + ~gssapi.exceptions.GSSError """ if rname_rfc6680 is None: diff --git a/gssapi/raw/chan_bindings.pyx b/gssapi/raw/chan_bindings.pyx index 737b5b1a..d66f587a 100644 --- a/gssapi/raw/chan_bindings.pyx +++ b/gssapi/raw/chan_bindings.pyx @@ -22,9 +22,11 @@ cdef class ChannelBindings: acceptor_address=None, application_data=None): """ Args: - initiator_address_type (AddressType): the initiator address type + initiator_address_type (~gssapi.AddressType): the initiator address + type initiator_address (bytes): the initiator address - acceptor_address_type (AddressType): the acceptor address type + acceptor_address_type (~gssapi.AddressType): the acceptor address + type acceptor_address (bytes): the acceptor address application_data (bytes): additional application-specific data """ diff --git a/gssapi/raw/creds.pyx b/gssapi/raw/creds.pyx index d123857d..caac3ea6 100644 --- a/gssapi/raw/creds.pyx +++ b/gssapi/raw/creds.pyx @@ -90,12 +90,12 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'): be specified. Args: - name (Name): the name for which to acquire the credentials (or None - for the "no name" functionality) + name (~gssapi.raw.names.Name): the name for which to acquire the + credentials (or None for the "no name" functionality) lifetime (int): the lifetime for the credentials (or None for indefinite) - mechs ([MechType]): the desired mechanisms for which the credentials - should work, or None for the default set + mechs (~gssapi.MechType): the desired mechanisms for which the + credentials should work, or None for the default set usage (str): the usage type for the credentials: may be 'initiate', 'accept', or 'both' @@ -105,11 +105,11 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'): indefinite or not supported) Raises: - BadMechanismError - BadNameTypeError - BadNameError - ExpiredCredentialsError - MissingCredentialsError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ cdef gss_OID_set desired_mechs @@ -176,7 +176,7 @@ def release_cred(Creds creds not None): creds (Creds): the credentials in question Raises: - MissingCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ cdef OM_uint32 maj_stat, min_stat @@ -200,8 +200,9 @@ accept_lifetime=None, mutate_input=False) Args: input_cred (Cred): the set of credentials to which to add the new credentials - name (Name): name of principal to acquire a credential for - mech (MechType): the desired security mechanism (required). + name (~gssapi.raw.names.Name): name of principal to acquire a + credential for + mech (~gssapi.MechType): the desired security mechanism (required). usage (str): usage type for credentials. Possible values: 'initiate' (default), 'accept', 'both' (failsafe). init_lifetime (int): lifetime of credentials for use in initiating @@ -218,12 +219,12 @@ accept_lifetime=None, mutate_input=False) be set to None if mutate_input is set to True. Raises: - BadMechanismError - BadNameTypeError - BadNameError - DuplicateCredentialsElementError - ExpiredCredentialsError - MissingCredentialsError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.DuplicateCredentialsElementError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError """ cdef gss_cred_usage_t c_usage if usage == 'initiate': @@ -297,9 +298,9 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True, with unused fields set to None Raises: - MissingCredentialsError - InvalidCredentialsError - ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.InvalidCredentialsError + ~gssapi.exceptions.ExpiredCredentialsError """ # TODO(directxman12): add docs @@ -371,7 +372,7 @@ accept_lifetime=True, usage=True) Args: creds (Creds): the credentials to inspect - mech (OID): the desired mechanism + mech (~gssapi.OID): the desired mechanism name (bool): get the Name associated with the credentials init_lifetime (bool): get the initiator TTL for the credentials accept_lifetime (bool): get the acceptor TTL for the credentials @@ -382,8 +383,8 @@ accept_lifetime=True, usage=True) with unused fields set to None Raises: - MissingCredentialsError - InvalidCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.InvalidCredentialsError """ # TODO(directxman12): add docs diff --git a/gssapi/raw/ext_cred_imp_exp.pyx b/gssapi/raw/ext_cred_imp_exp.pyx index ce525245..aa43cf86 100644 --- a/gssapi/raw/ext_cred_imp_exp.pyx +++ b/gssapi/raw/ext_cred_imp_exp.pyx @@ -36,7 +36,7 @@ def export_cred(Creds creds not None): bytes: the exported token representing the given credentials object Raises: - GSSError + ~gssapi.exceptions.GSSError """ # GSS_C_EMPTY_BUFFER @@ -70,7 +70,7 @@ def import_cred(token not None): Creds: the imported credentials object Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token) diff --git a/gssapi/raw/ext_cred_store.pyx b/gssapi/raw/ext_cred_store.pyx index 6b72f6ce..5edd5e65 100644 --- a/gssapi/raw/ext_cred_store.pyx +++ b/gssapi/raw/ext_cred_store.pyx @@ -120,8 +120,8 @@ usage='both') store (dict): the credential store information pointing to the credential store from which to acquire the credentials. See :doc:`credstore` for valid values - name (Name): the name associated with the credentials, - or None for the default name + name (~gssapi.raw.names.Name): the name associated with the + credentials, or None for the default name lifetime (int): the desired lifetime of the credentials, or None for indefinite mechs (list): the desired mechanisms to be used with these @@ -131,10 +131,10 @@ usage='both') Returns: AcquireCredResult: the acquired credentials and information about - them + them Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID_set desired_mechs @@ -218,8 +218,8 @@ init_lifetime=None, accept_lifetime=None) store (dict): the store into which to store the credentials, or None for the default store. See :doc:`credstore` for valid values - name (Name): the name associated with the credentials - mech (OID): the desired mechanism to be used with these + name (~gssapi.raw.names.Name): the name associated with the credentials + mech (~gssapi.OID): the desired mechanism to be used with these credentials usage (str): the usage for these credentials -- either 'both', 'initiate', or 'accept' @@ -230,10 +230,10 @@ init_lifetime=None, accept_lifetime=None) Returns: AcquireCredResult: the new credentials set and information about - it + it Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef OM_uint32 input_initiator_ttl = c_py_ttl_to_c(init_lifetime) @@ -316,7 +316,8 @@ set_default=False) creds (Creds): the credentials to store usage (str): the usage to store the credentials with -- either 'both', 'initiate', or 'accept' - mech (OID): the mechansim to associate with the stored credentials + mech (~gssapi.OID): the mechansim to associate with the stored + credentials overwrite (bool): whether or not to overwrite existing credentials stored with the same name, etc set_default (bool): whether or not to set these credentials as @@ -326,7 +327,7 @@ set_default=False) StoreCredResult: the results of the credential storing operation Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID desired_mech diff --git a/gssapi/raw/ext_dce.pyx b/gssapi/raw/ext_dce.pyx index a6aa8de9..7cc44b25 100644 --- a/gssapi/raw/ext_dce.pyx +++ b/gssapi/raw/ext_dce.pyx @@ -322,7 +322,8 @@ def wrap_iov(SecurityContext context not None, IOV message not None, This modifies the input :class:`IOV`. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): an :class:`IOV` containing the message confidential (bool): whether or not to encrypt the message (True), or just wrap it with a MIC (False) @@ -333,7 +334,7 @@ def wrap_iov(SecurityContext context not None, IOV message not None, bool: whether or not confidentiality was actually used Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef int conf_req = confidential @@ -376,15 +377,16 @@ def unwrap_iov(SecurityContext context not None, IOV message not None): This modifies the input :class:`IOV`. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): an :class:`IOV` containing the message Returns: IOVUnwrapResult: whether or not confidentiality was used, - and the QoP used. + and the QoP used. Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef int conf_used @@ -421,15 +423,16 @@ def wrap_iov_length(SecurityContext context not None, IOV message not None, This modifies the input :class:`IOV`. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): an :class:`IOV` containing the message Returns: WrapResult: a list of :class:IOVBuffer` objects, and whether or not - encryption was actually used + encryption was actually used Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef int conf_req = confidential diff --git a/gssapi/raw/ext_dce_aead.pyx b/gssapi/raw/ext_dce_aead.pyx index 4272b27b..32af479b 100644 --- a/gssapi/raw/ext_dce_aead.pyx +++ b/gssapi/raw/ext_dce_aead.pyx @@ -31,7 +31,8 @@ def wrap_aead(SecurityContext context not None, bytes message not None, and outputs and AEAD message. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the message to wrap or encrypt associated (bytes): associated data to go with the message confidential (bool): whether or not to encrypt the message (True), @@ -41,10 +42,10 @@ def wrap_aead(SecurityContext context not None, bytes message not None, Returns: WrapResult: the wrapped/encrypted total message, and whether or not - encryption was actually used + encryption was actually used Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef int conf_req = confidential @@ -87,16 +88,17 @@ def unwrap_aead(SecurityContext context not None, bytes message not None, data, and returns an unwrapped/decrypted message. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the AEAD message to unwrap or decrypt associated (bytes): associated data that goes with the message Returns: UnwrapResult: the unwrapped/decrypted message, whether or on - encryption was used, and the QoP used + encryption was used, and the QoP used Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc input_buffer = gss_buffer_desc(len(message), message) diff --git a/gssapi/raw/ext_ggf.pyx b/gssapi/raw/ext_ggf.pyx index 7da82c93..249631ac 100644 --- a/gssapi/raw/ext_ggf.pyx +++ b/gssapi/raw/ext_ggf.pyx @@ -47,14 +47,14 @@ def inquire_cred_by_oid(Creds cred_handle not None, Args: cred_handle (Creds): the Credentials to query - desired_aspect (OID): the desired aspect of the Credentials to inquire - about. + desired_aspect (~gssapi.OID): the desired aspect of the Credentials + to inquire about. Returns: list: A list of zero or more pieces of data (as bytes objects) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_set_t *data_set_ptr = NULL @@ -96,15 +96,16 @@ def inquire_sec_context_by_oid(SecurityContext context not None, encryption keys. Args: - context (SecurityContext): the Security Context to query - desired_aspect (OID): the desired aspect of the Security Context to - inquire about. + context (~gssapi.raw.sec_contexts.SecurityContext): the Security + Context to query + desired_aspect (~gssapi.OID): the desired aspect of the Security + Context to inquire about. Returns: list: A list of zero or more pieces of data (as bytes objects) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_set_t *data_set_ptr = NULL @@ -150,18 +151,18 @@ def set_sec_context_option(OID desired_aspect not None, sender handle. Args: - desired_aspect (OID): the desired aspect of the Security Context to set - the value for. - context (SecurityContext): the Security Context to set, or None to - create a new context. + desired_aspect (~gssapi.OID): the desired aspect of the Security + Context to set the value for. + context (~gssapi.raw.sec_contexts.SecurityContext): the Security + Context to set, or None to create a new context. value (bytes): the value to set on the desired aspect of the Security Context or None to send GSS_C_EMPTY_BUFFER. Returns: - SecurityContext: The output security context. + ~gssapi.raw.sec_contexts.SecurityContext: The output security context. Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc value_buffer diff --git a/gssapi/raw/ext_iov_mic.pyx b/gssapi/raw/ext_iov_mic.pyx index d18576f5..8d31ff5c 100644 --- a/gssapi/raw/ext_iov_mic.pyx +++ b/gssapi/raw/ext_iov_mic.pyx @@ -45,13 +45,17 @@ def get_mic_iov(SecurityContext context not None, IOV message not None, This modifies the input :class:`IOV`. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): the :class:`IOV` containing the message qop (int): the desired Quality of Protection (or None for the default QoP) + Returns: + None + Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_qop_t qop_req = qop if qop is not None else GSS_C_QOP_DEFAULT @@ -84,13 +88,17 @@ def get_mic_iov_length(SecurityContext context not None, IOV message not None, This modifies the input :class:`IOV`. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): the :class:`IOV` containing the message qop (int): the desired Quality of Protection (or None for the default QoP) + Returns: + None + Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_qop_t qop_req = qop if qop is not None else GSS_C_QOP_DEFAULT @@ -121,14 +129,15 @@ def verify_mic_iov(SecurityContext context not None, IOV message not None, in the given IOV method. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (IOV): the :class:`IOV` containing the message Returns: int: the QoP used to generate the MIC token Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_iov_buffer_desc *res_arr = message.__cvalue__() diff --git a/gssapi/raw/ext_password.pyx b/gssapi/raw/ext_password.pyx index 93f9c757..4f1ed81e 100644 --- a/gssapi/raw/ext_password.pyx +++ b/gssapi/raw/ext_password.pyx @@ -40,12 +40,12 @@ usage="initiate") In general, it functions similarly to :func:`acquire_cred`. Args: - name (Name): the name to acquire credentials for + name (~gssapi.raw.names.Name): the name to acquire credentials for password (bytes): the password used to acquire credentialss with lifetime (int): the lifetime for the credentials (or None for indefinite) - mechs ([MechType]): the desired mechanisms for which the credentials - should work (or None for the default set) + mechs (~gssapi.MechType): the desired mechanisms for which the + credentials should work (or None for the default set) usage (str): usage type for credentials. Possible values: 'initiate' (default), 'accept', 'both' (failsafe). @@ -55,7 +55,7 @@ usage="initiate") indefinite or not supported) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc password_buffer = gss_buffer_desc(len(password), diff --git a/gssapi/raw/ext_password_add.pyx b/gssapi/raw/ext_password_add.pyx index c020063f..5a142e76 100644 --- a/gssapi/raw/ext_password_add.pyx +++ b/gssapi/raw/ext_password_add.pyx @@ -48,8 +48,8 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) Args: input_cred (Creds): the credentials to add to - name (Name): the name to acquire credentials for - mech (MechType): the desired mechanism. Note that this is both + name (~gssapi.raw.names.Name): the name to acquire credentials for + mech (~gssapi.MechType): the desired mechanism. Note that this is both singular and required password (bytes): the password used to acquire credentialss with usage (str): the usage type for the credentials: may be @@ -67,7 +67,7 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) may be None for indefinite or not supported) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc password_buffer = gss_buffer_desc(len(password), diff --git a/gssapi/raw/ext_rfc4178.pyx b/gssapi/raw/ext_rfc4178.pyx index 056608f7..407d1f3d 100644 --- a/gssapi/raw/ext_rfc4178.pyx +++ b/gssapi/raw/ext_rfc4178.pyx @@ -24,11 +24,13 @@ def set_neg_mechs(Creds cred_handle not None, mech_set not None): Args: cred_handle (Creds): credentials to set negotiable mechanisms for - mech_set ([MechType]): negotiable mechanisms to be set + mech_set (~gssapi.MechType): negotiable mechanisms to be set + Returns: None + Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID_set negotiable_mechs = c_get_mech_oid_set(mech_set) diff --git a/gssapi/raw/ext_rfc5587.pyx b/gssapi/raw/ext_rfc5587.pyx index a061690c..ca669023 100644 --- a/gssapi/raw/ext_rfc5587.pyx +++ b/gssapi/raw/ext_rfc5587.pyx @@ -33,23 +33,23 @@ cdef extern from "python_gssapi_ext.h": def indicate_mechs_by_attrs(desired_mech_attrs=None, except_mech_attrs=None, critical_mech_attrs=None): """ - indicate_mechs_by_attrs(desired_mech_attrs=None, except_mech_attrs=None, - critical_mech_attrs=None) + indicate_mechs_by_attrs(desired_mech_attrs=None, except_mech_attrs=None,\ + critical_mech_attrs=None) Get a set of mechanisms that have the specified attributes. Args: - desired_mech_attrs ([OID]): Attributes that the output mechs MUST + desired_mech_attrs (~gssapi.OID): Attributes that the output mechs MUST offer - except_mech_attrs ([OID]): Attributes that the output mechs MUST NOT - offer - critical_mech_attrs ([OID]): Attributes that the output mechs MUST - understand and offer + except_mech_attrs (~gssapi.OID): Attributes that the output mechs MUST + NOT offer + critical_mech_attrs (~gssapi.OID): Attributes that the output mechs + MUST understand and offer Returns: - [MechType]: a set of mechs which satisfy the given criteria + ~gssapi.MechType: a set of mechs which satisfy the given criteria Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef OM_uint32 maj_stat, min_stat cdef gss_OID_set desired_attrs = GSS_C_NO_OID_SET @@ -83,14 +83,14 @@ def inquire_attrs_for_mech(OID mech): Gets the set of attrs supported and known by a mechanism. Args: - mech (MechType): Mechanism to inquire about + mech (~gssapi.MechType): Mechanism to inquire about Returns: InquireAttrsResult: the results of inquiry; a mech's attributes and - known attributes + known attributes Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef OM_uint32 maj_stat, min_stat cdef gss_OID m = GSS_C_NO_OID @@ -117,14 +117,15 @@ def display_mech_attr(OID attr): Returns information about attributes in human readable form. Args: - attr (OID): Mechanism attribute to retrive names and descriptions of + attr (~gssapi.OID): Mechanism attribute to retrive names and + descriptions of Returns: DisplayAttrResult: the results of displaying the attribute; mech name, - short description, and long description. + short description, and long description. Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef OM_uint32 maj_stat, min_stat cdef gss_OID a = GSS_C_NO_OID diff --git a/gssapi/raw/ext_rfc5588.pyx b/gssapi/raw/ext_rfc5588.pyx index 6244573b..dbf1fcd0 100644 --- a/gssapi/raw/ext_rfc5588.pyx +++ b/gssapi/raw/ext_rfc5588.pyx @@ -36,7 +36,8 @@ set_default=False) creds (Creds): the credentials to store usage (str): the usage to store the credentials with -- either 'both', 'initiate', or 'accept' - mech (OID): the mechansim to associate with the stored credentials + mech (~gssapi.OID): the mechansim to associate with the stored + credentials overwrite (bool): whether or not to overwrite existing credentials stored with the same name, etc set_default (bool): whether or not to set these credentials as @@ -46,11 +47,11 @@ set_default=False) StoreCredResult: the results of the credential storing operation Raises: - GSSError - ExpiredCredentialsError - MissingCredentialsError - OperationUnavailableError - DuplicateCredentialsElementError + ~gssapi.exceptions.GSSError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.OperationUnavailableError + ~gssapi.exceptions.DuplicateCredentialsElementError """ cdef gss_OID desired_mech if mech is not None: diff --git a/gssapi/raw/ext_rfc5801.pyx b/gssapi/raw/ext_rfc5801.pyx index 772c8f55..89da2ae1 100644 --- a/gssapi/raw/ext_rfc5801.pyx +++ b/gssapi/raw/ext_rfc5801.pyx @@ -28,14 +28,14 @@ def inquire_saslname_for_mech(OID mech not None): the mech name, and the mech description. Args: - mech (OID): Mechanism to inquire about + mech (~gssapi.OID): Mechanism to inquire about Returns: InquireSASLNameResult: the results of inquiry; a mech's SASL name, - name, and description. + name, and description. Raises: - GSSError: an unknown failure occurred + ~gssapi.exceptions.GSSError: an unknown failure occurred """ cdef OM_uint32 maj_stat, min_stat cdef gss_buffer_desc sasl_mech_name @@ -72,10 +72,10 @@ def inquire_mech_for_saslname(bytes sasl_name not None): sasl_name (bytes): SASL name of the mechanism Returns: - OID: the mechanism with corresponding SASL name. + ~gssapi.OID: the mechanism with corresponding SASL name. Raises: - GSSError: An unknown failure occurred + ~gssapi.exceptions.GSSError: An unknown failure occurred """ cdef OM_uint32 maj_stat, min_stat cdef gss_buffer_desc sn diff --git a/gssapi/raw/ext_rfc6680.pyx b/gssapi/raw/ext_rfc6680.pyx index bfd52319..94f52708 100644 --- a/gssapi/raw/ext_rfc6680.pyx +++ b/gssapi/raw/ext_rfc6680.pyx @@ -46,16 +46,16 @@ def display_name_ext(Name name not None, OID name_type not None): will be raised. Args: - name (Name): the name to display - name_type (OID): the name type (see NameType) to use to + name (~gssapi.raw.names.Name): the name to display + name_type (~gssapi.OID): the name type (see NameType) to use to display the given name Returns: bytes: the displayed name Raises: - OperationUnavailableError: the given name could not be displayed - using the given name type + ~gssapi.exceptions.OperationUnavailableError: the given name could not + be displayed using the given name type """ # GSS_C_EMPTY_BUFFER @@ -85,7 +85,7 @@ def inquire_name(Name name not None, mech_name=True, attrs=True): a mechanism name, the associated mechansim is returned as well. Args: - name (Name): the name about which to inquire + name (~gssapi.raw.names.Name): the name about which to inquire mech_name (bool): whether or not to retrieve if this name is a mech_name (and the associate mechanism) attrs (bool): whether or not to retrieve the attribute name list @@ -96,7 +96,7 @@ def inquire_name(Name name not None, mech_name=True, attrs=True): the associated mechanism if it is a Mechanism Name Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef int *name_is_mn_ptr = NULL @@ -156,15 +156,15 @@ def set_name_attribute(Name name not None, attr not None, value not None, used in between calls to "clear" the values. Args: - name (Name): the Name on which to set the attribute + name (~gssapi.raw.names.Name): the Name on which to set the attribute attr (bytes): the name of the attribute value (list): a list of bytes objects to use as the value(s) complete (bool): whether or not to mark this attribute's value set as being "complete" Raises: - OperationUnavailableError: the given attribute name is unknown - or could not be set + ~gssapi.exceptions.OperationUnavailableError: the given attribute name + is unknown or could not be set """ cdef gss_buffer_desc attr_buff = gss_buffer_desc(len(attr), attr) @@ -201,18 +201,18 @@ def get_name_attribute(Name name not None, attr not None, more=None): multiple calls to retrieve multiple values). Args: - name (Name): the Name from which to get the attribute + name (~gssapi.raw.names.Name): the Name from which to get the attribute attr (bytes): the name of the attribute Returns: GetNameAttributeResult: the raw version of the value(s), - the human-readable version of the value(s), whether - or not the attribute was authenticated, and whether or - not the attribute's value set was marked as complete + the human-readable version of the value(s), whether + or not the attribute was authenticated, and whether or + not the attribute's value set was marked as complete Raises: - OperationUnavailableError: the given attribute is unknown - or unset + ~gssapi.exceptions.OperationUnavailableError: the given attribute is + unknown or unset """ cdef gss_buffer_desc attr_buff = gss_buffer_desc(len(attr), attr) @@ -261,12 +261,12 @@ def delete_name_attribute(Name name not None, attr not None): Note that the removal of certain attributes may not be allowed. Args: - name (Name): the name to remove the attribute from + name (~gssapi.raw.names.Name): the name to remove the attribute from attr (bytes): the name of the attribute Raises: - OperationUnavailableError - UnauthorizedError + ~gssapi.exceptions.OperationUnavailableError + ~gssapi.exceptions.UnauthorizedError """ cdef gss_buffer_desc attr_buff = gss_buffer_desc(len(attr), attr) @@ -296,13 +296,13 @@ def export_name_composite(Name name not None): using the normal export name type. Args: - name (Name): the name to export + name (~gssapi.raw.names.Name): the name to export Returns: bytes: the exported composite name Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc res = gss_buffer_desc(0, NULL) diff --git a/gssapi/raw/ext_s4u.pyx b/gssapi/raw/ext_s4u.pyx index d91986e4..177b02e3 100644 --- a/gssapi/raw/ext_s4u.pyx +++ b/gssapi/raw/ext_s4u.pyx @@ -53,11 +53,11 @@ mechs=None, usage='initiate') Args: impersonator_cred (Cred): the credentials with permissions to impersonate the target name - name (Name): the name to impersonate + name (~gssapi.raw.names.Name): the name to impersonate lifetime (int): the lifetime for the credentials (or None for indefinite) - mechs ([MechType]): the desired mechanisms for which the credentials - should work (or None for the default set) + mechs (~gssapi.MechType): the desired mechanisms for which the + credentials should work (or None for the default set) usage (str): the usage type for the credentials: may be 'initiate', 'accept', or 'both' @@ -67,7 +67,7 @@ mechs=None, usage='initiate') indefinite or not support) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID_set desired_mechs @@ -135,8 +135,8 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) credentials impersonator_cred (Cred): the credentials with permissions to impersonate the target name - name (Name): the name to impersonate - mech (MechType): the desired mechanism. Note that this is both + name (~gssapi.raw.names.Name): the name to impersonate + mech (~gssapi.MechType): the desired mechanism. Note that this is both singular and required, unlike acquireCredImpersonateName usage (str): the usage type for the credentials: may be 'initiate', 'accept', or 'both' @@ -153,7 +153,7 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) may be None for indefinite or not supported) Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef OM_uint32 input_initiator_ttl = c_py_ttl_to_c(init_lifetime) diff --git a/gssapi/raw/ext_set_cred_opt.pyx b/gssapi/raw/ext_set_cred_opt.pyx index a72f7487..506dd12c 100644 --- a/gssapi/raw/ext_set_cred_opt.pyx +++ b/gssapi/raw/ext_set_cred_opt.pyx @@ -42,7 +42,8 @@ def set_cred_option(OID desired_aspect not None, Creds creds=None, value=None): credentials. Args: - desired_aspect (OID): the desired aspect of the Credential to set. + desired_aspect (~gssapi.OID): the desired aspect of the Credential to + set. cred_handle (Creds): the Credentials to set, or None to create a new credential. value (bytes): the value to set on the desired aspect of the Credential @@ -52,7 +53,7 @@ def set_cred_option(OID desired_aspect not None, Creds creds=None, value=None): Creds: The output credential. Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_buffer_desc value_buffer diff --git a/gssapi/raw/message.pyx b/gssapi/raw/message.pyx index d45e430c..314ebf4d 100644 --- a/gssapi/raw/message.pyx +++ b/gssapi/raw/message.pyx @@ -54,7 +54,8 @@ def get_mic(SecurityContext context not None, message, qop=None): together. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the message for which to generate the MIC qop (int): the requested Quality of Protection (or None to use the default) @@ -63,9 +64,9 @@ def get_mic(SecurityContext context not None, message, qop=None): bytes: the generated MIC token Raises: - ExpiredContextError - MissingContextError - BadQoPError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadQoPError """ cdef gss_buffer_desc message_buffer = gss_buffer_desc(len(message), @@ -99,7 +100,8 @@ def verify_mic(SecurityContext context not None, message, token): be raised. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the message in question token (bytes): the MIC token in question @@ -107,14 +109,14 @@ def verify_mic(SecurityContext context not None, message, token): int: the QoP used. Raises: - InvalidTokenError - BadMICError - DuplicateTokenError - ExpiredTokenError - TokenTooLateError - TokenTooEarlyError - ExpiredContextError - MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.TokenTooLateError + ~gssapi.exceptions.TokenTooEarlyError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ cdef gss_buffer_desc message_buffer = gss_buffer_desc(len(message), @@ -145,7 +147,8 @@ def wrap_size_limit(SecurityContext context not None, OM_uint32 output_size, the given maximum wrapped/encrypted message size. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context output_size (int): the maximum desired wrapped/encrypted message size confidential (bool): whether or not confidentiality is being used qop (int): the QoP that will be when you actually call wrap @@ -155,9 +158,9 @@ def wrap_size_limit(SecurityContext context not None, OM_uint32 output_size, int: the maximum unencrypted/unwrapped message size Raises: - MissingContextError - ExpiredContextError - BadQoPError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.BadQoPError """ cdef int conf_req = confidential @@ -187,7 +190,8 @@ def wrap(SecurityContext context not None, message, confidential=True, of confidential) with the given Quality of Protection. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the message to wrap or encrypt confidential (bool): whether or not to encrypt the message (True), or just wrap it with a MIC (False) @@ -199,9 +203,9 @@ def wrap(SecurityContext context not None, message, confidential=True, encryption was actually used Raises: - ExpiredContextError - MissingContextError - BadQoPError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadQoPError """ cdef int conf_req = confidential @@ -236,7 +240,8 @@ def unwrap(SecurityContext context not None, message): on whether the sender used confidentiality. Args: - context (SecurityContext): the current security context + context (~gssapi.raw.sec_contexts.SecurityContext): the current + security context message (bytes): the message to unwrap/decrypt Returns: @@ -244,14 +249,14 @@ def unwrap(SecurityContext context not None, message): encryption was used, and the QoP used Raises: - InvalidTokenError - BadMICError - DuplicateTokenError - ExpiredTokenError - TokenTooLateError - TokenTooEarlyError - ExpiredContextError - MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.TokenTooLateError + ~gssapi.exceptions.TokenTooEarlyError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ cdef gss_buffer_desc input_buffer = gss_buffer_desc(len(message), message) diff --git a/gssapi/raw/misc.pyx b/gssapi/raw/misc.pyx index 7f9d9203..c16a0431 100644 --- a/gssapi/raw/misc.pyx +++ b/gssapi/raw/misc.pyx @@ -60,13 +60,13 @@ def inquire_names_for_mech(OID mech not None): the given mechanism. Args: - mech (OID): the mechanism in question + mech (~gssapi.OID): the mechanism in question Returns: list: the name type OIDs supported by the given mechanism Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID_set name_types @@ -91,13 +91,13 @@ def inquire_mechs_for_name(Name name not None): process the given name. Args: - name (Name): the name in question + name (~gssapi.raw.names.Name): the name in question Returns: list: the mechanism OIDs able to process the given name Raises: - GSSError + ~gssapi.exceptions.GSSError """ cdef gss_OID_set mech_types @@ -129,8 +129,8 @@ def _display_status(unsigned int error_code, bint is_major_code, error_code (int): The error code in question is_major_code (bool): is this a major code (True) or a minor code (False) - mech (MechType): The mechanism type that returned this error code - (defaults to None, for the default mechanism) + mech (~gssapi.MechType): The mechanism type that returned this error + code (defaults to None, for the default mechanism) message_context (int): The context for this call -- this is used when multiple messages are available (defaults to 0) diff --git a/gssapi/raw/names.pyx b/gssapi/raw/names.pyx index cfeaef77..a6521dce 100644 --- a/gssapi/raw/names.pyx +++ b/gssapi/raw/names.pyx @@ -75,15 +75,15 @@ def import_name(name not None, OID name_type=None): Args: name (bytes): the string version of the name - name_type (NameType): the type of this name + name_type (~gssapi.NameType): the type of this name Returns: Name: the GSSAPI version of the name Raises: - BadNameTypeError - BadNameError - BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.BadMechanismError """ cdef gss_OID nt @@ -124,14 +124,14 @@ def display_name(Name name not None, name_type=True): returned name type will be ``None``). Args: - name (Name): the name in question + name (~gssapi.raw.names.Name): the name in question name_type (bool): whether or not to retrieve the name type Returns: DisplayNameResult: the text part of the name and its type Raises: - BadNameError + ~gssapi.exceptions.BadNameError """ # GSS_C_EMPTY_BUFFER @@ -177,15 +177,15 @@ def compare_name(Name name1=None, Name name2=None): see if they are equivalent. Args: - name1 (Name): the first name to compare - name2 (Name): the second name to compare + name1 (~gssapi.raw.names.Name): the first name to compare + name2 (~gssapi.raw.names.Name): the second name to compare Returns: bool: whether or not the names are equal Raises: - BadNameTypeError - BadNameError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError """ # check for either value being None @@ -219,15 +219,15 @@ def export_name(Name name not None): by :func:`canonicalize_name` or :func:`accept_sec_context`. Args: - name (Name): the name to export + name (~gssapi.raw.names.Name): the name to export Returns: bytes: the exported name Raises: - MechanismNameRequiredError - BadNameTypeError - BadNameError + ~gssapi.exceptions.MechanismNameRequiredError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError """ # GSS_C_EMPTY_BUFFER @@ -256,17 +256,17 @@ def canonicalize_name(Name name not None, OID mech not None): a full form name specific to a mechanism. Args: - name (Name): the name to canonicalize - mech (MechType): the mechanism type to use to + name (~gssapi.raw.names.Name): the name to canonicalize + mech (~gssapi.MechType): the mechanism type to use to canonicalize the name Returns: Name: a canonicalized version of the input name Raises: - BadMechanismError - BadNameTypeError - BadNameError + ~gssapi.exceptions.BadMechanismError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError """ cdef gss_name_t canonicalized_name @@ -292,13 +292,13 @@ def duplicate_name(Name name not None): Duplicate a GSSAPI name. Args: - name (Name): the name to duplicate + name (~gssapi.raw.names.Name): the name to duplicate Returns: Name: a duplicate of the input name Raises: - BadNameError + ~gssapi.exceptions.BadNameError """ cdef gss_name_t new_name @@ -328,10 +328,10 @@ def release_name(Name name not None): automatically freed by Python. Args: - name (Name): the name in question + name (~gssapi.raw.names.Name): the name in question Raises: - BadNameError + ~gssapi.exceptions.BadNameError """ cdef OM_uint32 maj_stat, min_stat diff --git a/gssapi/raw/sec_contexts.pyx b/gssapi/raw/sec_contexts.pyx index c18da3fa..5ed9b3c2 100644 --- a/gssapi/raw/sec_contexts.pyx +++ b/gssapi/raw/sec_contexts.pyx @@ -129,12 +129,13 @@ flags=None, lifetime=None, channel_bindings=None, input_token=None) This changes the input context! Args: - target_name (Name): the target for the security context + target_name (~gssapi.raw.names.Name): the target for the security + context creds (Creds): the credentials to use to initiate the context, or None to use the default credentials - context (SecurityContext): the security context to update, or - None to create a new context - mech (MechType): the mechanism type for this security context, + context (~gssapi.raw.sec_contexts.SecurityContext): the security + context to update, or None to create a new context + mech (~gssapi.MechType): the mechanism type for this security context, or None for the default mechanism type flags (list): the flags to request for the security context, or None to use the default set: mutual_authentication and @@ -155,18 +156,18 @@ flags=None, lifetime=None, channel_bindings=None, input_token=None) initiation. Raises: - InvalidTokenError - InvalidCredentialsError - MissingCredentialsError - ExpiredCredentialsError - BadChannelBindingsError - BadMICError - ExpiredTokenError - DuplicateTokenError - MissingContextError - BadNameTypeError - BadNameError - BadMechanismError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.InvalidCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.BadChannelBindingsError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadNameTypeError + ~gssapi.exceptions.BadNameError + ~gssapi.exceptions.BadMechanismError """ cdef gss_OID mech_oid @@ -265,8 +266,8 @@ channel_bindings=None) input_token (bytes): the token sent by the context initiator acceptor_creds (Creds): the credentials to be used to accept the context (or None to use the default credentials) - context (SecurityContext): the security context to update - (or None to create a new security context object) + context (~gssapi.raw.sec_contexts.SecurityContext): the security + context to update (or None to create a new security context object) channel_bindings (ChannelBindings): The channel bindings (or None for no channel bindings) @@ -279,16 +280,16 @@ channel_bindings=None) exchanges are needed to finalize the security context. Raises: - InvalidTokenError - InvalidCredentialsError - MissingCredentialsError - ExpiredCredentialsError - BadChannelBindingsError - MissingContextError - BadMICError - ExpiredTokenError - DuplicateTokenError - BadMechanismError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.InvalidCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.BadChannelBindingsError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.BadMechanismError """ cdef gss_channel_bindings_t bdng @@ -386,7 +387,8 @@ lifetime=True, mech=True, flags=True, locally_init=True, complete=True) the target name may be ``None`` if it would have been ``GSS_C_NO_NAME`` Args: - context (SecurityContext): the context in question + context (~gssapi.raw.sec_contexts.SecurityContext): the context in + question Returns: InquireContextResult: the initiator name, the target name, the TTL @@ -395,7 +397,7 @@ lifetime=True, mech=True, flags=True, locally_init=True, complete=True) and whether or not the context is currently fully established Raises: - MissingContextError + ~gssapi.exceptions.MissingContextError """ cdef gss_name_t output_init_name @@ -498,14 +500,15 @@ def context_time(SecurityContext context not None): give a result of 0. Args: - context (SecurityContext): the security context in question + context (~gssapi.raw.sec_contexts.SecurityContext): the security + context in question Returns: int: the number of seconds for which the context will be valid Raises: - ExpiredContextError - MissingContextError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ cdef OM_uint32 ttl @@ -536,13 +539,13 @@ def process_context_token(SecurityContext context not None, token): This method has been essentially deprecated by :rfc:`2744`. Args: - context (SecurityContext): the security context against which - to process the token + context (~gssapi.raw.sec_contexts.SecurityContext): the security + context against which to process the token token (bytes): the token to process Raises: - InvalidTokenError - MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.MissingContextError """ cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token) @@ -567,10 +570,10 @@ def import_sec_context(token not None): :func:`export_sec_context`. Raises: - MissingContextError - InvalidTokenError - OperationUnavailableError - UnauthorizedError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.OperationUnavailableError + ~gssapi.exceptions.UnauthorizedError """ cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token) @@ -602,15 +605,16 @@ def export_sec_context(SecurityContext context not None): Warning: this modifies the input context Args: - context (SecurityContext): the context to send to another process + context (~gssapi.raw.sec_contexts.SecurityContext): the context to send + to another process Returns: bytes: the output token to be imported Raises: - ExpiredContextError - MissingContextError - OperationUnavailableError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.OperationUnavailableError """ cdef gss_buffer_desc output_token = gss_buffer_desc(0, NULL) @@ -644,7 +648,8 @@ def delete_sec_context(SecurityContext context not None, local_only=True): objects will automatically be freed by Python. Args: - context (SecurityContext): the security context in question + context (~gssapi.raw.sec_contexts.SecurityContext): the security + context in question local_only (bool): should we request local deletion (True), or also remote deletion (False), in which case a token is also returned @@ -653,7 +658,7 @@ def delete_sec_context(SecurityContext context not None, local_only=True): this is None, but bytes for compatibility. Raises: - MissingContextError + ~gssapi.exceptions.MissingContextError """ cdef OM_uint32 maj_stat, min_stat diff --git a/gssapi/sec_contexts.py b/gssapi/sec_contexts.py index a1893d98..356b939a 100644 --- a/gssapi/sec_contexts.py +++ b/gssapi/sec_contexts.py @@ -146,9 +146,9 @@ def get_signature(self, message): bytes: the message signature Raises: - ExpiredContextError - MissingContextError - BadQoPError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadQoPError """ # TODO(directxman12): check flags? @@ -168,14 +168,14 @@ def verify_signature(self, message, mic): mic (bytes): the signature to verify Raises: - BadMICError: the signature was not valid - InvalidTokenError - DuplicateTokenError - ExpiredTokenError - TokenTooLateError - TokenTooEarlyError - ExpiredContextError - MissingContextError + ~gssapi.exceptions.BadMICError: the signature was not valid + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.TokenTooLateError + ~gssapi.exceptions.TokenTooEarlyError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ return rmessage.verify_mic(self, message, mic) @@ -195,9 +195,9 @@ def wrap(self, message, encrypt): (e.g. whether encryption was used succesfully) Raises: - ExpiredContextError - MissingContextError - BadQoPError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadQoPError """ return rmessage.wrap(self, message, encrypt) @@ -216,14 +216,14 @@ def unwrap(self, message): (e.g. wheter encryption was used) Raises: - InvalidTokenError - BadMICError - DuplicateTokenError - ExpiredTokenError - TokenTooLateError - TokenTooEarlyError - ExpiredContextError - MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.TokenTooLateError + ~gssapi.exceptions.TokenTooEarlyError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ return rmessage.unwrap(self, message) @@ -244,10 +244,11 @@ def encrypt(self, message): bytes: the encrypted message Raises: - EncryptionNotUsed: the encryption could not be used - ExpiredContextError - MissingContextError - BadQoPError + ~gssapi.exceptions.EncryptionNotUsed: the encryption could not be + used + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadQoPError """ res = self.wrap(message, encrypt=True) @@ -273,15 +274,16 @@ def decrypt(self, message): bytes: the decrypted message Raises: - EncryptionNotUsed: encryption was expected, but not used - InvalidTokenError - BadMICError - DuplicateTokenError - ExpiredTokenError - TokenTooLateError - TokenTooEarlyError - ExpiredContextError - MissingContextError + ~gssapi.exceptions.EncryptionNotUsed: encryption was expected, but + not used + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.ExpiredTokenError + ~gssapi.exceptions.TokenTooLateError + ~gssapi.exceptions.TokenTooEarlyError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError """ res = self.unwrap(message) @@ -311,9 +313,9 @@ def get_wrap_size_limit(self, desired_output_size, int: the maximum input message size Raises: - MissingContextError - ExpiredContextError - BadQoPError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.BadQoPError """ return rmessage.wrap_size_limit(self, desired_output_size, @@ -332,8 +334,8 @@ def process_token(self, token): token (bytes): the token to process Raises: - InvalidTokenError - MissingContextError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.MissingContextError """ rsec_contexts.process_context_token(self, token) @@ -348,9 +350,9 @@ def export(self): bytes: the exported security context Raises: - ExpiredContextError - MissingContextError - OperationUnavailableError + ~gssapi.exceptions.ExpiredContextError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.OperationUnavailableError """ return rsec_contexts.export_sec_context(self) @@ -383,7 +385,7 @@ def _inquire(self, **kwargs): fields set to None Raises: - MissingContextError + ~gssapi.exceptions.MissingContextError """ if not kwargs: default_val = True @@ -499,18 +501,18 @@ def step(self, token=None): bytes: the output token to send to the other participant Raises: - InvalidTokenError - InvalidCredentialsError - MissingCredentialsError - ExpiredCredentialsError - BadChannelBindingsError - BadMICError - ExpiredTokenError: (initiate only) - DuplicateTokenError - MissingContextError - BadNameTypeError: (initiate only) - BadNameError: (initiate only) - BadMechanismError + ~gssapi.exceptions.InvalidTokenError + ~gssapi.exceptions.InvalidCredentialsError + ~gssapi.exceptions.MissingCredentialsError + ~gssapi.exceptions.ExpiredCredentialsError + ~gssapi.exceptions.BadChannelBindingsError + ~gssapi.exceptions.BadMICError + ~gssapi.exceptions.ExpiredTokenError: (initiate only) + ~gssapi.exceptions.DuplicateTokenError + ~gssapi.exceptions.MissingContextError + ~gssapi.exceptions.BadNameTypeError: (initiate only) + ~gssapi.exceptions.BadNameError: (initiate only) + ~gssapi.exceptions.BadMechanismError """ if self.usage == 'accept': diff --git a/setup.cfg b/setup.cfg index d799dbc2..9d312837 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,6 +2,7 @@ source-dir=docs/source build-dir=docs/build all_files=1 +warning-is-error=1 [upload_sphinx] upload-dir = docs/build/html