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

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

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

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