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,
                                                         const guchar *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,
                                                         GcrDataFormat format);
void                gcr_parser_format_disable           (GcrParser *self,
                                                         GcrDataFormat format);
gboolean            gcr_parser_format_supported         (GcrParser *self,
                                                         GcrDataFormat format);
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);
const guchar *      gcr_parser_get_parsed_block         (GcrParser *self,
                                                         gsize *n_block);
GcrDataFormat       gcr_parser_get_parsed_format        (GcrParser *self);
                    GcrParsed;
GcrParsed *         gcr_parsed_ref                      (GcrParsed *parsed);
void                gcr_parsed_unref                    (gpointer parsed);
GckAttributes *     gcr_parsed_get_attributes           (GcrParsed *parsed);
const guchar *      gcr_parsed_get_data                 (GcrParsed *parsed,
                                                         gsize *n_data);
const gchar *       gcr_parsed_get_description          (GcrParsed *parsed);
GcrDataFormat       gcr_parsed_get_format               (GcrParsed *parsed);
const gchar *       gcr_parsed_get_label                (GcrParsed *parsed);
GcrParsed *         gcr_parser_get_parsed               (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 "authenticate" and "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 "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 ())

A domain for data errors with codes from GcrDataError


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_ALL = -1,
	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_SUBJECT_PUBLIC_KEY = 150,

	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_PKCS10 = 450,
	GCR_FORMAT_DER_SPKAC = 455,
	GCR_FORMAT_BASE64_SPKAC,

	GCR_FORMAT_DER_PKCS12 = 500,

	GCR_FORMAT_OPENSSH_PUBLIC = 600,

	GCR_FORMAT_OPENPGP_PACKET = 700,
	GCR_FORMAT_OPENPGP_ARMOR,

	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,
	GCR_FORMAT_PEM_PRIVATE_KEY,
	GCR_FORMAT_PEM_PKCS10,
} GcrDataFormat;

The various format identifiers.

GCR_FORMAT_ALL

Represents all the formats, when enabling or disabling

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_SUBJECT_PUBLIC_KEY

DER encoded SubjectPublicKeyInfo

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_PKCS10

DER encoded PKCS#10 certificate request file

GCR_FORMAT_DER_SPKAC

DER encoded SPKAC as generated by HTML5 keygen element

GCR_FORMAT_BASE64_SPKAC

OpenSSL style SPKAC data

GCR_FORMAT_DER_PKCS12

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

GCR_FORMAT_OPENSSH_PUBLIC

OpenSSH v1 or v2 public key

GCR_FORMAT_OPENPGP_PACKET

OpenPGP key packet(s)

GCR_FORMAT_OPENPGP_ARMOR

OpenPGP public or private key armor encoded data

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

GCR_FORMAT_PEM_PRIVATE_KEY

An OpenSSL style PEM file with a private key

GCR_FORMAT_PEM_PKCS10

An OpenSSL style PEM file containing PKCS#10

struct GcrParser

struct GcrParser;

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. [transfer full]

gcr_parser_parse_data ()

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

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

self :

The parser

data :

the data to parse. [array length=n_data]

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 "parsed" and "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 "parsed" and "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,
                                                         GcrDataFormat format);

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

self :

The parser

format :

The format identifier

gcr_parser_format_disable ()

void                gcr_parser_format_disable           (GcrParser *self,
                                                         GcrDataFormat format);

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

self :

The parser

format :

The format identifier

gcr_parser_format_supported ()

gboolean            gcr_parser_format_supported         (GcrParser *self,
                                                         GcrDataFormat format);

Check whether the given format is supported by the parser.

self :

The parser

format :

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 "authenticate" signal.

self :

The parser

password :

a password to try. [allow-none]

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 "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. [allow-none]

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 "parsed" signal.

self :

The parser

Returns :

the description for the current item; this is owned by the parser and should not be freed. [allow-none]

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 "parsed" signal.

self :

The parser

Returns :

the attributes for the current item, which are owned by the parser and should not be freed. [transfer none][allow-none]

gcr_parser_get_parsed_block ()

const guchar *      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 "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. [transfer none][array length=n_block][allow-none]

gcr_parser_get_parsed_format ()

GcrDataFormat       gcr_parser_get_parsed_format        (GcrParser *self);

Get the format of the raw data block that represents this parsed object. This corresponds with the data returned from gcr_parser_get_parsed_block().

This is only valid during the "parsed" signal.

self :

a parser

Returns :

the data format of the currently parsed item

GcrParsed

typedef struct _GcrParsed GcrParsed;

A parsed item parsed by a GcrParser.


gcr_parsed_ref ()

GcrParsed *         gcr_parsed_ref                      (GcrParsed *parsed);

Add a reference to a parsed item. An item may not be shared across threads until it has been referenced at least once.

parsed :

a parsed item

Returns :

the parsed item. [transfer full]

gcr_parsed_unref ()

void                gcr_parsed_unref                    (gpointer parsed);

Unreferences a parsed item which was referenced with gcr_parsed_ref()

parsed :

a parsed item

gcr_parsed_get_attributes ()

GckAttributes *     gcr_parsed_get_attributes           (GcrParsed *parsed);

Get the attributes which make up the parsed item.

parsed :

a parsed item

Returns :

the attributes for the item; these are owned by the parsed item and should not be freed. [transfer none][allow-none]

gcr_parsed_get_data ()

const guchar *      gcr_parsed_get_data                 (GcrParsed *parsed,
                                                         gsize *n_data);

Get the raw data block for the parsed item.

parsed :

a parsed item

n_data :

location to store size of returned data

Returns :

the raw data of the parsed item, or NULL. [transfer full][array length=n_data][allow-none]

gcr_parsed_get_description ()

const gchar *       gcr_parsed_get_description          (GcrParsed *parsed);

Get the descirption for a parsed item.

parsed :

a parsed item

Returns :

the description. [allow-none]

gcr_parsed_get_format ()

GcrDataFormat       gcr_parsed_get_format               (GcrParsed *parsed);

Get the format of the parsed item.

parsed :

a parsed item

Returns :

the data format of the item

gcr_parsed_get_label ()

const gchar *       gcr_parsed_get_label                (GcrParsed *parsed);

Get the label for the parsed item.

parsed :

a parsed item

Returns :

the label for the item. [allow-none]

gcr_parser_get_parsed ()

GcrParsed *         gcr_parser_get_parsed               (GcrParser *self);

Get the currently parsed item

self :

a parser

Returns :

the currently parsed item. [transfer none]

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 *self,
                                                        gint       count,
                                                        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.

self :

the parser

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 *self,
                                                        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.

self :

the parser

user_data :

user data set when the signal handler was connected.