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.

			Gcr Library Reference Manual
Top \| Description