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

### 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 GcrParser::parsed and GcrParser::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 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,
                                                             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 GcrParser::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 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. [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 GcrParser::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 GcrParser::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 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. [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 GcrParser::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 *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.