GMime.CryptoContext

Subclasses:

GMime.GpgContext, GMime.Pkcs7Context

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class	new (protocol)
	decrypt (flags, session_key, istream, ostream)
	digest_id (name)
	digest_name (digest)
	encrypt (sign, userid, flags, recipients, istream, ostream)
	export_keys (keys, ostream)
	get_encryption_protocol ()
	get_key_exchange_protocol ()
	get_signature_protocol ()
	import_keys (istream)
	sign (detach, userid, istream, ostream)
	verify (flags, istream, sigstream, ostream)

Virtual Methods

Inherited:

GObject.Object (7)

	do_decrypt (flags, session_key, istream, ostream)
	do_digest_id (name)
	do_digest_name (digest)
	do_encrypt (sign, userid, flags, recipients, istream, ostream)
	do_export_keys (keys, ostream)
	do_get_encryption_protocol ()
	do_get_key_exchange_protocol ()
	do_get_signature_protocol ()
	do_import_keys (istream)
	do_sign (detach, userid, istream, ostream)
	do_verify (flags, istream, sigstream, ostream)

Properties

None

Signals

Inherited:

GObject.Object (1)

Fields

Inherited:

GObject.Object (1)

Name	Type	Access	Description
parent_object	GObject.Object	r	parent GObject.Object
request_passwd	GMime.PasswordRequestFunc	r	a callback for requesting a password

Class Details

class GMime.CryptoContext(**kwargs)

Bases:

GObject.Object

Abstract:

No

Structure:

GMime.CryptoContextClass

A crypto context for use with MIME.

classmethod new(protocol)

Parameters:

protocol (str) – the crypto protocol

Returns:

a newly allocated GMime.CryptoContext.

Return type:

GMime.CryptoContext or None

Creates a new crypto context for the specified protocol.

decrypt(flags, session_key, istream, ostream)

Parameters:

• flags (GMime.DecryptFlags) – a set of GMime.DecryptFlags

• session_key (str or None) – the session key to use or None

• istream (GMime.Stream) – input/ciphertext stream

• ostream (GMime.Stream) – output/cleartext stream

Raises:

GLib.Error

Returns:

a GMime.DecryptResult on success or None on error.

Return type:

GMime.DecryptResult

Decrypts the ciphertext input stream and writes the resulting cleartext to the output stream.

When non-None, session_key should be a None-terminated string, such as the one returned by GMime.DecryptResult.get_session_key() from a previous decryption. If the session_key is not valid, decryption will fail.

If the encrypted input stream was also signed, the returned GMime.DecryptResult will have a non-None list of signatures, each with a GMime.SignatureStatus (among other details about each signature).

On success, the returned GMime.DecryptResult will contain a list of certificates, one for each recipient, that the original encrypted stream was encrypted to.

Note: It *may* be possible to maliciously design an encrypted stream such that recursively decrypting it will result in an endless loop, causing a denial of service attack on your application.

digest_id(name)

Parameters:

name (str) – digest name

Returns:

the equivalent digest id or GMime.DigestAlgo.DEFAULT on fail.

Return type:

GMime.DigestAlgo

Gets the digest id based on the digest name.

digest_name(digest)

Parameters:

digest (GMime.DigestAlgo) – digest id

Returns:

the equivalent digest name or None on fail.

Return type:

str or None

Gets the digest name based on the digest id digest.

encrypt(sign, userid, flags, recipients, istream, ostream)

Parameters:

• sign (bool) – sign as well as encrypt

• userid (str or None) – the key id (or email address) to use when signing (assuming sign is True)

• flags (GMime.EncryptFlags) – a set of GMime.EncryptFlags

• recipients ([str]) – an array of recipient key ids and/or email addresses

• istream (GMime.Stream) – cleartext input stream

• ostream (GMime.Stream) – ciphertext output stream

Raises:

GLib.Error

Returns:

%0 on success or %-1 on fail.

Return type:

int

Encrypts (and optionally signs) the cleartext input stream and writes the resulting ciphertext to the output stream.

export_keys(keys, ostream)

Parameters:

• keys (str) – an array of key ids, terminated by a None element

• ostream (GMime.Stream) – output stream

Raises:

GLib.Error

Returns:

%0 on success or %-1 on fail.

Return type:

int

Exports the keys/certificates in keys to the stream ostream from the key/certificate database controlled by self.

If keys is None or contains only a None element, then all keys will be exported.

get_encryption_protocol()

Returns:

the encryption protocol or None if not supported.

Return type:

str or None

Gets the encryption protocol for the crypto context.

get_key_exchange_protocol()

Returns:

the key exchange protocol or None if not supported.

Return type:

str or None

Gets the key exchange protocol for the crypto context.

get_signature_protocol()

Returns:

the signature protocol or None if not supported.

Return type:

str or None

Gets the signature protocol for the crypto context.

import_keys(istream)

Parameters:

istream (GMime.Stream) – input stream (containing keys)

Raises:

GLib.Error

Returns:

the total number of keys imported on success or %-1 on fail.

Return type:

int

Imports a stream of keys/certificates contained within istream into the key/certificate database controlled by self.

sign(detach, userid, istream, ostream)

Parameters:

• detach (bool) – True if ostream should be the detached signature; otherwise, False

• userid (str) – private key to use to sign the stream

• istream (GMime.Stream) – input stream

• ostream (GMime.Stream) – output stream

Raises:

GLib.Error

Returns:

the GMime.DigestAlgo used on success or %-1 on fail.

Return type:

int

Signs the input stream and writes the resulting signature to the output stream.

verify(flags, istream, sigstream, ostream)

Parameters:

• flags (GMime.VerifyFlags) – a GMime.VerifyFlags

• istream (GMime.Stream) – input stream

• sigstream (GMime.Stream or None) – detached-signature stream

• ostream (GMime.Stream or None) – output stream for use with encapsulated signature input streams

Raises:

GLib.Error

Returns:

a GMime.SignatureList object containing the status of each signature or None on error.

Return type:

GMime.SignatureList or None

Verifies the signature. If istream is a clearsigned stream, you should pass None as the sigstream parameter and may wish to provide an ostream argument for GMime to output the original plaintext into. Otherwise sigstream is assumed to be the signature stream and is used to verify the integirity of the istream.

do_decrypt(flags, session_key, istream, ostream) virtual

Parameters:

• flags (GMime.DecryptFlags) – a set of GMime.DecryptFlags

• session_key (str or None) – the session key to use or None

• istream (GMime.Stream) – input/ciphertext stream

• ostream (GMime.Stream) – output/cleartext stream

Returns:

a GMime.DecryptResult on success or None on error.

Return type:

GMime.DecryptResult

Decrypts the ciphertext input stream and writes the resulting cleartext to the output stream.

When non-None, session_key should be a None-terminated string, such as the one returned by GMime.DecryptResult.get_session_key() from a previous decryption. If the session_key is not valid, decryption will fail.

If the encrypted input stream was also signed, the returned GMime.DecryptResult will have a non-None list of signatures, each with a GMime.SignatureStatus (among other details about each signature).

On success, the returned GMime.DecryptResult will contain a list of certificates, one for each recipient, that the original encrypted stream was encrypted to.

Note: It *may* be possible to maliciously design an encrypted stream such that recursively decrypting it will result in an endless loop, causing a denial of service attack on your application.

do_digest_id(name) virtual

Parameters:

name (str) – digest name

Returns:

the equivalent digest id or GMime.DigestAlgo.DEFAULT on fail.

Return type:

GMime.DigestAlgo

Gets the digest id based on the digest name.

do_digest_name(digest) virtual

Parameters:

digest (GMime.DigestAlgo) – digest id

Returns:

the equivalent digest name or None on fail.

Return type:

str or None

Gets the digest name based on the digest id digest.

do_encrypt(sign, userid, flags, recipients, istream, ostream) virtual

Parameters:

• sign (bool) – sign as well as encrypt

• userid (str or None) – the key id (or email address) to use when signing (assuming sign is True)

• flags (GMime.EncryptFlags) – a set of GMime.EncryptFlags

• recipients ([str]) – an array of recipient key ids and/or email addresses

• istream (GMime.Stream) – cleartext input stream

• ostream (GMime.Stream) – ciphertext output stream

Returns:

%0 on success or %-1 on fail.

Return type:

int

Encrypts (and optionally signs) the cleartext input stream and writes the resulting ciphertext to the output stream.

do_export_keys(keys, ostream) virtual

Parameters:

• keys (str) – an array of key ids, terminated by a None element

• ostream (GMime.Stream) – output stream

Returns:

%0 on success or %-1 on fail.

Return type:

int

Exports the keys/certificates in keys to the stream ostream from the key/certificate database controlled by ctx.

If keys is None or contains only a None element, then all keys will be exported.

do_get_encryption_protocol() virtual

Returns:

the encryption protocol or None if not supported.

Return type:

str or None

Gets the encryption protocol for the crypto context.

do_get_key_exchange_protocol() virtual

Returns:

the key exchange protocol or None if not supported.

Return type:

str or None

Gets the key exchange protocol for the crypto context.

do_get_signature_protocol() virtual

Returns:

the signature protocol or None if not supported.

Return type:

str or None

Gets the signature protocol for the crypto context.

do_import_keys(istream) virtual

Parameters:

istream (GMime.Stream) – input stream (containing keys)

Returns:

the total number of keys imported on success or %-1 on fail.

Return type:

int

Imports a stream of keys/certificates contained within istream into the key/certificate database controlled by ctx.

do_sign(detach, userid, istream, ostream) virtual

Parameters:

• detach (bool) – True if ostream should be the detached signature; otherwise, False

• userid (str) – private key to use to sign the stream

• istream (GMime.Stream) – input stream

• ostream (GMime.Stream) – output stream

Returns:

the GMime.DigestAlgo used on success or %-1 on fail.

Return type:

int

Signs the input stream and writes the resulting signature to the output stream.

do_verify(flags, istream, sigstream, ostream) virtual

Parameters:

• flags (GMime.VerifyFlags) – a GMime.VerifyFlags

• istream (GMime.Stream) – input stream

• sigstream (GMime.Stream or None) – detached-signature stream

• ostream (GMime.Stream or None) – output stream for use with encapsulated signature input streams

Returns:

a GMime.SignatureList object containing the status of each signature or None on error.

Return type:

GMime.SignatureList or None

Verifies the signature. If istream is a clearsigned stream, you should pass None as the sigstream parameter and may wish to provide an ostream argument for GMime to output the original plaintext into. Otherwise sigstream is assumed to be the signature stream and is used to verify the integirity of the istream.