CkMime Python Programming
Reference Documentation
CkMime
Chilkat MIME allows you to easily create and manipulate MIME and S/MIME messages from within your applications. ("Chilkat MIME" may be referred to as "Chilkat S/MIME" on some chilkatsoft.com web pages. They are the same product.) The Chilkat MIME license also includes the Chilkat DKIM component/class/libs for creating and verifying DKIM / DomainKey signatures.
Object Creation
obj = chilkat.CkMime()
Properties
# str is a CkString object (output)
get_Boundary( str )
# newVal is a string (input)
put_Boundary( newVal )
The boundary string for a multipart MIME message.
It is the value of the boundary attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/mixed; boundary="------------080707010302060306060800"
then the value of the Boundary property is "------------080707010302060306060800".
When building multipart MIME messages, the boundary is automatically generated by methods such as NewMultipartMixed, to be a unique and random string, so explicitly setting the boundary is usually not necessary. Example Code: Create a Multipart-Mixed MIME Message with Auto-Generated Boundary and with Explicitly Set Boundary
# sb is a CkString object (output)
get_Charset( sb )
# newVal is a string (input)
put_Charset( newVal )
The value of the "charset" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: text/plain; charset="iso-8859-1"
then the value of the Charset property is "iso-8859-1".Example Code: Demonstrates the effect of setting the Charset property.
# str is a CkString object (output)
get_ContentType( str )
# newVal is a string (input)
put_ContentType( newVal )
The MIME content type, such as "text/plain", "text/html", "image/gif", "multipart/alternative", "multipart/mixed", etc.
It is the value of the Content-Type header field, excluding any attributes. For example, if the Content-Type header is this:
Content-Type: multipart/mixed; boundary="------------080707010302060306060800"
then the value of the ContentType property is "multipart/mixed".
# str is a CkString object (output)
get_CurrentDateTime( str )
Returns the current date/time in RFC 822 format.
# str is a CkString object (output)
get_Disposition( str )
# newVal is a string (input)
put_Disposition( newVal )
The value of the Content-Disposition header field, excluding any attributes. For example, if the Content-Disposition header is this:
Content-Disposition: attachment; filename="starfish.gif"
then the value of the Disposition property is "attachment".
# str is a CkString object (output)
get_Encoding( str )
# newVal is a string (input)
put_Encoding( newVal )
The value of the Content-Transfer-Encoding header field. Typical values are "base64", "quoted-printable", "7bit", "8bit", "binary", etc. For example, if the Content-Transfer-Encoding header is this:
Content-Transfer-Encoding: base64
then the value of the Encoding property is "base64".
# str is a CkString object (output)
get_Filename( str )
# newVal is a string (input)
put_Filename( newVal )
The value of the "filename" attribute of the Content-Disposition header field. For example, if the Content-Disposition header is this:
Content-Disposition: attachment; filename="starfish.gif"
then the value of the Filename property is "starfish.gif".
# str is a CkString object (output)
LastErrorHtml( str )
Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
Error information in XML format for the last method called.
# str is a CkString object (output)
get_Micalg( str )
# newVal is a string (input)
put_Micalg( newVal )
The value of the "micalg" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1;
boundary="------------ms000908010507020408060303"
then the value of the Micalg property is "sha".
Note: The micalg attribute is only present in PKCS7 signed MIME. Setting the Micalg property has the effect of choosing the hash algorithm used w/ signing. Possible choices are "sha1", "md5", "sha256", "sha384", and "sha512". However, it is preferable to set the signing hash algorithm by setting the SigningHashAlg property instead.
# str is a CkString object (output)
get_Name( str )
# newVal is a string (input)
put_Name( newVal )
The value of the "name" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: image/gif; name="starfish.gif"
then the value of the Name property is "starfish.gif".
# Returns an integer value
get_NumEncryptCerts( )
The number of certificates found when decrypting S/MIME. This property is set after UnwrapSecurity is called.
# Returns an integer value
get_NumHeaderFields( )
The number of header fields. Header field names and values can be retrieved by index (starting at 0) by calling GetHeaderFieldName and GetHeaderFieldValue.
# Returns an integer value
get_NumParts( )
The number of sub-parts contained within this message. Each sub-part is a complete Chilkat MIME message itself.
# Returns an integer value
get_NumSignerCerts( )
The number of certificates found when verifying signature(s). This property is set after UnwrapSecurity is called.
# str is a CkString object (output)
get_Pkcs7CryptAlg( str )
# newVal is a string (input)
put_Pkcs7CryptAlg( newVal )
When the MIME is encrypted (using PKCS7 public-key encryption), this selects the underlying symmetric encryption algorithm. Possible values are: "aes", "des", "3des", and "rc2".
# Returns an integer value
get_Pkcs7KeyLength( )
# newVal is an integer (input)
put_Pkcs7KeyLength( newVal )
When the MIME is encrypted (using PKCS7 public-key encryption), this selects the key length of the underlying symmetric encryption algorithm. The possible values allowed depend on the Pkcs7CryptAlg property. For "aes", the key length may be 128, 192, or 256. For "3des" the key length must be 192. For "des" the key length must be 40. For "rc2" the key length can be 40, 56, 64, or 128.
# str is a CkString object (output)
get_Protocol( str )
# newVal is a string (input)
put_Protocol( newVal )
The value of the "protocol" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1;
boundary="------------ms000908010507020408060303"
then the value of the Protocol property is "application/x-pkcs7-signature".
# str is a CkString object (output)
get_SigningHashAlg( str )
# newVal is a string (input)
put_SigningHashAlg( newVal )
Selects the underlying hash algorithm used when creating signed (PKCS7) MIME. Possible values are "sha1", "sha256", "sha384", "sha512", "md5", and "md2".
# Returns a boolean value
get_UnwrapExtras( )
# newVal is a boolean (input)
put_UnwrapExtras( newVal )
Controls whether extra (informative) header fields are added to the MIME message when unwrapping security.
# Returns a boolean value
get_UseMmDescription( )
# newVal is a boolean (input)
put_UseMmDescription( newVal )
Controls whether the boilerplate text "This is a multi-part message in MIME format." is used as the body content of a multipart MIME part. Example Code: Create a Multipart-Mixed MIME Message (shows the difference when UseMmDescription is on/off).
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
# Returns a boolean value
get_VerboseLogging( )
# newVal is a boolean (input)
put_VerboseLogging( newVal )
If True, increases the amount of information available in LastErrorText (or LastErrorXml / LastErrorHtml). The default is False.
# str is a CkString object (output)
get_Version( str )
The version, such as "1.0.0".
Methods
AddContentLength( )
Computes the size of the MIME body and adds a Content-Length header field with the computed value. If the MIME body is non-multipart, the Content-Length is just the size of the content. If the MIME is multipart, then the Content-Length is the sum of all the sub-parts. Calling this method more than once causes the Content-Length header to be re-computed and updated. Add Content-Length Header to a MIME Message
# cert is a CkCert object (input)
# Returns a boolean value
AddDetachedSignature( cert )
Signs the message using the certificate provided. If successful, the message is converted to "multipart/signed" and the original message will be contained in the first sub-part. Returns True for success, False for failure. Example Code: Create PKCS7 Detached Signature (S/MIME) Example: Add S/MIME Signature using PFX
# transferHeaderFields is a boolean (input)
# Returns a boolean value
AddDetachedSignature2( cert, transferHeaderFields )
Same as AddDetachedSignature, except an extra argument is provided to control whether header fields from the calling MIME object are transferred to the content part of the multipart/signed object. This method transforms the calling object into a multipart/signed MIME with two sub-parts. The first contains the original content of the calling object, and the second contains the digital signature. Returns True for success, False for failure.
# Returns a boolean value
AddDetachedSignaturePk( cert, privateKey )
To be documented soon.
# transferHeaderFields is a boolean (input)
# Returns a boolean value
AddDetachedSignaturePk2( cert, privateKey, transferHeaderFields )
To be documented soon.
# Returns a boolean value
AddEncryptCert( cert )
Adds a certificate to the object's internal list of certificates to be used when the EncryptN method is called. (See the EncryptN method for more information.) The internal list may be cleared by calling ClearEncryptCerts. Returns True for success, False for failure.
# name is a string (input)
# value is a string (input)
# Returns a boolean value
AddHeaderField( name, value )
Adds a header field to the MIME.
# pfxFileData is a CkByteData object (output)
# pfxPassword is a string (input)
# Returns a boolean value
AddPfxSourceData( pfxFileData, pfxPassword )
Adds a PFX to the object's internal list of sources to be searched for certificates and private keys when decrypting . Multiple PFX sources can be added by calling this method once for each. (On the Windows operating system, the registry-based certificate stores are also automatically searched, so it is commonly not required to explicitly add PFX sources.)
The pfxFileData contains the bytes of a PFX file (also known as PKCS12 or .p12). Returns True for success, False for failure.
# pfxFilePath is a string (input)
# password is a string (input)
# Returns a boolean value
AddPfxSourceFile( pfxFilePath, password )
Adds a PFX file to the object's internal list of sources to be searched for certificates and private keys when decrypting. Multiple PFX files can be added by calling this method once for each. (On the Windows operating system, the registry-based certificate stores are also automatically searched, so it is commonly not required to explicitly add PFX sources.)
The ARG1 contains the bytes of a PFX file (also known as PKCS12 or .p12). Returns True for success, False for failure.
# mime is a CkMime object (input)
# Returns a boolean value
AppendPart( mime )
Appends a MIME message to the sub-parts of this message. Arbitrarily complex messages with unlimited nesting levels can be created. If the calling Mime object is not already multipart, it is automatically converted to multipart/mixed first.
# filename is a string (input)
# Returns a boolean value
AppendPartFromFile( filename )
Loads a file and creates a Mime message object using the file extension to determine the content type, and adds it as a sub-part to the calling object. Returns True for success, False for failure.
# outStr is a CkString object (output)
# Returns a boolean value
AsnBodyToXml( outStr )
To be documented soon. Returns True for success, False for failure.
ClearEncryptCerts( )
Clears the internal list of certificates added by previous calls to the AddEncryptCert method. (See the EncryptN method for information about encrypting using multiple certificates.)
# Returns a boolean value
ContainsEncryptedParts( )
Returns True if the MIME message contains encrypted parts.
Note: This method examines the MIME as-is. If UnwrapSecurity is called and it is successful, then the MIME should no longer contain encrypted parts, and this method would return 0.
Note: If a signed MIME message is then encrypted, then it is not possible to know that the MIME is both encrypted and signed until UnwrapSecurity is called. (In other words, it is not possible to know the contents of the encrypted MIME until it is decrypted.) Therefore, the ContainsSignedParts method would return False.
# Returns a boolean value
ContainsSignedParts( )
Returns True if the MIME message contains signed parts.
Note: This method examines the MIME as-is. If UnwrapSecurity is called and it is successful, then the MIME should no longer contain signed parts, and this method would return 0.
Note: If a signed MIME message is then encrypted, then it is not possible to know that the MIME is both encrypted and signed until UnwrapSecurity is called. (In other words, it is not possible to know the contents of the encrypted MIME until it is decrypted.) Therefore, the ContainsSignedParts method would return False.
Note: The same concept also applies to opaque signatures, such as with the MIME produced by calling ConvertToSigned.
Convert8Bit( )
Changes the content-transfer-encoding to "base64" for all 8bit or binary MIME subparts. This allows for the MIME to be exported as a string via the GetMime method.
ConvertToMultipartAlt( )
To be documented soon. Returns True for success, False for failure.
ConvertToMultipartMixed( )
To be documented soon. Returns True for success, False for failure.
# cert is a CkCert object (input)
# Returns a boolean value
ConvertToSigned( cert )
Digitally signs a MIME message. The MIME is converted to an application/x-pkcs7-mime which is a PKCS7 signature that includes both the original MIME message and the signature. This is different than AddDetachedSignature, where the signature is appended to the MIME.
Note: This is commonly referred to as an "opaque" signature. Returns True for success, False for failure. Example Code: Create PKCS7 Attached/Opaque Signature (S/MIME)
# Returns a boolean value
ConvertToSignedPk( cert, privateKey )
To be documented soon. Returns True for success, False for failure.
# Returns a boolean value
Decrypt( )
If the MIME is PKCS7 encrypted, this method can decrypt. Information about the certificates required for decryption is always embedded within a PKCS7 enveloped (i.e. encrypted) message. This method will automatically use this information to locate the certificate + private key in Windows-based registry stores. If the cert + private key was previously installed, such as from a PFX, then the Decrypt method should be able to find it.
If the required cert + private key was NOT previously installed, then it is possible to use PFX files directly. See the AddPfxSourceData and AddPfxSourceFile methods for more information. (Also, see the example linked below.) Returns True for success, False for failure. Example Code: PKCS7 Decrypt MIME
# Returns a boolean value
Decrypt2( cert, privateKey )
To be documented soon. Returns True for success, False for failure.
# pfxData is a CkByteData object (output)
# password is a string (input)
# Returns a boolean value
DecryptUsingPfxData( pfxData, password )
Decrypts MIME using a specific PFX ( also known as PKCS12, which is a file format commonly used to store private keys with accompanying public key certificates, protected with a password-based symmetric key). This method allows the bytes of the PKCS12 file to be passed directly, thus allowing PKCS12's to be persisted and retrieved from non-file-based locations, such as in LDAP or a database. Returns True for success, False for failure.
# pfxFilePath is a string (input)
# pfxPassword is a string (input)
# Returns a boolean value
DecryptUsingPfxFile( pfxFilePath, pfxPassword )
Decrypts MIME using a specific PFX file (also known as PKCS12) as the source for any required certificates and private keys. (Note: .pfx and .p12 files are both PKCS12 format.) Returns True for success, False for failure. PKCS7 Decrypt Using .pfx or .p12 File
# cert is a CkCert object (input)
# Returns a boolean value
Encrypt( cert )
Encrypts the MIME to create PKCS7 encrypted MIME. A digital certificate (which always contains a public-key) is used to encrypt. Returns True for success, False for failure. Example Code: PKCS7 Encrypt MIME
# Returns a boolean value
EncryptN( )
Encrypt MIME using any number of digital certificates. Each certificate to be used must first be added by calling AddEncryptCert (once per certificate). See the example code below: Returns True for success, False for failure. Example: PKCS7 Encrypt using Multiple Certificates
# dirPath is a string (input)
ExtractPartsToFiles( dirPath )
Recursively descends through the parts of a MIME message and extracts all parts having a filename to a file. The files are created in dirPath. Returns a (Ck)StringArray object containing the names of the files created. The filenames are obtained from the "filename" attribute of the content-disposition header. If a filename does not exist, then the MIME part is not saved to a file. Returns a null reference on failure Extract Files from MIME
# db is a CkByteData object (output)
# Returns a boolean value
GetBodyBinary( db )
Returns the body of the MIME message as a block of binary data. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned.
# decodedBody is a CkString object (output)
# Returns a boolean value
GetBodyDecoded( decodedBody )
Returns the body of the MIME message as a string. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned. Returns True for success, False for failure. Example Code: GetBodyEncoded / GetBodyDecoded Example Code: MIME Body vs. Sub-Parts
# encodedBody is a CkString object (output)
# Returns a boolean value
GetBodyEncoded( encodedBody )
Returns the body of the MIME message as a String. The body is explicitly not decoded from it's encoding type, so if it was represented in Base64, you will get the Base64 encoded body, as an example. Returns True for success, False for failure. Example Code: GetBodyEncoded / GetBodyDecoded Example Code: MIME Body vs. Sub-Parts
# index is an integer (input)
# Returns a CkCert object
GetEncryptCert( index )
Returns the Nth certificate found when decrypting. The EncryptCerts property contains the number of certificates.
# str is a CkString object (output)
GetEntireBody( str )
Returns the entire MIME body, including all sub-parts. Returns True for success, False for failure.
# str is a CkString object (output)
GetEntireHead( str )
Returns the MIME header. Returns True for success, False for failure.
# fieldName is a string (input)
# value is a CkString object (output)
# Returns a boolean value
GetHeaderField( fieldName, value )
Returns the value of a MIME header field. fieldName is case-insensitive. Returns True for success, False for failure.
# name is a string (input)
# attrName is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetHeaderFieldAttribute( name, attrName, outStr )
Parses a MIME header field and returns the value of an attribute. MIME header fields w/ attributes are formatted like this:
Header-Name: value; attrName1="value1"; attrName2="value2"; .... attrNameN="valueN"
Semi-colons separate attribute name=value pairs. The Content-Type header field often contains attributes. Here is an example:
Content-Type: multipart/signed;
protocol="application/x-pkcs7-signature";
micalg=SHA1;
boundary="----=_NextPart_000_0000_01CB03E4.D0BAF010"
In the above example, to access the value of the "protocol" attribute, call GetHeaderFieldAttribute("Content-Type", "protocol");Returns True for success, False for failure. Example Code: Parse MIME Header Fields
# index is an integer (input)
# fieldName is a CkString object (output)
# Returns a boolean value
GetHeaderFieldName( index, fieldName )
Returns the Nth MIME header field name. Returns True for success, False for failure.
# index is an integer (input)
# fieldValue is a CkString object (output)
# Returns a boolean value
GetHeaderFieldValue( index, fieldValue )
Returns the Nth MIME header field value. Returns True for success, False for failure.
# mime is a CkString object (output)
# Returns a boolean value
GetMime( mime )
Returns a string containing the complete MIME message, including all sub-parts. Returns True for success, False for failure.
# outBytes is a CkByteData object (output)
# Returns a boolean value
GetMimeBytes( outBytes )
Returns a byte array containing the complete MIME message, including all sub-parts.
# index is an integer (input)
# Returns a CkMime object
GetPart( index )
Returns the Nth sub-part of the MIME message. Indexing begins at 0.
# index is an integer (input)
# sysTime is a SYSTEMTIME object (output)
# Returns a boolean value
GetSignatureSigningTime( index, sysTime )
To be documented soon.
# index is an integer (input)
# Returns a CkCert object
GetSignerCert( index )
Returns the Nth digital certificate used to sign the MIME message. Indexing begins at 0.
# xml is a CkString object (output)
# Returns a boolean value
GetXml( xml )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string. Returns True for success, False for failure.
# index is an integer (input)
# Returns a boolean value
HasSignatureSigningTime( index )
To be documented soon.
# Returns a boolean value
IsApplicationData( )
Return True if the MIME message contains application data, otherwise returns False.
# Returns a boolean value
IsAttachment( )
Return True if this MIME message is an attachment, otherwise returns False.
# Returns a boolean value
IsAudio( )
Return True if the MIME message contains audio data, otherwise returns False.
# Returns a boolean value
IsEncrypted( )
Returns True if the MIME message is PKCS7 encrypted, otherwise returns False.
# Returns a boolean value
IsHtml( )
Return True if the MIME body is HTML, otherwise returns False.
# Returns a boolean value
IsImage( )
Return True if the MIME message contains image data, otherwise returns False.
# Returns a boolean value
IsMultipart( )
Return True if the MIME message is multipart (multipart/mixed, multipart/related, multipart/alternative, etc.), otherwise returns False.
# Returns a boolean value
IsMultipartAlternative( )
Return True if the MIME message is multipart/alternative, otherwise returns False.
# Returns a boolean value
IsMultipartMixed( )
Return true if the MIME message is multipart/mixed, otherwise returns False.
# Returns a boolean value
IsMultipartRelated( )
Return True if the MIME message is multipart/related, otherwise returns False.
# Returns a boolean value
IsPlainText( )
Return True if the MIME message body is plain text, otherwise returns False.
# Returns a boolean value
IsSigned( )
Return True if the MIME message is PKCS7 digitally signed, otherwise returns False.
# Returns a boolean value
IsText( )
Return True if the MIME message body is any text content type, such as text/plain, text/html, text/xml, etc., otherwise returns False.
# Returns a boolean value
IsUnlocked( )
Returns True if the component is already unlocked, otherwise returns False.
# Returns a boolean value
IsVideo( )
Return True if the MIME message contains video data, otherwise returns False.
# Returns a boolean value
IsXml( )
Return True if the MIME message body is XML, otherwise returns False.
# mimeMsg is a string (input)
# Returns a boolean value
LoadMime( mimeMsg )
Discards the current contents of the MIME object and loads a new MIME message from a string.
# fileName is a string (input)
# Returns a boolean value
LoadMimeFile( fileName )
Discards the current contents of the MIME object and loads a new MIME message from a file. Returns True for success, False for failure.
# xml is a string (input)
# Returns a boolean value
LoadXml( xml )
Converts XML to MIME and replaces the MIME object's contents with the converted XML.
# fileName is a string (input)
# Returns a boolean value
LoadXmlFile( fileName )
Converts XML to MIME and replaces the MIME object's contents with the converted XML. Returns True for success, False for failure.
# mimeObject is a CkMime object (input)
# Returns a boolean value
NewMessageRfc822( mimeObject )
Clears the Mime object and initializes it such that the header contains a "content-type: message/rfc822" line and the body is the MIME text of the Mime object passed to the method.
# Returns a boolean value
NewMultipartAlternative( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/alternative message.
# Returns a boolean value
NewMultipartMixed( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/mixed message. Example Code: Create a Multipart-Mixed MIME Message
# Returns a boolean value
NewMultipartRelated( )
Discards the current MIME message header fields and contents, if any, an initializes the MIME object to be an empty mulipart/related message.
# fieldName is a string (input)
# bAllOccurances is a boolean (input)
RemoveHeaderField( fieldName, bAllOccurances )
Removes a header field from the MIME header. If bAllOccurances is True, then all occurances of the header field are removed. Otherwise, only the 1st occurance is removed.
# index is an integer (input)
# Returns a boolean value
RemovePart( index )
Removes the Nth subpart from the MIME message.
# filename is a string (input)
# Returns a boolean value
SaveBody( filename )
Saves the MIME message body to a file. If the body is base64 or quoted-printable encoded, it is automatically decoded.
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# filename is a string (input)
# Returns a boolean value
SaveMime( filename )
Saves the MIME message to a file, in MIME format. (This is the same as the .EML format used by Microsoft Outlook Express.)
# filename is a string (input)
# Returns a boolean value
SaveXml( filename )
Converts the MIME message to XML and saves to an XML file.
# str is a string (input)
SetBody( str )
Sets the MIME body content to a text string. Example Code: MIME SetBody
# dbuf is a CkByteData object (input)
# Returns a boolean value
SetBodyFromBinary( dbuf )
Sets the MIME message body from a byte array.
# encoding is a string (input)
# str is a string (input)
# Returns a boolean value
SetBodyFromEncoded( encoding, str )
Sets the MIME message body from a Base64 or Quoted-Printable encoded string.
# fileName is a string (input)
# Returns a boolean value
SetBodyFromFile( fileName )
Sets the MIME message body from the contents of a file. Note: A MIME message consists of a header and a body. The body may itself be a MIME message that consists of a header and body, etc. This method loads the contents of a file into the body of a MIME message, without replacing the header.
The Content-Type and Content-Transfer-Encoding header fields are automatically updated to match the type of content loaded (based on file extension). If your application requires the MIME to have a specific Content-Type and/or Content-Transfer-Encoding, set the ContentType and Encoding properties after calling this method (not before).
# str is a string (input)
# Returns a boolean value
SetBodyFromHtml( str )
Sets the MIME message body from a string containing HTML. The Content-Type header is added or updated to the value "text/html".
If 8bit (non-us-ascii) characters are present, and if the Charset property was not previously set, then the "charset" attribute is automatically added to the Content-Type header using the default value of "utf-8". This can be changed at any time by setting the Charset property.
If the Encoding property was not previously set, then the Content-Transfer-Encoding header is automatically added. It will be set to "7bit" or "8bit" depending on whether the HTML body contains 8-bit non-us-ascii characters.
To set the MIME body with no intentional side-effects, use SetBody instead. Example Code: Create MIME Containing HTML
# str is a string (input)
# Returns a boolean value
SetBodyFromPlainText( str )
Sets the MIME message body from a string containing plain-text. The Content-Type header is added or updated to the value "text/plain".
If 8bit (non-us-ascii) characters are present, and if the Charset property was not previously set, then the "charset" attribute is automatically added to the Content-Type header using the default value of "utf-8". This can be changed at any time by setting the Charset property.
If the Encoding property was not previously set, then the Content-Transfer-Encoding header is automatically added. It will be set to "7bit" or "8bit" depending on whether the plain-text body contains 8-bit non-us-ascii characters.
To set the MIME body with no intentional side-effects, use SetBody instead. Example Code: Create MIME Containing Plain-Text
# str is a string (input)
# Returns a boolean value
SetBodyFromXml( str )
Sets the MIME message body from a string containing XML. The Content-Type header is added or updated to the value "text/xml".
If 8bit (non-us-ascii) characters are present, and if the Charset property was not previously set, then the "charset" attribute is automatically added to the Content-Type header using the default value of "utf-8". This can be changed at any time by setting the Charset property.
If the Encoding property was not previously set, then the Content-Transfer-Encoding header is automatically added. It will be set to "7bit" or "8bit" depending on whether the plain-text body contains 8-bit non-us-ascii characters.
To set the MIME body with no intentional side-effects, use SetBody instead. Example Code: Create MIME Containing XML
# csp is a CkCSP object (input)
# Returns a boolean value
SetCSP( csp )
(Only applies to the Microsoft Windows OS) Sets the Cryptographic Service Provider (CSP) to be used for encryption / signing, or decryption / signature verification.
This is not commonly used becaues the default Microsoft CSP is typically appropriate.
One instance where SetCSP is necessary is when using the Crypto-Pro CSP for the GOST R 34.10-2001 and GOST R 34.10-94 providers.
# name is a string (input)
# value is a string (input)
# Returns a boolean value
SetHeaderField( name, value )
Adds or replaces a MIME message header field. If the field already exists, it is automatically replaced. Otherwise it is added. Pass zero-length value to remove the header field.
# cert is a CkCert object (input)
SetVerifyCert( cert )
Allows a certificate to be explicitly specified for verifying a signature.
# Returns a CkEmail object
ToEmailObject( )
Returns the MIME message converted to a CkEmail object. Returns a null reference on failure
# unlockCode is a string (input)
# Returns a boolean value
UnlockComponent( unlockCode )
Unlocks the component allowing for the full functionality to be used. If this method unexpectedly returns False, examine the contents of the LastErrorText property to determine the reason for failure. Returns True for success, False for failure.
# Returns a boolean value
UnwrapSecurity( )
Decrypts and/or verifies all digital signatures contained within the MIME message, and returns True if all decryptions and verifications succeeded. Otherwise returns False. After unwrapping, the information regarding security and certificates can be obtained by the methods GetSignerCert and GetEncryptCert, and the properties NumEncryptCerts and NumSignerCerts.
The MIME is restored to the original structure/content prior to all signing and/or encryption.
The difference between UnwrapSecurity and methods such as Verify or Decrypt is that UnwrapSecurity will recursively traverse the MIME to decrypt and/or verify all parts. Also, UnwrapSecurity will unwrap layers until no further encrypted/signed content is found. For example, if a MIME message was encrypted and then subsequently signed, then UnwrapSecurity will verify and unwrap the detached signature/signed-data layer, and then decrypt the "enveloped data". Returns True for success, False for failure.
# charset is a string (input)
UrlEncodeBody( charset )
To be documented soon.
# Returns a boolean value
Verify( )
Verifies PKCS7 signed MIME and "unwraps" the signature. The MIME is restored to the original structure that it would have originally had prior to signing. The Verify method works with both detached signatures, as well as opaque/attached signatures.
A PKCS7 signature usually embeds both the signing certificate with its public key. Therefore, it is usually possible to verify a signature without the need to already have the certificate installed. If the signature does not embed the certificate, the Verify method will automatically locate and use the certificate if it was correctly pre-installed on the computer. Returns True for success, False for failure. Example Code: Verify and Unwrap PCKS7 Signed MIME
# Returns a string
asnBodyToXml( )
To be documented soon. Returns a null on failure
# Returns a string
bodyDecoded( )
Returns the body of the MIME message as a string. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned. Returns a null on failure
# Returns a string
bodyEncoded( )
Returns the body of the MIME message as a String. The body is explicitly not decoded from it's encoding type, so if it was represented in Base64, you will get the Base64 encoded body, as an example. Returns a null on failure
# Returns a string
boundary( )
The boundary string for a multipart MIME message.
It is the value of the boundary attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/mixed; boundary="------------080707010302060306060800"
then the value of the Boundary property is "------------080707010302060306060800".
When building multipart MIME messages, the boundary is automatically generated by methods such as NewMultipartMixed, to be a unique and random string, so explicitly setting the boundary is usually not necessary. Returns a null on failure Example Code: Create a Multipart-Mixed MIME Message with Auto-Generated Boundary and with Explicitly Set Boundary
# Returns a string
charset( )
The value of the "charset" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: text/plain; charset="iso-8859-1"
then the value of the Charset property is "iso-8859-1".Returns a null on failure Example Code: Demonstrates the effect of setting the Charset property.
# Returns a string
contentType( )
The MIME content type, such as "text/plain", "text/html", "image/gif", "multipart/alternative", "multipart/mixed", etc.
It is the value of the Content-Type header field, excluding any attributes. For example, if the Content-Type header is this:
Content-Type: multipart/mixed; boundary="------------080707010302060306060800"
then the value of the ContentType property is "multipart/mixed".Returns a null on failure
# Returns a string
currentDateTime( )
Returns the current date/time in RFC 822 format. Returns a null on failure
# Returns a string
disposition( )
The value of the Content-Disposition header field, excluding any attributes. For example, if the Content-Disposition header is this:
Content-Disposition: attachment; filename="starfish.gif"
then the value of the Disposition property is "attachment".Returns a null on failure
# Returns a string
encoding( )
The value of the Content-Transfer-Encoding header field. Typical values are "base64", "quoted-printable", "7bit", "8bit", "binary", etc. For example, if the Content-Transfer-Encoding header is this:
Content-Transfer-Encoding: base64
then the value of the Encoding property is "base64".Returns a null on failure
# Returns a string
entireBody( )
Returns the entire MIME body, including all sub-parts. Returns a null on failure
# Returns a string
entireHead( )
Returns the MIME header. Returns a null on failure
# Returns a string
filename( )
The value of the "filename" attribute of the Content-Disposition header field. For example, if the Content-Disposition header is this:
Content-Disposition: attachment; filename="starfish.gif"
then the value of the Filename property is "starfish.gif".Returns a null on failure
# Returns a string
getBodyDecoded( )
Returns the body of the MIME message as a string. The body is automatically converted from its encoding type, such as base64 or quoted-printable, before being returned. Returns a null on failure Example Code: GetBodyEncoded / GetBodyDecoded Example Code: MIME Body vs. Sub-Parts
# Returns a string
getBodyEncoded( )
Returns the body of the MIME message as a String. The body is explicitly not decoded from it's encoding type, so if it was represented in Base64, you will get the Base64 encoded body, as an example. Returns a null on failure Example Code: GetBodyEncoded / GetBodyDecoded Example Code: MIME Body vs. Sub-Parts
# Returns a string
getEntireBody( )
Returns the entire MIME body, including all sub-parts. Returns a null on failure
# Returns a string
getEntireHead( )
Returns the MIME header. Returns a null on failure
# fieldName is a string (input)
# Returns a string
getHeaderField( fieldName )
Returns the value of a MIME header field. fieldName is case-insensitive. Returns a null on failure
# name is a string (input)
# attrName is a string (input)
# Returns a string
getHeaderFieldAttribute( name, attrName )
Parses a MIME header field and returns the value of an attribute. MIME header fields w/ attributes are formatted like this:
Header-Name: value; attrName1="value1"; attrName2="value2"; .... attrNameN="valueN"
Semi-colons separate attribute name=value pairs. The Content-Type header field often contains attributes. Here is an example:
Content-Type: multipart/signed;
protocol="application/x-pkcs7-signature";
micalg=SHA1;
boundary="----=_NextPart_000_0000_01CB03E4.D0BAF010"
In the above example, to access the value of the "protocol" attribute, call GetHeaderFieldAttribute("Content-Type", "protocol");Returns a null on failure Example Code: Parse MIME Header Fields
# index is an integer (input)
# Returns a string
getHeaderFieldName( index )
Returns the Nth MIME header field name. Returns a null on failure
# index is an integer (input)
# Returns a string
getHeaderFieldValue( index )
Returns the Nth MIME header field value. Returns a null on failure
# Returns a string
getMime( )
Returns a string containing the complete MIME message, including all sub-parts. Returns a null on failure
# Returns a string
getXml( )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string. Returns a null on failure
# name is a string (input)
# Returns a string
header( name )
Returns the content of a MIME header field. The "fieldName" is case-insensitive, and if the MIME header field does not exist, an empty string is returned. Returns a null on failure
# index is an integer (input)
# Returns a string
headerName( index )
Returns the Nth MIME header field name. Returns a null on failure
# index is an integer (input)
# Returns a string
headerValue( index )
Returns the Nth MIME header field value. Returns a null on failure
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.Returns a null on failure
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.Returns a null on failure
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.Returns a null on failure
# Returns a string
micalg( )
The value of the "micalg" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1;
boundary="------------ms000908010507020408060303"
then the value of the Micalg property is "sha".
Note: The micalg attribute is only present in PKCS7 signed MIME. Setting the Micalg property has the effect of choosing the hash algorithm used w/ signing. Possible choices are "sha1", "md5", "sha256", "sha384", and "sha512". However, it is preferable to set the signing hash algorithm by setting the SigningHashAlg property instead. Returns a null on failure
# Returns a string
mime( )
Returns a string containing the complete MIME message, including all sub-parts. Returns a null on failure
# Returns a string
name( )
The value of the "name" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: image/gif; name="starfish.gif"
then the value of the Name property is "starfish.gif".Returns a null on failure
# Returns a string
pkcs7CryptAlg( )
When the MIME is encrypted (using PKCS7 public-key encryption), this selects the underlying symmetric encryption algorithm. Possible values are: "aes", "des", "3des", and "rc2". Returns a null on failure
# Returns a string
protocol( )
The value of the "protocol" attribute of the Content-Type header field. For example, if the Content-Type header is this:
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1;
boundary="------------ms000908010507020408060303"
then the value of the Protocol property is "application/x-pkcs7-signature".Returns a null on failure
# Returns a string
signingHashAlg( )
Selects the underlying hash algorithm used when creating signed (PKCS7) MIME. Possible values are "sha1", "sha256", "sha384", "sha512", "md5", and "md2". Returns a null on failure
# Returns a string
version( )
The version, such as "1.0.0". Returns a null on failure
# Returns a string
xml( )
Converts the MIME (or S/MIME) message to XML and returns the XML as a string. Returns a null on failure
|