![]() |
![]() |
![]() |
Gcr Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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 |
struct GcrParser { GObject parent; };
A parser for parsing various types of files or data.
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 |
The parent class |
The default handler for the authenticate signal. | |
The default handler for the parsed signal. |
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_enable (GcrParser *self
,gint format_id
);
Enable parsing of the given format. Use -1 to enable all the formats.
|
The parser |
|
The format identifier |
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. |
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.
|
a parser |
|
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. |