GcrParser

GcrParser — Parser for certificate and key files

Synopsis

#define             GCR_DATA_ERROR
enum                GcrDataError;
enum                GcrDataFormat;
struct              GcrParser;
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);

Object Hierarchy

  GObject
   +----GcrParser

Properties

  "parsed-attributes"        GckAttributes*        : Read
  "parsed-description"       gchar*                : Read
  "parsed-label"             gchar*                : Read

Signals

  "authenticate"                                   : Run Last
  "parsed"                                         : Run First

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;

A parser for parsing various types of files or data.


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);


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.

Property Details

The "parsed-attributes" property

  "parsed-attributes"        GckAttributes*        : Read

Get the attributes that make up the currently parsed item. This is generally only valid during a "parsed" signal.


The "parsed-description" property

  "parsed-description"       gchar*                : Read

The description of the type of the currently parsed item. This is generally only valid during a "parsed" signal.

Default value: ""


The "parsed-label" property

  "parsed-label"             gchar*                : Read

The label of the currently parsed item. This is generally only valid during a "parsed" signal.

Default value: ""

Signal Details

The "authenticate" signal

gboolean            user_function                      (GcrParser *count,
                                                        gpointer   Returns,
                                                        gpointer   user_data)      : Run Last

This signal is emitted when an item needs to be unlocked or decrypted before it can be parsed. The count argument specifies the number of times the signal has been emitted for a given item. This can be used to display a message saying the previous password was incorrect.

Typically the gcr_parser_add_password() function is called in response to this signal.

If FALSE is returned, then the authentication was not handled. If no handlers return TRUE then the item is not parsed and an error with the code GCR_ERROR_CANCELLED will be raised.

count :

The number of times this item has been authenticated.

user_data :

user data set when the signal handler was connected.

Returns :

Whether the authentication was handled.

The "parsed" signal

void                user_function                      (GcrParser *arg0,
                                                        gpointer   user_data)      : Run First

This signal is emitted when an item is sucessfully parsed. To access the information about the item use the gcr_parser_get_parsed_label(), gcr_parser_get_parsed_attributes() and gcr_parser_get_parsed_description() functions.

user_data :

user data set when the signal handler was connected.