GcrParser: Gcr Library Reference Manual

## GcrParser GcrParser — Parser for certificate and key files |

## Functions

#define | GCR_DATA_ERROR
GcrParser * | gcr_parser_new ()
gboolean | gcr_parser_parse_bytes ()
gboolean | gcr_parser_parse_data ()
gboolean | gcr_parser_parse_stream ()
void | gcr_parser_parse_stream_async ()
gboolean | gcr_parser_parse_stream_finish ()
void | gcr_parser_format_enable ()
void | gcr_parser_format_disable ()
gboolean | gcr_parser_format_supported ()
void | gcr_parser_add_password ()
const gchar * | gcr_parser_get_parsed_label ()
const gchar * | gcr_parser_get_parsed_description ()
GckAttributes * | gcr_parser_get_parsed_attributes ()
const guchar * | gcr_parser_get_parsed_block ()
GBytes * | gcr_parser_get_parsed_bytes ()
GcrDataFormat | gcr_parser_get_parsed_format ()
const gchar * | gcr_parser_get_filename ()
void | gcr_parser_set_filename ()
GcrParsed * | gcr_parsed_ref ()
void | gcr_parsed_unref ()
GckAttributes * | gcr_parsed_get_attributes ()
const guchar * | gcr_parsed_get_data ()
GBytes * | gcr_parsed_get_bytes ()
const gchar * | gcr_parsed_get_description ()
GcrDataFormat | gcr_parsed_get_format ()
const gchar * | gcr_parsed_get_label ()
GcrParsed * | gcr_parser_get_parsed ()
const gchar * | gcr_parsed_get_filename ()

## Properties

GckAttributes * | parsed-attributes | Read
gchar * | parsed-description | Read
gchar * | parsed-label | Read

## Signals

gboolean | authenticate | Run Last
void | parsed | Run First

## Types and Values

enum | GcrDataError
enum | GcrDataFormat
struct | GcrParser
struct | GcrParserClass
| GcrParsed

## 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