GcrParser

GcrParser — Parser for certificate and key files

Types and Values

Object Hierarchy

    GObject
    ╰── GcrParser

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.

Functions

GCR_DATA_ERROR

#define             GCR_DATA_ERROR                    (gcr_data_error_get_domain ())

A domain for data errors with codes from GcrDataError


gcr_parser_new ()

GcrParser *
gcr_parser_new (void);

Create a new GcrParser

Returns

a newly allocated GcrParser.

[transfer full]


gcr_parser_parse_bytes ()

gboolean
gcr_parser_parse_bytes (GcrParser *self,
                        GBytes *data,
                        GError **error);

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

Parameters

self

The parser

 

data

the data to parse

 

error

A location to raise an error on failure.

 

Returns

Whether the data was parsed successfully or not.


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.

A copy of the data will be made. Use gcr_parser_parse_bytes() to avoid this.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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_bytes ()

GBytes *
gcr_parser_get_parsed_bytes (GcrParser *self);

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

Parameters

self

a parser

 

Returns

the raw data block of the currently parsed item.

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

Parameters

self

a parser

 

Returns

the data format of the currently parsed item


gcr_parser_get_filename ()

const gchar *
gcr_parser_get_filename (GcrParser *self);

Get the filename of the parser item.

Parameters

self

a parser item

 

Returns

the filename set on the parser, or NULL


gcr_parser_set_filename ()

void
gcr_parser_set_filename (GcrParser *self,
                         const gchar *filename);

Sets the filename of the parser item.

Parameters

self

a parser item

 

filename

a string of the filename of the parser item.

[allow-none]

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.

Parameters

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

Parameters

parsed

a parsed item

 

gcr_parsed_get_attributes ()

GckAttributes *
gcr_parsed_get_attributes (GcrParsed *parsed);

Get the attributes which make up the parsed item.

Parameters

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.

Parameters

parsed

a parsed item

 

n_data

location to store size of returned data

 

Returns

the raw data of the parsed item, or NULL.

[transfer none][array length=n_data][allow-none]


gcr_parsed_get_bytes ()

GBytes *
gcr_parsed_get_bytes (GcrParsed *parsed);

Get the raw data block for the parsed item.

Parameters

parsed

a parsed item

 

Returns

the raw data of the parsed item, or NULL.

[transfer none]


gcr_parsed_get_description ()

const gchar *
gcr_parsed_get_description (GcrParsed *parsed);

Get the descirption for a parsed item.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

self

a parser

 

Returns

the currently parsed item.

[transfer none]


gcr_parsed_get_filename ()

const gchar *
gcr_parsed_get_filename (GcrParsed *parsed);

Get the filename of the parsed item.

Parameters

parsed

a parsed item

 

Returns

the filename of the parsed item, or NULL.

[transfer none]

Types and Values

enum GcrDataError

Values responding to error codes for parsing and serializing data.

Members

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

The various format identifiers.

Members

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_PRIVATE_KEY_EC

DER encoded EC 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

 

GCR_FORMAT_PEM_PRIVATE_KEY_EC

An OpenSSL style PEM file with a private EC key

 

GCR_FORMAT_PEM_PUBLIC_KEY

An OpenSSL style PEM file containing a SubjectPublicKeyInfo

 

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

Members

GObjectClass parent_class;

The parent class

 

authenticate ()

The default handler for the authenticate signal.

 

parsed ()

The default handler for the parsed signal.

 

GcrParsed

typedef struct _GcrParsed GcrParsed;

A parsed item parsed by a GcrParser.

Property Details

The “parsed-attributes” property

  “parsed-attributes”        GckAttributes *

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

Flags: Read


The “parsed-description” property

  “parsed-description”       gchar *

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

Flags: Read

Default value: ""


The “parsed-label” property

  “parsed-label”             gchar *

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

Flags: Read

Default value: ""

Signal Details

The “authenticate” signal

gboolean
user_function (GcrParser *self,
               gint       count,
               gpointer   user_data)

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.

Parameters

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.

Flags: Run Last


The “parsed” signal

void
user_function (GcrParser *self,
               gpointer   user_data)

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.

Parameters

self

the parser

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First