MIME image format. More...

#include <stdint.h>
#include <string.h>
#include <strings.h>
#include <ctype.h>
#include <errno.h>
#include <ipxe/image.h>
#include <ipxe/base64.h>
#include <ipxe/mime.h>

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
static const struct mime_type *	mime_type (const char *name)
	Identify MIME type.
static void	mime_parse_attribute (struct image image, const char value, const char eol, const char name, struct mime_attribute *attr)
	Parse MIME attribute.
static void	mime_parse_type (struct image image, const char value, const char eol, struct mime_headers headers)
	Parse Content-Type header.
static void	mime_parse_encoding (struct image image, const char value, const char eol __unused, struct mime_headers headers)
	Parse Content-Transfer-Encoding header.
static const struct mime_header *	mime_header (const char *line)
	Identify MIME header.
static int	mime_parse (struct image image, const char text, struct mime_headers *headers)
	Parse MIME headers.
static int	mime_decode_identity (struct image image, const struct mime_headers headers, struct image *decoded)
	Decode MIME entity with identity encoding.
static int	mime_decode_base64 (struct image image, const struct mime_headers headers, struct image *decoded)
	Decode MIME entity with Base64 encoding.
static const struct mime_encoding *	mime_encoding (const char *name)
	Identify MIME encoding.
static int	mime_extract_entity (struct image image, const struct mime_headers headers, struct image *extracted)
	Extract single MIME entity.
static const char *	mime_part_end (struct image image, const struct mime_attribute boundary, const char *pos)
	Find end of current part in multipart MIME image.
static const char *	mime_part_next (struct image image, const struct mime_attribute boundary, const char *pos)
	Find start of next part in multipart MIME image.
static int	mime_extract_part (struct image image, const struct mime_headers headers, struct image *extracted)
	Extract part from multipart MIME image.
static int	mime_probe (struct image *image)
	Probe MIME image.
static int	mime_extract (struct image image, struct image extracted)
	Extract MIME image.
struct image_type mime_image_type	__image_type (PROBE_NORMAL)
	MIME image type.

Variables
const struct mime_header	mime_headers []
	Recognised MIME headers.
static const struct mime_encoding	mime_encodings []
	MIME encodings.
static const struct mime_type	mime_types []
	MIME types.

Detailed Description

MIME image format.

The MIME format is defined in RFC 2045 and RFC 2046 (with reference to RFC 822). We treat it firstly as a simple single-member archive format where the content is extracted using the specified encoding.

We additionally support multipart MIME as an archive format from which we attempt to extract the first body part that has the MIME type "text/x-ipxe". This makes it possible to store both cloud-init configuration and an iPXE boot script in the same user metadata blob for a cloud instance.

Due to its historical origins, MIME is an irritatingly flexible format. We do not attempt to support all possible MIME files: only those that we might reasonably expect to encounter as cloud instance metadata.

Definition in file mime.c.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

References name.

◆ mime_type()

const struct mime_type * mime_type ( const char * name )

static

Identify MIME type.

Parameters

name Encoding

Return values

type	MIME type, or NULL if not recognised

Definition at line 531 of file mime.c.

                                                               {
        const struct mime_type *type;
        size_t len;
        unsigned int i;
 
        /* Identify MIME type */
        for ( i = 0 ; i < ( sizeof ( mime_types ) /
                            sizeof ( mime_types[0] ) ) ; i++ ) {
                type = &mime_types[i];
                len = strlen ( type->name );
                if ( ( strncasecmp ( name, type->name, len ) == 0 ) &&
                     ( ( name[len] == ';' ) || isspace ( name[len] ) ) ) {
                        return type;
                }
        }
 
        return NULL;
}

References isspace(), len, mime_types, name, NULL, strlen(), strncasecmp(), and type.

Referenced by mime_extract(), and mime_extract_part().

◆ mime_parse_attribute()

void mime_parse_attribute	(	struct image *	image,
		const char *	value,
		const char *	eol,
		const char *	name,
		struct mime_attribute *	attr )

static

Parse MIME attribute.

Parameters

image	MIME image
value	Header value
eol	End of header line
name	Attribute name (including terminating equals sign)
attr	MIME attribute to update

Definition at line 66 of file mime.c.

                                                                 {
        const char *match;
 
        /* Locate attribute */
        match = strcasestr ( value, name );
        if ( ( ! match ) || ( match >= eol ) )
                return;
        attr->value = ( match + strlen ( name ) );
        DBGC2 ( image, "MIME %s found %s\"", image->name, name );
 
        /* Determine attribute length */
        if ( attr->value[0] == '"' )
                attr->value++;
        attr->len = 0;
        while ( attr->value[attr->len] && ( attr->value[attr->len] != '"' ) &&
                ( ! isspace ( attr->value[attr->len] ) ) ) {
                DBGC2 ( image, "%c", attr->value[attr->len] );
                attr->len++;
        }
        DBGC2 ( image, "\"\n" );
        assert ( &attr->value[attr->len] <= eol );
}

References assert, attr, DBGC2, isspace(), image::name, name, strcasestr(), strlen(), and value.

Referenced by mime_parse_type().

◆ mime_parse_type()

void mime_parse_type	(	struct image *	image,
		const char *	value,
		const char *	eol,
		struct mime_headers *	headers )

static

Parse Content-Type header.

Parameters

image	MIME image
value	Header value
eol	End of header line
headers	MIME headers to update

Definition at line 99 of file mime.c.

                                                                              {
 
        /* Record content type */
        headers->type = value;
        DBGC2 ( image, "MIME %s found content type\n", image->name );
 
        /* Check for boundary separator */
        mime_parse_attribute ( image, value, eol, "boundary=",
                               &headers->boundary );
}

References DBGC2, headers, mime_parse_attribute(), image::name, and value.

◆ mime_parse_encoding()

void mime_parse_encoding	(	struct image *	image,
		const char *	value,
		const char *eol	__unused,
		struct mime_headers *	headers )

static

Parse Content-Transfer-Encoding header.

Parameters

image	MIME image
value	Header value
eol	End of header line
headers	MIME headers to update

Definition at line 119 of file mime.c.

                                                                 {
 
        /* Record content transfer encoding */
        headers->encoding = value;
        DBGC2 ( image, "MIME %s found content transfer encoding\n",
                image->name );
}

References __unused, DBGC2, headers, image::name, and value.

◆ mime_header()

const struct mime_header * mime_header ( const char * line )

static

Identify MIME header.

Parameters

line	Header line

Return values

header MIME header, or NULL if not recognised

Definition at line 148 of file mime.c.

                                                                   {
        const struct mime_header *header;
        unsigned int i;
 
        /* Identify MIME header */
        for ( i = 0 ; i < ( sizeof ( mime_headers ) /
                            sizeof ( mime_headers[0] ) ) ; i++ ) {
                header = &mime_headers[i];
                if ( strncasecmp ( line, header->name,
                                   strlen ( header->name ) ) == 0 ) {
                        return header;
                }
        }
 
        return NULL;
}

References header, NULL, strlen(), and strncasecmp().

Referenced by mime_parse().

◆ mime_parse()

int mime_parse	(	struct image *	image,
		const char *	text,
		struct mime_headers *	headers )

static

Parse MIME headers.

Parameters

image	MIME image
text	Start of MIME headers within image
headers	MIME headers to fill in

Return values

rc	Return status code

Definition at line 173 of file mime.c.

                                                       {
        const struct mime_header *header;
        const char *value;
        const char *line;
        const char *next;
        const char *eol;
 
        /* Initialise headers */
        memset ( headers, 0, sizeof ( *headers ) );
 
        /* Parse headers until reaching empty-line separator */
        for ( line = text ; ; line = next ) {
 
                /* Locate end of line */
                eol = strchr ( line, '\n' );
                if ( ! eol ) {
                        DBGC ( image, "MIME %s premature end of file\n",
                               image->name );
                        return -EINVAL;
                }
                next = ( eol + 1 );
 
                /* Check for empty line */
                if ( eol == line )
                        break;
                if ( eol[-1] == '\r' )
                        eol--;
                if ( eol == line )
                        break;
 
                /* Identify header (if recognised) */
                header = mime_header ( line );
                if ( ! header )
                        continue;
 
                /* Locate start of value */
                value = ( line + strlen ( header->name ) );
                while ( ( *value != '\n' ) && isspace ( *value ) )
                        value++;
 
                /* Parse header */
                header->parse ( image, value, eol, headers );
        }
 
        /* Check for mandatory headers */
        if ( ! headers->type ) {
                DBGC ( image, "MIME %s missing content type\n", image->name );
                return -EINVAL;
        }
 
        /* Record length of headers */
        headers->len = ( next - text );
 
        return 0;
}

References DBGC, EINVAL, header, headers, isspace(), memset(), mime_header(), image::name, next, strchr(), strlen(), and value.

Referenced by mime_extract(), mime_extract_part(), and mime_probe().

◆ mime_decode_identity()

int mime_decode_identity	(	struct image *	image,
		const struct mime_headers *	headers,
		struct image *	decoded )

static

Decode MIME entity with identity encoding.

Parameters

image	MIME image
headers	MIME headers
decoded	Decoded image

Return values

rc	Return status code

Definition at line 238 of file mime.c.

                                                          {
        size_t len;
        int rc;
 
        /* Allocate space */
        len = ( image->len - headers->len );
        if ( ( rc = image_set_len ( decoded, len ) ) != 0 )
                return rc;
 
        /* Decode data */
        memcpy ( decoded->rwdata, ( image->data + headers->len ), len );
 
        return 0;
}

References image::data, headers, image_set_len(), image::len, len, memcpy(), rc, and image::rwdata.

◆ mime_decode_base64()

int mime_decode_base64	(	struct image *	image,
		const struct mime_headers *	headers,
		struct image *	decoded )

static

Decode MIME entity with Base64 encoding.

Parameters

image	MIME image
headers	MIME headers
decoded	Decoded image

Return values

rc	Return status code

Definition at line 263 of file mime.c.

                                                        {
        const char *encoded;
        size_t max_len;
        int len;
        int rc;
 
        /* Allocate space for decoded data */
        encoded = ( image->text + headers->len );
        max_len = base64_decoded_max_len ( encoded );
        if ( ( rc = image_set_len ( decoded, max_len ) ) != 0 )
                return rc;
 
        /* Decode data */
        len = base64_decode ( encoded, decoded->rwdata, decoded->len );
        if ( len < 0 ) {
                rc = len;
                DBGC ( image, "MIME %s could not decode base64: %s\n",
                       image->name, strerror ( rc ) );
                return rc;
        }
        assert ( ( ( size_t ) len ) <= max_len );
 
        /* Set decoded length */
        if ( ( rc = image_set_len ( decoded, len ) ) != 0 )
                return rc;
 
        return 0;
}

References assert, base64_decode(), base64_decoded_max_len(), DBGC, headers, image_set_len(), image::len, len, image::name, rc, image::rwdata, strerror(), and image::text.

◆ mime_encoding()

const struct mime_encoding * mime_encoding ( const char * name )

static

Identify MIME encoding.

Parameters

name	Encoding name, or NULL to use default

Return values

encoding MIME encoding, or NULL if not recognised

Definition at line 321 of file mime.c.

                                                                       {
        const struct mime_encoding *encoding;
        size_t len;
        unsigned int i;
 
        /* Use default encoding if no name specified */
        if ( ! name )
                return &mime_encodings[0];
 
        /* Identify MIME encoding */
        for ( i = 0 ; i < ( sizeof ( mime_encodings ) /
                            sizeof ( mime_encodings[0] ) ) ; i++ ) {
                encoding = &mime_encodings[i];
                len = strlen ( encoding->name );
                if ( ( strncasecmp ( name, encoding->name, len ) == 0 ) &&
                     ( ( name[len] == ';' ) || isspace ( name[len] ) ) ) {
                        return encoding;
                }
        }
 
        return NULL;
}

References isspace(), len, mime_encodings, mime_encoding::name, name, NULL, strlen(), and strncasecmp().

Referenced by mime_extract_entity().

◆ mime_extract_entity()

int mime_extract_entity	(	struct image *	image,
		const struct mime_headers *	headers,
		struct image *	extracted )

static

Extract single MIME entity.

Parameters

image	MIME image
headers	MIME headers
extracted	Extracted image

Return values

rc	Return status code

Definition at line 352 of file mime.c.

                                                           {
        const struct mime_encoding *encoding;
        int rc;
 
        /* Identify encoding */
        encoding = mime_encoding ( headers->encoding );
        if ( ! encoding ) {
                DBGC ( image, "MIME %s has unrecognised encoding\n",
                       image->name );
                return -ENOTSUP;
        }
        DBGC ( image, "MIME %s has encoding %s\n",
               image->name, encoding->name );
 
        /* Decode via applicable encoding */
        if ( ( rc = encoding->decode ( image, headers, extracted ) ) != 0 )
                return rc;
 
        return 0;
}

References DBGC, mime_encoding::decode, ENOTSUP, headers, mime_encoding(), image::name, mime_encoding::name, and rc.

◆ mime_part_end()

const char * mime_part_end	(	struct image *	image,
		const struct mime_attribute *	boundary,
		const char *	pos )

static

Find end of current part in multipart MIME image.

Parameters

image	MIME image
boundary	Boundary separator
pos	Current position within image

Return values

end	End of current part, or NULL if not found

Definition at line 383 of file mime.c.

                                                      {
 
        /* Locate boundary marker */
        while ( 1 ) {
                pos = strstr ( pos, "\n--" );
                if ( ! pos )
                        break;
                pos += ( 1 /* newline */ );
                if ( strncmp ( ( pos + 2 /* -- */ ), boundary->value,
                               boundary->len ) != 0 ) {
                        continue;
                }
                return pos;
        }
 
        DBGC ( image, "MIME %s missing boundary marker\n", image->name );
        return NULL;
}

References DBGC, mime_attribute::len, image::name, NULL, strncmp(), strstr(), and mime_attribute::value.

Referenced by mime_extract_part().

◆ mime_part_next()

const char * mime_part_next	(	struct image *	image,
		const struct mime_attribute *	boundary,
		const char *	pos )

static

Find start of next part in multipart MIME image.

Parameters

image	MIME image
boundary	Boundary separator
pos	End of current part within image
next	Start of next part, or NULL if not found

Definition at line 412 of file mime.c.

                                                       {
 
        /* Skip boundary marker */
        pos += ( 2 /* -- */ + boundary->len );
 
        /* Check for end boundary */
        if ( strcmp ( pos, "--" ) == 0 )
                return NULL;
 
        /* Skip trailing whitespace */
        while ( ( *pos != '\n' ) && isspace ( *pos ) )
                pos++;
 
        /* Check for and skip terminating newline */
        if ( *pos != '\n' ) {
                DBGC ( image, "MIME %s malformed boundary marker\n",
                       image->name );
                return NULL;
        }
        pos++;
 
        return pos;
}

References DBGC, isspace(), mime_attribute::len, image::name, NULL, and strcmp().

Referenced by mime_extract_part().

◆ mime_extract_part()

int mime_extract_part	(	struct image *	image,
		const struct mime_headers *	headers,
		struct image *	extracted )

static

Extract part from multipart MIME image.

Parameters

image	MIME image
headers	MIME headers
extracted	Extracted image

Return values

rc	Return status code

Extraction will produce a MIME image containing only the selected part. (We rely on the recursive behaviour of image_extract_exec() to extract the content within the extracted part.)

Definition at line 450 of file mime.c.

                                                         {
        const struct mime_attribute *boundary = &headers->boundary;
        const struct mime_type *type;
        struct mime_headers subheaders;
        const char *part;
        const char *end;
        size_t len;
        int rc;
 
        /* Find end of preamble */
        end = mime_part_end ( image, boundary, image->text );
        if ( ! end )
                return -ENOENT;
 
        /* Look for a usable part */
        while ( ( part = mime_part_next ( image, boundary, end ) ) &&
                ( end = mime_part_end ( image, boundary, part ) ) ) {
 
                /* Parse part headers */
                DBGC ( image, "MIME %s found part at [%#zx,%#zx)\n",
                       image->name, ( part - image->text ),
                       ( end - image->text ) );
                if ( ( rc = mime_parse ( image, part, &subheaders ) ) != 0 )
                        return rc;
 
                /* Check for a recognised MIME type */
                type = mime_type ( subheaders.type );
                if ( ! type )
                        continue;
                DBGC ( image, "MIME %s found part with type %s\n",
                       image->name, type->name );
 
                /* Extract part */
                len = ( end - part );
                if ( ( rc = image_set_len ( extracted, len ) ) != 0 )
                        return rc;
                memcpy ( extracted->rwdata, part, len );
                return 0;
        }
 
        DBGC ( image, "MIME %s found no usable part\n", image->name );
        return -ENOENT;
}

References mime_headers::boundary, DBGC, end, ENOENT, headers, image_set_len(), len, memcpy(), mime_parse(), mime_part_end(), mime_part_next(), mime_type(), image::name, rc, image::rwdata, image::text, mime_headers::type, and type.

◆ mime_probe()

int mime_probe ( struct image * image )

static

Probe MIME image.

Parameters

image Compressed kernel image

Return values

rc	Return status code

Definition at line 502 of file mime.c.

                                              {
        struct mime_headers headers;
        int rc;
 
        /* Check for MIME headers */
        if ( ( rc = mime_parse ( image, image->text, &headers ) ) != 0 )
                return rc;
 
        return 0;
}

References headers, mime_parse(), rc, and image::text.

Referenced by __image_type().

◆ mime_extract()

int mime_extract	(	struct image *	image,
		struct image *	extracted )

static

Extract MIME image.

Parameters

image	Compressed kernel image
extracted	Extracted image

Return values

rc	Return status code

Definition at line 557 of file mime.c.

                                                                         {
        const struct mime_type *type;
        struct mime_headers headers;
        int rc;
 
        /* Parse headers */
        if ( ( rc = mime_parse ( image, image->text, &headers ) ) != 0 )
                return rc;
 
        /* Identify MIME type */
        type = mime_type ( headers.type );
        if ( ! type ) {
                DBGC ( image, "MIME %s has no type\n", image->name );
                return -ENOTSUP;
        }
        DBGC ( image, "MIME %s has type %s\n", image->name, type->name );
 
        /* Extract image */
        if ( ( rc = type->extract ( image, &headers, extracted ) ) != 0 )
                return rc;
 
        return 0;
}

References DBGC, ENOTSUP, headers, mime_parse(), mime_type(), image::name, rc, image::text, and type.

Referenced by __image_type().

◆ __image_type()

struct image_type mime_image_type __image_type ( PROBE_NORMAL )

MIME image type.

References __image_type, image_extract_exec(), mime_extract(), mime_probe(), and PROBE_NORMAL.

Variable Documentation

◆ mime_headers

const struct mime_header mime_headers[]

Initial value:

                        = {
        {
                .name = "Content-Type:",
                .parse = mime_parse_type,
 
        },
        {
                .name = "Content-Transfer-Encoding:",
                .parse = mime_parse_encoding,
        },
}

Recognised MIME headers.

Definition at line 130 of file mime.c.

                                        {
        {
                .name = "Content-Type:",
                .parse = mime_parse_type,
 
        },
        {
                .name = "Content-Transfer-Encoding:",
                .parse = mime_parse_encoding,
        },
};

◆ mime_encodings

const struct mime_encoding mime_encodings[]

static

Initial value:

                                 = {
        {
                
                .name = "7bit",
                .decode = mime_decode_identity,
        },
        {
                .name = "8bit",
                .decode = mime_decode_identity,
        },
        {
                .name = "binary",
                .decode = mime_decode_identity,
        },
        {
                .name = "base64",
                .decode = mime_decode_base64,
        },
}

MIME encodings.

Definition at line 295 of file mime.c.

                                                   {
        {
                /* Default encoding */
                .name = "7bit",
                .decode = mime_decode_identity,
        },
        {
                .name = "8bit",
                .decode = mime_decode_identity,
        },
        {
                .name = "binary",
                .decode = mime_decode_identity,
        },
        {
                .name = "base64",
                .decode = mime_decode_base64,
        },
};

Referenced by mime_encoding().

◆ mime_types

const struct mime_type mime_types[]

static

Initial value:

                             = {
        {
                .name = "multipart/mixed",
                .extract = mime_extract_part,
        },
        {
                .name = "text/x-ipxe",
                .extract = mime_extract_entity,
        },
}

MIME types.

Definition at line 514 of file mime.c.

                                           {
        {
                .name = "multipart/mixed",
                .extract = mime_extract_part,
        },
        {
                .name = "text/x-ipxe",
                .extract = mime_extract_entity,
        },
};

Referenced by mime_type().

Functions

Variables

Detailed Description

Function Documentation

◆ FILE_LICENCE()

◆ mime_type()

◆ mime_parse_attribute()

◆ mime_parse_type()

◆ mime_parse_encoding()

◆ mime_header()

◆ mime_parse()

◆ mime_decode_identity()

◆ mime_decode_base64()

◆ mime_encoding()

◆ mime_extract_entity()

◆ mime_part_end()

◆ mime_part_next()

◆ mime_extract_part()

◆ mime_probe()

◆ mime_extract()

◆ __image_type()

Variable Documentation

◆ mime_headers

◆ mime_encodings

◆ mime_types