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..69078d20 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,20 @@ Acquiring Credentials With a Password Extensions :members: :undoc-members: +Other Extensions +~~~~~~~~~~~~~~~~ + +.. automodule:: gssapi.raw.ext_set_cred_opt + :members: + :undoc-members: + +Results +------- + +.. automodule:: gssapi.raw.named_tuples + :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/named_tuples.py b/gssapi/raw/named_tuples.py index 3ce494ea..3a0e798b 100644 --- a/gssapi/raw/named_tuples.py +++ b/gssapi/raw/named_tuples.py @@ -1,76 +1,138 @@ -from collections import namedtuple +from typing import Iterable, List, NamedTuple, Optional, Set, TYPE_CHECKING +if TYPE_CHECKING: + from gssapi.raw.creds import Creds + from gssapi.raw.names import Name + from gssapi.raw.oids import OID + from gssapi.raw.sec_contexts import SecurityContext + from gssapi.raw.types import RequirementFlag -AcquireCredResult = namedtuple('AcquireCredResult', - ['creds', 'mechs', 'lifetime']) +class AcquireCredResult(NamedTuple): + """Credential result when acquiring a GSSAPI credential.""" + creds: "Creds" #: GSSAPI credentials that were acquired + mechs: Set["OID"] #: Set of mechs the cred is for + lifetime: int #: Number of seconds for which the cred will remain valid -InquireCredResult = namedtuple('InquireCredResult', - ['name', 'lifetime', 'usage', - 'mechs']) +class InquireCredResult(NamedTuple): + """Information about the credential.""" + name: Optional["Name"] #: The principal associated with the credential + lifetime: Optional[int] #: Number of seconds which the cred is valid for + usage: Optional[str] #: How the credential can be used + mechs: Optional[Set["OID"]] #: Set of mechs the cred is for -InquireCredByMechResult = namedtuple('InquireCredByMechResult', - ['name', 'init_lifetime', - 'accept_lifetime', 'usage']) +class InquireCredByMechResult(NamedTuple): + """Information about the credential for a specific mechanism.""" + name: Optional["Name"] #: The principal associated with the credential + init_lifetime: Optional[int] #: Time valid for initiation + accept_lifetime: Optional[int] #: Time valid for accepting + usage: Optional[str] #: How the credential can be used -AddCredResult = namedtuple('AddCredResult', - ['creds', 'mechs', 'init_lifetime', - 'accept_lifetime']) +class AddCredResult(NamedTuple): + """Result of adding to a GSSAPI credential.""" + creds: Optional["Creds"] #: The credential that was generated + mechs: Set["OID"] #: Set of mechs the cred is for + init_lifetime: int #: Time valid for initiation + accept_lifetime: int #: Time valid for accepting -DisplayNameResult = namedtuple('DisplayNameResult', - ['name', 'name_type']) +class DisplayNameResult(NamedTuple): + """Textual representation of a GSSAPI name.""" + name: bytes #: The representation of the GSSAPI name + name_type: Optional["OID"] #: The type of GSSAPI name -WrapResult = namedtuple('WrapResult', - ['message', 'encrypted']) +class WrapResult(NamedTuple): + """Wrapped message result.""" + message: bytes #: The wrapped message + encrypted: bool #: Whether the message is encrypted and not just signed -UnwrapResult = namedtuple('UnwrapResult', - ['message', 'encrypted', 'qop']) +class UnwrapResult(NamedTuple): + """Unwrapped message result.""" + message: bytes #: The unwrapped message + encrypted: bool #: Whether the message was encrypted and not just signed + qop: int #: The quality of protection applied to the message -AcceptSecContextResult = namedtuple('AcceptSecContextResult', - ['context', 'initiator_name', - 'mech', 'token', 'flags', 'lifetime', - 'delegated_creds', 'more_steps']) +class AcceptSecContextResult(NamedTuple): + """Result when accepting a security context by an initiator.""" + context: "SecurityContext" #: The acceptor security context + initiator_name: "Name" #: The authenticated name of the initiator + mech: "OID" #: Mechanism with which the context was established + token: Optional[bytes] #: Token to be returned to the initiator + flags: "RequirementFlag" #: Services requested by the initiator + lifetime: int #: Seconds for which the context is valid for + delegated_creds: Optional["Creds"] #: Delegated credentials + more_steps: bool #: More input is required to complete the exchange -InitSecContextResult = namedtuple('InitSecContextResult', - ['context', 'mech', 'flags', 'token', - 'lifetime', 'more_steps']) +class InitSecContextResult(NamedTuple): + """Result when initiating a security context""" + context: "SecurityContext" #: The initiator security context + mech: "OID" #: Mechanism used in the security context + flags: "RequirementFlag" #: Services available for the context + token: Optional[bytes] #: Token to be sent to the acceptor + lifetime: int #: Seconds for which the context is valid for + more_steps: bool #: More input is required to complete the exchange -InquireContextResult = namedtuple('InquireContextResult', - ['initiator_name', 'target_name', - 'lifetime', 'mech', 'flags', - 'locally_init', 'complete']) +class InquireContextResult(NamedTuple): + """Information about the security context.""" + initiator_name: Optional["Name"] #: Name of the initiator + target_name: Optional["Name"] #: Name of the acceptor + lifetime: Optional[int] #: Time valid for the security context + mech: Optional["OID"] #: Mech used to create the security context + flags: Optional["RequirementFlag"] #: Services available for the context + locally_init: Optional[bool] #: Context was initiated locally + complete: Optional[bool] #: Context has been established and ready to use -StoreCredResult = namedtuple('StoreCredResult', - ['mechs', 'usage']) +class StoreCredResult(NamedTuple): + """Result of the credential storing operation.""" + mechs: List["OID"] #: Mechs that were stored in the credential store + usage: str #: How the credential can be used -IOVUnwrapResult = namedtuple('IOVUnwrapResult', - ['encrypted', 'qop']) +class IOVUnwrapResult(NamedTuple): + """Unwrapped IOV message result.""" + encrypted: bool #: Whether the message was encrypted and not just signed + qop: int #: The quality of protection applied to the message -InquireNameResult = namedtuple('InquireNameResult', - ['attrs', 'is_mech_name', 'mech']) +class InquireNameResult(NamedTuple): + """Information about a GSSAPI Name.""" + attrs: List[bytes] #: Set of attribute names + is_mech_name: bool #: Name is a mechanism name + mech: "OID" #: The mechanism if is_name_mech is True -GetNameAttributeResult = namedtuple('GetNamedAttributeResult', - ['values', 'display_values', - 'authenticated', 'complete']) -InquireAttrsResult = namedtuple('InquireAttrsResult', - ['mech_attrs', 'known_mech_attrs']) +class GetNameAttributeResult(NamedTuple): + """GSSAPI Name attribute values.""" + values: Iterable[bytes] #: Raw values + display_values: Iterable[bytes] #: Human-readable values + authenticated: bool #: Attribute has been authenticated + complete: bool #: Attribute value is marked as complete -DisplayAttrResult = namedtuple('DisplayAttrResult', ['name', 'short_desc', - 'long_desc']) -InquireSASLNameResult = namedtuple('InquireSASLNameResult', - ['sasl_mech_name', 'mech_name', - 'mech_description']) +class InquireAttrsResult(NamedTuple): + """Set of attributes supported and known by a mechanism.""" + mech_attrs: Set["OID"] #: The mechanisms attributes + known_mech_attrs: Set["OID"] #: Known attributes of the mechanism + + +class DisplayAttrResult(NamedTuple): + """Information about an attribute.""" + name: bytes #: The mechanism name + short_desc: bytes #: Short description of the mechanism + long_desc: bytes #: Long description of the mechanism + + +class InquireSASLNameResult(NamedTuple): + """SASL informmation about a GSSAPI Name.""" + sasl_mech_name: bytes #: The SASL name + mech_name: bytes #: The mechanism name + mech_description: bytes #: The mechanism description 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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy