GcrParser

GcrParser — Parser for certificate and key files

Synopsis

#define             GCR_DATA_ERROR
enum                GcrDataError;
enum                GcrDataFormat;
struct              GcrParser;
struct              GcrParserClass;
GcrParser *         gcr_parser_new                      (void);
gboolean            gcr_parser_parse_data               (GcrParser *self,
                                                         gconstpointer data,
                                                         gsize n_data,
                                                         GError **error);
gboolean            gcr_parser_parse_stream             (GcrParser *self,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gcr_parser_parse_stream_async       (GcrParser *self,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gcr_parser_parse_stream_finish      (GcrParser *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                gcr_parser_format_enable            (GcrParser *self,
                                                         gint format_id);
void                gcr_parser_format_disable           (GcrParser *self,
                                                         gint format_id);
gboolean            gcr_parser_format_supported         (GcrParser *self,
                                                         gint format_id);
void                gcr_parser_add_password             (GcrParser *self,
                                                         const gchar *password);
const gchar *       gcr_parser_get_parsed_label         (GcrParser *self);
const gchar *       gcr_parser_get_parsed_description   (GcrParser *self);
GckAttributes *     gcr_parser_get_parsed_attributes    (GcrParser *self);
gconstpointer       gcr_parser_get_parsed_block         (GcrParser *self,
                                                         gsize *n_block);

Description

A GcrParser can parse various certificate and key files such as OpenSSL PEM files, DER encoded certifictes, PKCS#8 keys and so on. Each various format is identified by a value in the GcrDataFormat enumeration.

In order to parse data, a new parser is created with gcr_parser_new() and then the GcrParser::authenticate and GcrParser::parsed signals should be connected to. Data is then fed to the parser via gcr_parser_parse_data() or gcr_parser_parse_stream().

During the GcrParsed::parsed signal the attributes that make up the currently parsed item can be retrieved using the gcr_parser_get_parsed_attributes() function.

Details

GCR_DATA_ERROR

#define             GCR_DATA_ERROR                    (gcr_data_error_get_domain ())

The GError domain for data parsing errors.


enum GcrDataError

typedef enum {
	GCR_ERROR_FAILURE = -1,
	GCR_ERROR_UNRECOGNIZED = 1,
	GCR_ERROR_CANCELLED = 2,
	GCR_ERROR_LOCKED = 3
} GcrDataError;

Values responding to error codes for parsing and serializing data.

GCR_ERROR_FAILURE

Failed to parse or serialize the data

GCR_ERROR_UNRECOGNIZED

The data was unrecognized or unsupported

GCR_ERROR_CANCELLED

The operation was cancelled

GCR_ERROR_LOCKED

The data was encrypted or locked and could not be unlocked.

enum GcrDataFormat

typedef enum {
	GCR_FORMAT_INVALID = 0,

	GCR_FORMAT_DER_PRIVATE_KEY = 100,
	GCR_FORMAT_DER_PRIVATE_KEY_RSA,
	GCR_FORMAT_DER_PRIVATE_KEY_DSA,

	GCR_FORMAT_DER_CERTIFICATE_X509 = 200,

	GCR_FORMAT_DER_PKCS7 = 300,

	GCR_FORMAT_DER_PKCS8 = 400,
	GCR_FORMAT_DER_PKCS8_PLAIN,
	GCR_FORMAT_DER_PKCS8_ENCRYPTED,

	GCR_FORMAT_DER_PKCS12 = 500,

	GCR_FORMAT_PEM = 1000,
	GCR_FORMAT_PEM_PRIVATE_KEY_RSA,
	GCR_FORMAT_PEM_PRIVATE_KEY_DSA,
	GCR_FORMAT_PEM_CERTIFICATE_X509,
	GCR_FORMAT_PEM_PKCS7,
	GCR_FORMAT_PEM_PKCS8_PLAIN,
	GCR_FORMAT_PEM_PKCS8_ENCRYPTED,
	GCR_FORMAT_PEM_PKCS12
} GcrDataFormat;

The various format identifiers.

GCR_FORMAT_INVALID

Not a valid format

GCR_FORMAT_DER_PRIVATE_KEY

DER encoded private key

GCR_FORMAT_DER_PRIVATE_KEY_RSA

DER encoded RSA private key

GCR_FORMAT_DER_PRIVATE_KEY_DSA

DER encoded DSA private key

GCR_FORMAT_DER_CERTIFICATE_X509

DER encoded X.509 certificate

GCR_FORMAT_DER_PKCS7

DER encoded PKCS#7 container file which can contain certificates

GCR_FORMAT_DER_PKCS8

DER encoded PKCS#8 file which can contain a key

GCR_FORMAT_DER_PKCS8_PLAIN

Unencrypted DER encoded PKCS#8 file which can contain a key

GCR_FORMAT_DER_PKCS8_ENCRYPTED

Encrypted DER encoded PKCS#8 file which can contain a key

GCR_FORMAT_DER_PKCS12

DER encoded PKCS#12 file which can contain certificates and/or keys

GCR_FORMAT_PEM

An OpenSSL style PEM file with unspecified contents

GCR_FORMAT_PEM_PRIVATE_KEY_RSA

An OpenSSL style PEM file with a private RSA key

GCR_FORMAT_PEM_PRIVATE_KEY_DSA

An OpenSSL style PEM file with a private DSA key

GCR_FORMAT_PEM_CERTIFICATE_X509

An OpenSSL style PEM file with an X.509 certificate

GCR_FORMAT_PEM_PKCS7

An OpenSSL style PEM file containing PKCS#7

GCR_FORMAT_PEM_PKCS8_PLAIN

Unencrypted OpenSSL style PEM file containing PKCS#8

GCR_FORMAT_PEM_PKCS8_ENCRYPTED

Encrypted OpenSSL style PEM file containing PKCS#8

GCR_FORMAT_PEM_PKCS12

An OpenSSL style PEM file containing PKCS#12

struct GcrParser

struct GcrParser {
	GObject parent;
};

A parser for parsing various types of files or data.


struct GcrParserClass

struct GcrParserClass {
	GObjectClass parent_class;

	/* signals --------------------------------------------------------- */

	/* A callback for each password needed */
	gboolean (*authenticate) (GcrParser *self, gint count);
	
	void     (*parsed) (GcrParser *self);
};

The class for GcrParser

GObjectClass parent_class;

The parent class

authenticate ()

The default handler for the authenticate signal.

parsed ()

The default handler for the parsed signal.

gcr_parser_new ()

GcrParser *         gcr_parser_new                      (void);

Create a new GcrParser

Returns :

A newly allocated GcrParser

gcr_parser_parse_data ()

gboolean            gcr_parser_parse_data               (GcrParser *self,
                                                         gconstpointer data,
                                                         gsize n_data,
                                                         GError **error);

Parse the data. The GcrParser::parsed and GcrParser::authenticate signals may fire during the parsing.

self :

The parser

data :

The data to parse

n_data :

The length of the data

error :

A location to raise an error on failure.

Returns :

Whether the data was parsed successfully or not.

gcr_parser_parse_stream ()

gboolean            gcr_parser_parse_stream             (GcrParser *self,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GError **error);

Parse items from the data in a GInputStream. This function may block while reading from the input stream. Use gcr_parser_parse_stream_async() for a non-blocking variant.

The GcrParser::parsed and GcrParser::authenticate signals may fire during the parsing.

self :

The parser

input :

The input stream

cancellable :

An optional cancellation object

error :

A location to raise an error on failure

Returns :

Whether the parsing completed successfully or not.

gcr_parser_parse_stream_async ()

void                gcr_parser_parse_stream_async       (GcrParser *self,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Parse items from the data in a GInputStream. This function completes asyncronously and doesn't block.

The GcrParser::parsed and GcrParser::authenticate signals may fire during the parsing.

self :

The parser

input :

The input stream

cancellable :

An optional cancellation object

callback :

Called when the operation result is ready.

user_data :

Data to pass to callback

gcr_parser_parse_stream_finish ()

gboolean            gcr_parser_parse_stream_finish      (GcrParser *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Complete an operation to parse a stream.

self :

The parser

result :

The operation result

error :

A location to raise an error on failure

Returns :

Whether the parsing completed successfully or not.

gcr_parser_format_enable ()

void                gcr_parser_format_enable            (GcrParser *self,
                                                         gint format_id);

Enable parsing of the given format. Use -1 to enable all the formats.

self :

The parser

format_id :

The format identifier

gcr_parser_format_disable ()

void                gcr_parser_format_disable           (GcrParser *self,
                                                         gint format_id);

Disable parsing of the given format. Use -1 to disable all the formats.

self :

The parser

format_id :

The format identifier

gcr_parser_format_supported ()

gboolean            gcr_parser_format_supported         (GcrParser *self,
                                                         gint format_id);

Check whether the given format is supported by the parser.

self :

The parser

format_id :

The format identifier

Returns :

Whether the format is supported.

gcr_parser_add_password ()

void                gcr_parser_add_password             (GcrParser *self,
                                                         const gchar *password);

Add a password to the set of passwords to try when parsing locked or encrypted items. This is usually called from the GcrParser::authenticate signal.

self :

The parser

password :

A password to try

gcr_parser_get_parsed_label ()

const gchar *       gcr_parser_get_parsed_label         (GcrParser *self);

Get the label of the currently parsed item. This is generally only valid during the GcrParser::parsed signal.

self :

The parser

Returns :

The label of the currently parsed item. The value is owned by the parser and should not be freed.

gcr_parser_get_parsed_description ()

const gchar *       gcr_parser_get_parsed_description   (GcrParser *self);

Get a description for the type of the currently parsed item. This is generally only valid during the GcrParser::parsed signal.

self :

The parser

Returns :

The description for the current item. This is owned by the parser and should not be freed.

gcr_parser_get_parsed_attributes ()

GckAttributes *     gcr_parser_get_parsed_attributes    (GcrParser *self);

Get the attributes which make up the currently parsed item. This is generally only valid during the GcrParser::parsed signal.

self :

The parser

Returns :

The attributes for the current item. These are owned by the parser and should not be freed.

gcr_parser_get_parsed_block ()

gconstpointer       gcr_parser_get_parsed_block         (GcrParser *self,
                                                         gsize *n_block);

Get the raw data block that represents this parsed object. This is only valid during the GcrParser::parsed signal.

self :

a parser

n_block :

a location to place the size of the block

Returns :

The raw data block of the currently parsed item. The value is owned by the parser and should not be freed.