API reference

Basic encoding and decoding

pymunge.encode(payload=None)

Create a MUNGE credential using the default context. Optionally, a payload (byte string) can be encapsulated as well.

If successful, returns the credential (a byte string), otherwise raises a MungeError.

pymunge.decode(cred)

Validate a MUNGE credential using the default context.

If successful, returns (payload, uid, gid, ctx), where payload is the payload encapsulated in the credential, uid, gid are the UID/GID of the process that created the credential, and ctx is a MungeContext set to the one used to create the credential.

If unsuccessful, a MungeError is raised. For certain errors (i.e. EMUNGE_CRED_EXPIRED, EMUNGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED), the payload, uid and gid can still be obtained via the result property of the raised MungeError. Note that the context cannot be obtained from the MungeError; if you need it, manually create a MungeContext and use its decode() method.

MUNGE contexts

class pymunge.MungeContext(ctx=None)

A MUNGE context. Encapsulates a collection of options used when creating a credential, or obtained from decoding a credential.

MungeContext() creates a new context with default attributes. As contexts are mutable, the context’s attributes can subsequently be modified by assigning values to them.

If ctx != None, MungeContext(ctx) creates a copy of the context ctx. (For ctx == None, MungeContext(ctx) is equivalent to MungeContext().) Modifying attributes in the copy does not affect the attributes of the original context.

A MungeContext should be closed when it is no longer used. The easiest way to do this is to use the MungeContext as a context manager for a ‘with’ statement, which automatically closes the context when the ‘with’ scope ends, e.g.:

>>> with MungeContext() as ctx:
>>>     do stuff with ctx
>>> # ctx is now closed

Typical MungeContext usage patterns:

• For encoding:

>>> with MungeContext() as ctx:
>>>     (set attributes of ctx, if needed)
>>>     cred = ctx.encode(payload)

• For decoding:

>>> with MungeContext() as ctx:
>>>     payload, uid, gid = ctx.decode(cred)
>>>     (check attributes of ctx, if needed)

close()

Close this context, releasing any resources associated with it. Once a context is closed, it cannot be reopened. It also cannot be used to encode or decode credentials, nor can its attributes (other than closed) be read or set (in each case, a MungeError is raised). Calling close() on an already closed context has no effect.

decode(cred)

Validate a MUNGE credential. The attributes of this context will be set to those used to encode the credential.

If successful, returns (payload, uid, gid), where payload is the payload encapsulated in the credential, and uid, gid are the UID/GID of the process that created the credential. Otherwise a MungeError is raised. For certain errors (i.e. EMUNGE_CRED_EXPIRED, EMUNGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED), the payload, uid and gid can still be obtained via the result property of the raised MungeError.

encode(payload=None)

Create a MUNGE credential using the options defined in this context. Optionally, a payload (byte string) can be encapsulated as well.

If successful, returns the credential (a byte string), otherwise raises a MungeError.

addr4

The IPv4 address of the host where the credential was encoded, in dotted-quad notation (e.g. ‘127.0.0.1’). This property cannot be explicitly set.

cipher_type

Symmetric cipher type (a CipherType).

closed

True if this context is closed, False otherwise. This property cannot be explicitly set, instead use the close() method to close the context.

decode_time

The time (in seconds since the epoch) at which the credential was decoded. This property cannot be explicitly set.

encode_time

The time (in seconds since the epoch) at which the credential was encoded. This property cannot be explicitly set.

gid_restriction

Numeric GID allowed to decode the credential. This value will be matched against the effective group ID of the process requesting the credential decode. Default is the special value GID_ANY, which means no GID restriction is set.

mac_type

Message authentication code type (a MACType).

realm

Security realm (a str). Not currently supported.

socket

Path of the local domain socket for connecting with munged, a str.

ttl

Time-to-live (in seconds). This value controls how long the credential is valid once it has been encoded.

When encoding a credential, two special values can be used:

• TTL_DEFAULT, which specifies the default according to the munged configuration. This is the default value of this property.
• TTL_MAXIMUM, which specifies the maximum allowed by the munged configuration.

uid_restriction

Numeric UID allowed to decode the credential. This value will be matched against the effective user ID of the process requesting the credential decode. Default is the special value UID_ANY, which means no UID restriction is set.

zip_type

Compression type (a ZipType).

Enumerations and constants

class pymunge.CipherType

Bases: enum.Enum

MUNGE symmetric cipher types

AES128 = 4

AES CBC with 128b-block/128b-key

AES256 = 5

AES CBC with 128b-block/256b-key

Blowfish = 2

Blowfish CBC with 64b-block/128b-key

CAST5 = 3

CAST5 CBC with 64b-block/128b-key

Default = 1

default cipher specified by daemon

Disabled = 0

encryption disabled

class pymunge.MACType

Bases: enum.Enum

MUNGE message authentication code types

Default = 1

default MAC specified by daemon

Disabled = 0

MAC disabled – invalid, btw

MD5 = 2

MD5 with 128b-digest

RIPEMD160 = 4

RIPEMD-160 with 160b-digest

SHA1 = 3

SHA-1 with 160b-digest

SHA256 = 5

SHA-256 with 256b-digest

SHA512 = 6

SHA-512 with 512b-digest

class pymunge.ZipType

Bases: enum.Enum

MUNGE compression types

Default = 1

default zip specified by daemon

Disabled = 0

compression disabled

bzlib = 2

bzip2 by Julian Seward

zlib = 3

zlib “deflate” by Gailly & Adler

pymunge.TTL_MAXIMUM

Use the maximum TTL allowed by the daemon.

pymunge.TTL_DEFAULT

Use the default TTL specified by the daemon.

pymunge.UID_ANY

Do not restrict decode to a specific UID.

pymunge.GID_ANY

Do not restrict decode to a specific GID.

Exceptions

class pymunge.MungeError(code, message, result=None)

Bases: Exception

Generic MUNGE exception. Generally raised when an underlying libmunge function returns an error code, or in a few cases when a pymunge wrapper detects an invalid argument.

MungeError instances have the following attributes:

• code: The error code (a MungeErrorCode, which is NOT an integer). To retrieve the raw error code as an integer, use code.value.
• message: The message string from libmunge. This is only the raw message without the exception type or the error code.
• result: Partial result, in most cases None. If a decode fails with one of certain errors (i.e. EMUNGE_CRED_EXPIRED, EMUNGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED), result is a 3-tuple (payload, uid, gid) containing the results that would have been returned by the decode function or method.

class pymunge.MungeErrorCode

Bases: enum.Enum

MUNGE error codes.

EMUNGE_BAD_ARG = 2

Invalid argument

EMUNGE_BAD_CIPHER = 10

Bad credential cipher type

EMUNGE_BAD_CRED = 8

Bad credential format

EMUNGE_BAD_LENGTH = 3

Exceeded maximum message length

EMUNGE_BAD_MAC = 11

Bad credential MAC type

EMUNGE_BAD_REALM = 13

Bad credential security realm

EMUNGE_BAD_VERSION = 9

Bad credential version

EMUNGE_BAD_ZIP = 12

Bad credential compression type

EMUNGE_CRED_EXPIRED = 15

Credential expired

EMUNGE_CRED_INVALID = 14

Credential invalid

EMUNGE_CRED_REPLAYED = 17

Credential replayed

EMUNGE_CRED_REWOUND = 16

Credential created in the future

EMUNGE_CRED_UNAUTHORIZED = 18

Credential decode unauthorized

EMUNGE_NO_MEMORY = 5

Out of memory

EMUNGE_OVERFLOW = 4

Buffer overflow

EMUNGE_SNAFU = 1

Internal error

EMUNGE_SOCKET = 6

Munged communication error

EMUNGE_SUCCESS = 0

Success

EMUNGE_TIMEOUT = 7

Munged timeout

Low-level API

The pymunge.raw module provides access to the low-level C API of libmunge. See the module documentation.