![]() |
![]() |
![]() |
Gcr Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#define GCR_DATA_ERROR enum GcrDataError; enum GcrDataFormat; struct GcrParser; 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
);
"parsed-attributes" GckAttributes* : Read "parsed-description" gchar* : Read "parsed-label" gchar* : Read
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.
#define GCR_DATA_ERROR (gcr_data_error_get_domain ())
The GError domain for data parsing errors.
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.
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.
Not a valid format | |
DER encoded private key | |
DER encoded RSA private key | |
DER encoded DSA private key | |
DER encoded X.509 certificate | |
DER encoded PKCS#7 container file which can contain certificates | |
DER encoded PKCS#8 file which can contain a key | |
Unencrypted DER encoded PKCS#8 file which can contain a key | |
Encrypted DER encoded PKCS#8 file which can contain a key | |
DER encoded PKCS#12 file which can contain certificates and/or keys | |
An OpenSSL style PEM file with unspecified contents | |
An OpenSSL style PEM file with a private RSA key | |
An OpenSSL style PEM file with a private DSA key | |
An OpenSSL style PEM file with an X.509 certificate | |
An OpenSSL style PEM file containing PKCS#7 | |
Unencrypted OpenSSL style PEM file containing PKCS#8 | |
Encrypted OpenSSL style PEM file containing PKCS#8 | |
An OpenSSL style PEM file containing PKCS#12 |
GcrParser * gcr_parser_new (void
);
Create a new GcrParser
Returns : |
A newly allocated GcrParser |
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.
|
The parser |
|
The data to parse |
|
The length of the data |
|
A location to raise an error on failure. |
Returns : |
Whether the data was parsed successfully or not. |
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.
|
The parser |
|
The input stream |
|
An optional cancellation object |
|
A location to raise an error on failure |
Returns : |
Whether the parsing completed successfully or not. |
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.
|
The parser |
|
The input stream |
|
An optional cancellation object |
|
Called when the operation result is ready. |
|
Data to pass to callback |
gboolean gcr_parser_parse_stream_finish (GcrParser *self
,GAsyncResult *result
,GError **error
);
Complete an operation to parse a stream.
|
The parser |
|
The operation result |
|
A location to raise an error on failure |
Returns : |
Whether the parsing completed successfully or not. |
void gcr_parser_format_disable (GcrParser *self
,gint format_id
);
Disable parsing of the given format. Use -1 to disable all the formats.
|
The parser |
|
The format identifier |
gboolean gcr_parser_format_supported (GcrParser *self
,gint format_id
);
Check whether the given format is supported by the parser.
|
The parser |
|
The format identifier |
Returns : |
Whether the format is supported. |
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.
|
The parser |
|
A password to try |
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.
|
The parser |
Returns : |
The label of the currently parsed item. The value is owned by the parser and should not be freed. |
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.
|
The parser |
Returns : |
The description for the current item. This is owned by the parser and should not be freed. |
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.
|
The parser |
Returns : |
The attributes for the current item. These are owned by the parser and should not be freed. |
"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.
"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: ""
"authenticate"
signalgboolean 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.
|
The number of times this item has been authenticated. |
|
user data set when the signal handler was connected. |
Returns : |
Whether the authentication was handled. |
"parsed"
signalvoid 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 set when the signal handler was connected. |