Cypher_Stack/libsecret
2
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libsecret.git synced 2024-12-21 12:18:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Port documentation to gi-docgen

Browse Source
This commit is contained in:
Maximiliano 2022-02-02 12:19:14 +00:00 committed by Dhanuka Warusadura
parent 1f06297713
commit 2c3a34cca4
42 changed files with 2402 additions and 2907 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -28,7 +28,6 @@ config.*
depcomp
install-sh
INSTALL
gtk-doc.make
libtool
ltmain.sh
Makefile

29
.gitlab-ci.yml
View File

@ -16,7 +16,7 @@ fedora:Werror:
- dnf install -y $DEPENDENCIES
- dbus-uuidgen --ensure
script:
- meson _build -Dwerror=true -Dc_args=-Wno-error=deprecated-declarations
- meson _build -Dwerror=true -Dc_args=-Wno-error=deprecated-declarations -Dgtk_doc=false
- meson compile -C _build
- eval `dbus-launch --sh-syntax`
- meson test -C _build
@ -35,7 +35,7 @@ fedora:asan:
- dnf install -y $DEPENDENCIES libasan
- dbus-uuidgen --ensure
script:
- meson _build -Dsanitize=address
- meson _build -Dsanitize=address -Dgtk_doc=false
- meson compile -C _build
- eval `dbus-launch --sh-syntax`
- meson test -C _build
@ -54,7 +54,7 @@ fedora:ubsan:
- dnf install -y $DEPENDENCIES libubsan
- dbus-uuidgen --ensure
script:
- meson _build -Dsanitize=undefined
- meson _build -Dsanitize=undefined -Dgtk_doc=false
- meson compile -C _build
- eval `dbus-launch --sh-syntax`
- meson test -C _build
@ -73,7 +73,7 @@ fedora-static-analyzers/test:
- dnf install -y $DEPENDENCIES clang-analyzer cppcheck
- dbus-uuidgen --ensure
script:
- meson _build
- meson _build -Dgtk_doc=false
- meson compile -C _build --ninja-args scan-build
- cppcheck --force -q $CPPCHECK_OPTIONS libsecret/ egg/ tool/
artifacts:
@ -92,7 +92,7 @@ fedora:coverage:
- dnf install -y $DEPENDENCIES lcov
- dbus-uuidgen --ensure
script:
- meson _build -Db_coverage=true -Dtpm2=true
- meson _build -Db_coverage=true -Dtpm2=true -Dgtk_doc=false
- meson compile -C _build
- eval `dbus-launch --sh-syntax`
- export XDG_CONFIG_HOME=$HOME/.config
@ -113,11 +113,30 @@ fedora:coverage:
# https://github.com/linux-test-project/lcov/issues/58
allow_failure: true
reference:
stage: build
image: fedora:35
before_script:
- dnf install -y $DEPENDENCIES gi-docgen gobject-introspection-devel libgcrypt-devel
variables:
MESON_ARGS: >-
-Dgtk_doc=true
-Dvapi=false
-Dmanpage=false
script:
- meson ${MESON_ARGS} _build
- ninja -C _build
- mv _build/docs/reference/libsecret/libsecret-1 _reference
artifacts:
paths:
- _reference
pages:
stage: deploy
script:
- mkdir public
- mv _build/meson-logs/coveragereport public/coverage
- mv _reference/* public/
artifacts:
when: on_success
paths:

5
README.md
View File

@ -9,6 +9,11 @@ methods so consumers do not have to call the low-level DBus methods.
The actual Secret Service API spec can be found at
https://specifications.freedesktop.org/secret-service/.
Documentation
--------
You can find the nighlt documentation at https://gnome.pages.gitlab.gnome.org/libsecret/.
Building
--------

251
docs/reference/libsecret/libsecret-c-examples.md Normal file
View File

@ -0,0 +1,251 @@
Title: C Examples
Slug: libsecret-c-example
# C Examples
## Define a password schema
Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:
```c
// in a header:
const SecretSchema * example_get_schema (void) G_GNUC_CONST;
#define EXAMPLE_SCHEMA example_get_schema ()
// in a .c file:
const SecretSchema *
example_get_schema (void)
{
static const SecretSchema the_schema = {
"org.example.Password", SECRET_SCHEMA_NONE,
{
{ "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
{ "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
{ "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
{ "NULL", 0 },
}
};
return &the_schema;
}
```
See the [other examples](#store-a-password) for how to use the schema.
## Store a password
Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.
These examples use the [example schema](#define-a-password-schema).
This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```c
static void
on_password_stored (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
secret_password_store_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* ... do something now that the password has been stored */
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_store (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT, "The label",
"the password", NULL, on_password_stored, NULL,
"number", 8,
"string", "eight",
"even", TRUE,
NULL);
```
This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.
```c
GError *error = NULL;
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_store_sync (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT,
"The label", "the password", NULL, &error,
"number", 9,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* ... do something now that the password has been stored */
}
```
## Lookup a password
Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.
These examples use the [example schema](#define-a-password-schema).
This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```c
static void
on_password_lookup (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
gchar *password = secret_password_lookup_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else if (password == NULL) {
/* password will be null, if no matching password found */
} else {
/* ... do something with the password */
secret_password_free (password);
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_lookup (EXAMPLE_SCHEMA, NULL, on_password_lookup, NULL,
"string", "nine",
"even", FALSE,
NULL);
```
This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.
```c
GError *error = NULL;
/* The attributes used to lookup the password should conform to the schema. */
gchar *password = secret_password_lookup_sync (EXAMPLE_SCHEMA, NULL, &error,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else if (password == NULL) {
/* password will be null, if no matching password found */
} else {
/* ... do something with the password */
secret_password_free (password);
}
```
## Remove a password
Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.
These examples use the [example schema](#define-a-password-schema).
This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```c
static void
on_password_cleared (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
gboolean removed = secret_password_clear_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* removed will be TRUE if a password was removed */
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_clear (EXAMPLE_SCHEMA, NULL, on_password_cleared, NULL,
"string", "nine",
"even", FALSE,
NULL);
```
This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.
```c
GError *error = NULL;
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
gboolean removed = secret_password_clear_sync (EXAMPLE_SCHEMA, NULL, &error,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* removed will be TRUE if a password was removed */
}
```

47
docs/reference/libsecret/libsecret-docs.sgml
View File

@ -1,47 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Libsecret Library Reference Manual</title>
<releaseinfo>
for libsecret &version;.
An online version of this documentation can be found at
<ulink role="online-location" url="https://developer.gnome.org/libsecret/unstable/">https://developer.gnome.org/libsecret/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<part id="simple">
<title>Simple API</title>
<xi:include href="xml/secret-password.xml"/>
<xi:include href="xml/secret-schema.xml"/>
</part>
<xi:include href="libsecret-examples.sgml"/>
<part id="complete">
<title>Complete API</title>
<xi:include href="xml/secret-service.xml"/>
<xi:include href="xml/secret-collection.xml"/>
<xi:include href="xml/secret-item.xml"/>
<xi:include href="xml/secret-retrievable.xml"/>
<xi:include href="xml/secret-value.xml"/>
<xi:include href="xml/secret-attributes.xml"/>
<xi:include href="xml/secret-prompt.xml"/>
<xi:include href="xml/secret-error.xml"/>
<xi:include href="xml/secret-paths.xml"/>
<xi:include href="xml/secret-version.xml"/>
</part>
<xi:include href="libsecret-using.sgml"/>
<xi:include href="libsecret-tpm2.sgml"/>
<xi:include href="xml/migrating-libgnome-keyring.xml"/>
<xi:include href="xml/annotation-glossary.xml">
<xi:fallback />
</xi:include>
</book>

785
docs/reference/libsecret/libsecret-examples.sgml
View File

@ -1,785 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<part id="examples">
<title>Examples</title>
<chapter id="c-examples">
<title>C examples</title>
<section id="c-schema-example">
<title>C example: Define a password schema</title>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:</para>
<informalexample><programlisting language="c"><![CDATA[
/* in a header: */
const SecretSchema * example_get_schema (void) G_GNUC_CONST;
#define EXAMPLE_SCHEMA example_get_schema ()
/* in a .c file: */
const SecretSchema *
example_get_schema (void)
{
static const SecretSchema the_schema = {
"org.example.Password", SECRET_SCHEMA_NONE,
{
{ "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
{ "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
{ "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
{ "NULL", 0 },
}
};
return &the_schema;
}
]]></programlisting></informalexample>
<para>See the <link linkend="c-store-example">other examples</link> for how
to use the schema.</para>
</section>
<section id="c-store-example">
<title>C example: Store a password</title>
<para>Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.</para>
<para>These examples use <link linkend="c-schema-example">the example
schema</link>.</para>
<para>This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="c"><![CDATA[
static void
on_password_stored (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
secret_password_store_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* ... do something now that the password has been stored */
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_store (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT, "The label",
"the password", NULL, on_password_stored, NULL,
"number", 8,
"string", "eight",
"even", TRUE,
NULL);
]]></programlisting></informalexample>
<para>This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="javascript"><![CDATA[
GError *error = NULL;
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_store_sync (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT,
"The label", "the password", NULL, &error,
"number", 9,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* ... do something now that the password has been stored */
}
]]></programlisting></informalexample>
</section>
<section id="c-lookup-example">
<title>C example: Lookup a password</title>
<para>Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.</para>
<para>These examples use <link linkend="c-schema-example">the example
schema</link>.</para>
<para>This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="javascript"><![CDATA[
static void
on_password_lookup (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
gchar *password = secret_password_lookup_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else if (password == NULL) {
/* password will be null, if no matching password found */
} else {
/* ... do something with the password */
secret_password_free (password);
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_lookup (EXAMPLE_SCHEMA, NULL, on_password_lookup, NULL,
"string", "nine",
"even", FALSE,
NULL);
]]></programlisting></informalexample>
<para>This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="c"><![CDATA[
GError *error = NULL;
/* The attributes used to lookup the password should conform to the schema. */
gchar *password = secret_password_lookup_sync (EXAMPLE_SCHEMA, NULL, &error,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else if (password == NULL) {
/* password will be null, if no matching password found */
} else {
/* ... do something with the password */
secret_password_free (password);
}
]]></programlisting></informalexample>
</section>
<section id="c-remove-example">
<title>C example: Remove a password</title>
<para>Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.</para>
<para>These examples use <link linkend="c-schema-example">the example
schema</link>.</para>
<para>This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="c"><![CDATA[
static void
on_password_cleared (GObject *source,
GAsyncResult *result,
gpointer unused)
{
GError *error = NULL;
gboolean removed = secret_password_clear_finish (result, &error);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* removed will be TRUE if a password was removed */
}
}
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
secret_password_clear (EXAMPLE_SCHEMA, NULL, on_password_cleared, NULL,
"string", "nine",
"even", FALSE,
NULL);
]]></programlisting></informalexample>
<para>This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="c"><![CDATA[
GError *error = NULL;
/*
* The variable argument list is the attributes used to later
* lookup the password. These attributes must conform to the schema.
*/
gboolean removed = secret_password_clear_sync (EXAMPLE_SCHEMA, NULL, &error,
"string", "nine",
"even", FALSE,
NULL);
if (error != NULL) {
/* ... handle the failure here */
g_error_free (error);
} else {
/* removed will be TRUE if a password was removed */
}
]]></programlisting></informalexample>
</section>
</chapter>
<chapter id="js-examples">
<title>Javascript examples</title>
<section id="js-schema-example">
<title>Javascript example: Define a password schema</title>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
/* This schema is usually defined once globally */
const EXAMPLE_SCHEMA = new Secret.Schema.new("org.example.Password",
Secret.SchemaFlags.NONE,
{
"number": Secret.SchemaAttributeType.INTEGER,
"string": Secret.SchemaAttributeType.STRING,
"even": Secret.SchemaAttributeType.BOOLEAN,
}
);
]]></programlisting></informalexample>
<para>See the <link linkend="js-store-example">other examples</link> for how
to use the schema.</para>
</section>
<section id="js-store-example">
<title>Javascript example: Store a password</title>
<para>Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.</para>
<para>These examples use <link linkend="js-schema-example">the example
schema</link>.</para>
<para>This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
function on_password_stored(source, result) {
Secret.password_store_finish(result);
/* ... do something now that the password has been stored */
}
/*
* The attributes used to later lookup the password. These
* attributes should conform to the schema.
*/
var attributes = {
"number": "8",
"string": "eight",
"even": "true"
};
Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null, on_password_stored);
]]></programlisting></informalexample>
<para>This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
/*
* The attributes used to later lookup the password. These
* attributes should conform to the schema.
*/
var attributes = {
"number": "9",
"string": "nine",
"even": "false"
};
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null);
]]></programlisting></informalexample>
</section>
<section id="js-lookup-example">
<title>Javascript example: Lookup a password</title>
<para>Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.</para>
<para>These examples use <link linkend="js-schema-example">the example
schema</link>.</para>
<para>This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
function on_password_lookup(source, result) {
var password = Secret.password_lookup_finish(result);
/* password will be null if no matching password found */
}
/* The attributes used to lookup the password should conform to the schema. */
Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
null, on_password_lookup);
]]></programlisting></informalexample>
<para>This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
/* The attributes used to lookup the password should conform to the schema. */
var password = Secret.password_lookup_sync(EXAMPLE_SCHEMA,
{ "number": "8", "even": "true" },
null);
/* password will be null, if no matching password found */
]]></programlisting></informalexample>
</section>
<section id="js-remove-example">
<title>Javascript example: Remove a password</title>
<para>Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.</para>
<para>These examples use <link linkend="js-schema-example">the example
schema</link>.</para>
<para>This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
function on_password_clear(source, result) {
var removed = Secret.password_clear_finish(result);
/* removed will be true if the password was removed */
}
/* The attributes used to lookup which password to remove should conform to the schema. */
Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
null, on_password_clear);
]]></programlisting></informalexample>
<para>This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="javascript"><![CDATA[
const Secret = imports.gi.Secret;
/* The attributes used to lookup which password to remove should conform to the schema. */
var removed = Secret.password_clear_sync(EXAMPLE_SCHEMA,
{ "number": "8", "even": "true" },
null);
/* removed will be true if the password was removed */
]]></programlisting></informalexample>
</section>
</chapter>
<chapter id="py-examples">
<title>Python examples</title>
<section id="py-schema-example">
<title>Python example: Define a password schema</title>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
EXAMPLE_SCHEMA = Secret.Schema.new("org.mock.type.Store",
Secret.SchemaFlags.NONE,
{
"number": Secret.SchemaAttributeType.INTEGER,
"string": Secret.SchemaAttributeType.STRING,
"even": Secret.SchemaAttributeType.BOOLEAN,
}
)
]]></programlisting></informalexample>
<para>See the <link linkend="py-store-example">other examples</link> for how
to use the schema.</para>
</section>
<section id="py-store-example">
<title>Python example: Store a password</title>
<para>Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.</para>
<para>These examples use <link linkend="py-schema-example">the example
schema</link>.</para>
<para>This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
def on_password_stored(source, result, unused):
Secret.password_store_finish(result)
# ... do something now that the password has been stored
# The attributes used to later lookup the password. These
# attributes should conform to the schema.
attributes = {
"number": "8",
"string": "eight",
"even": "true"
}
Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", None, on_password_stored)
]]></programlisting></informalexample>
<para>This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
# The attributes used to later lookup the password. These
# attributes should conform to the schema.
attributes = {
"number": "8",
"string": "eight",
"even": "true"
}
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", None)
]]></programlisting></informalexample>
</section>
<section id="py-lookup-example">
<title>Python example: Lookup a password</title>
<para>Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.</para>
<para>These examples use <link linkend="py-schema-example">the example
schema</link>.</para>
<para>This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
def on_password_lookup(source, result, unused):
password = Secret.password_lookup_finish(result)
# password will be null, if no matching password found
Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
None, on_password_lookup)
]]></programlisting></informalexample>
<para>This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
password = Secret.password_lookup_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
# password will be null, if no matching password found
]]></programlisting></informalexample>
</section>
<section id="py-remove-example">
<title>Python example: Remove a password</title>
<para>Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.</para>
<para>These examples use <link linkend="py-schema-example">the example
schema</link>.</para>
<para>This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
def on_password_clear(source, result, unused):
removed = Secret.password_clear_finish(result)
# removed will be true if the password was removed
Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
None, on_password_clear)
]]></programlisting></informalexample>
<para>This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="python"><![CDATA[
from gi.repository import Secret
removed = Secret.password_clear_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
# removed will be true if the password was removed
]]></programlisting></informalexample>
</section>
</chapter>
<chapter id="vala-examples">
<title>Vala examples</title>
<section id="vala-schema-example">
<title>Vala example: Define a password schema</title>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:</para>
<informalexample><programlisting language="vala"><![CDATA[
var example = new Secret.Schema ("org.example.Password", Secret.SchemaFlags.NONE,
"number", Secret.SchemaAttributeType.INTEGER,
"string", Secret.SchemaAttributeType.STRING,
"even", Secret.SchemaAttributeType.BOOLEAN);
]]></programlisting></informalexample>
<para>See the <link linkend="vala-store-example">other examples</link> for how
to use the schema.</para>
</section>
<section id="vala-store-example">
<title>Vala example: Store a password</title>
<para>Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.</para>
<para>These examples use <link linkend="vala-schema-example">the example
schema</link>.</para>
<para>This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="vala"><![CDATA[
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null, (obj, async_res) => {
bool res = Secret.password_store.end (async_res);
/* ... do something now that the password has been stored */
});
]]></programlisting></informalexample>
<para>If you are already inside of an async function, you can also
use the yield keyword:</para>
<informalexample><programlisting language="vala"><![CDATA[
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
bool res = yield Secret.password_storev (example_schema, attributes,
Secret.COLLECTION_DEFAULT, "The label",
"the password", null);
]]></programlisting></informalexample>
<para>If you would like to avoid creating a hash table for the
attributes you can just use the variadic version:</para>
<informalexample><programlisting language="vala"><![CDATA[
bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label",
"the password", null, "number", 8, "string", "eight",
"even", true);
]]></programlisting></informalexample>
<para>This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="vala"><![CDATA[
Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null,
"number", 9, "string", "nine", "even", false);
]]></programlisting></informalexample>
</section>
<section id="vala-lookup-example">
<title>Vala example: Lookup a password</title>
<para>Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.</para>
<para>These examples use <link linkend="vala-schema-example">the example
schema</link>.</para>
<para>This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="vala"><![CDATA[
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
string password = Secret.password_lookup.end (async_res);
});
]]></programlisting></informalexample>
<para>This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="vala"><![CDATA[
string password = Secret.password_lookup_sync (example_schema, attributes, null,
"number", 9, "string", "nine", "even", false);
/* password will be null, if no matching password found */
]]></programlisting></informalexample>
</section>
<section id="vala-remove-example">
<title>Vala example: Remove a password</title>
<para>Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.</para>
<para>Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.</para>
<para>These examples use <link linkend="vala-schema-example">the example
schema</link>.</para>
<para>This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.</para>
<informalexample><programlisting language="vala"><![CDATA[
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_clearv.begin (example_schema, attributes, null, (obj, async_res) => {
bool removed = Secret.password_clearv.end (async_res);
});
]]></programlisting></informalexample>
<para>This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.</para>
<informalexample><programlisting language="vala"><![CDATA[
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
bool removed = Secret.password_clear_sync (example_schema, null,
"number", 8, "string", "eight", "even", true);
/* removed will be true if the password was removed */
]]></programlisting></informalexample>
</section>
</chapter>
</part>

170
docs/reference/libsecret/libsecret-js-examples.md Normal file
View File

@ -0,0 +1,170 @@
Title: Javascript Examples
Slug: libsecret-js-example
# Javascript examples
## Define a password schema
Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:
```js
const Secret = imports.gi.Secret;
/* This schema is usually defined once globally */
const EXAMPLE_SCHEMA = new Secret.Schema.new("org.example.Password",
Secret.SchemaFlags.NONE,
{
"number": Secret.SchemaAttributeType.INTEGER,
"string": Secret.SchemaAttributeType.STRING,
"even": Secret.SchemaAttributeType.BOOLEAN,
}
);
```
See the [other examples](#store-a-password) for how
to use the schema.
## Store a password
Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.
These examples use the [example schema](#define-a-password-schema).
This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```js
const Secret = imports.gi.Secret;
function on_password_stored(source, result) {
Secret.password_store_finish(result);
/* ... do something now that the password has been stored */
}
/*
* The attributes used to later lookup the password. These
* attributes should conform to the schema.
*/
var attributes = {
"number": "8",
"string": "eight",
"even": "true"
};
Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null, on_password_stored);
```
This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.
```js
const Secret = imports.gi.Secret;
/*
* The attributes used to later lookup the password. These
* attributes should conform to the schema.
*/
var attributes = {
"number": "9",
"string": "nine",
"even": "false"
};
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null);
```
## Lookup a password
Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.
These examples use the [example schema](#define-a-password-schema).
This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```js
const Secret = imports.gi.Secret;
function on_password_lookup(source, result) {
var password = Secret.password_lookup_finish(result);
/* password will be null if no matching password found */
}
/* The attributes used to lookup the password should conform to the schema. */
Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
null, on_password_lookup);
```
This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.
```js
const Secret = imports.gi.Secret;
/* The attributes used to lookup the password should conform to the schema. */
var password = Secret.password_lookup_sync(EXAMPLE_SCHEMA,
{ "number": "8", "even": "true" },
null);
/* password will be null, if no matching password found */
```
## Remove a password
Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.
These examples use the [example schema](#define-a-password-schema).
This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```js
const Secret = imports.gi.Secret;
function on_password_clear(source, result) {
var removed = Secret.password_clear_finish(result);
/* removed will be true if the password was removed */
}
/* The attributes used to lookup which password to remove should conform to the schema. */
Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
null, on_password_clear);
```
This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.
```js
const Secret = imports.gi.Secret;
/* The attributes used to lookup which password to remove should conform to the schema. */
var removed = Secret.password_clear_sync(EXAMPLE_SCHEMA,
{ "number": "8", "even": "true" },
null);
/* removed will be true if the password was removed */
```

2
docs/reference/libsecret/libsecret-overrides.txt
View File

@ -1,2 +0,0 @@
# These are manually-edited to override or add declarations to those scanned
# from the header files.

152
docs/reference/libsecret/libsecret-python-examples.md Normal file
View File

@ -0,0 +1,152 @@
Title: Python Examples
Slug: libsecret-python-example
# Python examples
## Define a password schema
Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:
```python
from gi.repository import Secret
EXAMPLE_SCHEMA = Secret.Schema.new("org.mock.type.Store",
Secret.SchemaFlags.NONE,
{
"number": Secret.SchemaAttributeType.INTEGER,
"string": Secret.SchemaAttributeType.STRING,
"even": Secret.SchemaAttributeType.BOOLEAN,
}
)
```
See the [other examples](#store-a-password) for how
to use the schema.
## Store a password
Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.
These examples use the [example schema](#define-a-password-schema).
This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```python
from gi.repository import Secret
def on_password_stored(source, result, unused):
Secret.password_store_finish(result)
# ... do something now that the password has been stored
# The attributes used to later lookup the password. These
# attributes should conform to the schema.
attributes = {
"number": "8",
"string": "eight",
"even": "true"
}
Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", None, on_password_stored)
```
This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.
```python
from gi.repository import Secret
# The attributes used to later lookup the password. These
# attributes should conform to the schema.
attributes = {
"number": "8",
"string": "eight",
"even": "true"
}
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", None)
```
## Lookup a password
Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.
These examples use the [example schema](#define-a-password-schema).
This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```python
from gi.repository import Secret
def on_password_lookup(source, result, unused):
password = Secret.password_lookup_finish(result)
# password will be null, if no matching password found
Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
None, on_password_lookup)
```
This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.
```python
from gi.repository import Secret
password = Secret.password_lookup_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
# password will be null, if no matching password found
```
## Remove a password
Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.
These examples use the [example schema](#define-a-password-schema).
This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```python
from gi.repository import Secret
def on_password_clear(source, result, unused):
removed = Secret.password_clear_finish(result)
# removed will be true if the password was removed
Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
None, on_password_clear)
```
This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.
```python
from gi.repository import Secret
removed = Secret.password_clear_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
# removed will be true if the password was removed
```

389
docs/reference/libsecret/libsecret-sections.txt
View File

@ -1,389 +0,0 @@
<SECTION>
<FILE>secret-collection</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SecretCollection
SecretCollectionClass
SecretCollectionFlags
secret_collection_for_alias
secret_collection_for_alias_finish
secret_collection_for_alias_sync
secret_collection_load_items
secret_collection_load_items_finish
secret_collection_load_items_sync
secret_collection_create
secret_collection_create_finish
secret_collection_create_sync
secret_collection_search
secret_collection_search_finish
secret_collection_search_sync
secret_collection_delete
secret_collection_delete_finish
secret_collection_delete_sync
secret_collection_get_created
secret_collection_get_service
secret_collection_get_flags
secret_collection_get_items
secret_collection_get_label
secret_collection_set_label
secret_collection_set_label_finish
secret_collection_set_label_sync
secret_collection_get_locked
secret_collection_get_modified
secret_collection_refresh
<SUBSECTION Standard>
SECRET_COLLECTION
SECRET_COLLECTION_CLASS
SECRET_COLLECTION_GET_CLASS
SECRET_IS_COLLECTION
SECRET_IS_COLLECTION_CLASS
SECRET_TYPE_COLLECTION
SECRET_TYPE_COLLECTION_FLAGS
SecretCollectionPrivate
secret_collection_get_type
secret_collection_flags_get_type
SecretCollectionCreateFlags
SECRET_TYPE_COLLECTION_CREATE_FLAGS
secret_collection_create_flags_get_type
</SECTION>
<SECTION>
<FILE>secret-item</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SecretItem
SecretItemClass
SecretItemFlags
SecretItemCreateFlags
secret_item_create
secret_item_create_finish
secret_item_create_sync
secret_item_delete
secret_item_delete_finish
secret_item_delete_sync
secret_item_get_schema_name
secret_item_get_attributes
secret_item_set_attributes
secret_item_set_attributes_finish
secret_item_set_attributes_sync
secret_item_get_created
secret_item_get_label
secret_item_set_label
secret_item_set_label_finish
secret_item_set_label_sync
secret_item_get_flags
secret_item_get_locked
secret_item_get_modified
secret_item_get_service
secret_item_get_secret
secret_item_load_secret
secret_item_load_secret_finish
secret_item_load_secret_sync
secret_item_load_secrets
secret_item_load_secrets_finish
secret_item_load_secrets_sync
secret_item_set_secret
secret_item_set_secret_finish
secret_item_set_secret_sync
secret_item_refresh
<SUBSECTION Standard>
SECRET_IS_ITEM
SECRET_IS_ITEM_CLASS
SECRET_ITEM
SECRET_ITEM_CLASS
SECRET_ITEM_GET_CLASS
SECRET_TYPE_ITEM
SECRET_TYPE_ITEM_FLAGS
SecretItemPrivate
secret_item_get_type
secret_item_flags_get_type
SECRET_TYPE_ITEM_CREATE_FLAGS
secret_item_create_flags_get_type
</SECTION>
<SECTION>
<FILE>secret-error</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SECRET_ERROR
SecretError
<SUBSECTION Standard>
SECRET_TYPE_ERROR
secret_error_get_quark
secret_error_get_type
</SECTION>
<SECTION>
<FILE>secret-password</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SECRET_COLLECTION_DEFAULT
SECRET_COLLECTION_SESSION
secret_password_store
secret_password_storev
secret_password_store_finish
secret_password_store_sync
secret_password_storev_sync
secret_password_store_binary
secret_password_store_binary_sync
secret_password_storev_binary
secret_password_storev_binary_sync
secret_password_lookup
secret_password_lookupv
secret_password_lookup_finish
secret_password_lookup_nonpageable_finish
secret_password_lookup_sync
secret_password_lookup_nonpageable_sync
secret_password_lookupv_sync
secret_password_lookupv_nonpageable_sync
secret_password_lookup_binary_finish
secret_password_lookup_binary_sync
secret_password_lookupv_binary_sync
secret_password_clear
secret_password_clearv
secret_password_clear_finish
secret_password_clear_sync
secret_password_clearv_sync
secret_password_search
secret_password_search_finish
secret_password_search_sync
secret_password_searchv
secret_password_searchv_sync
secret_password_wipe
secret_password_free
</SECTION>
<SECTION>
<FILE>secret-retrievable</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SECRET_TYPE_RETRIEVABLE
SecretRetrievable
SecretRetrievableInterface
secret_retrievable_get_attributes
secret_retrievable_get_created
secret_retrievable_get_label
secret_retrievable_get_modified
secret_retrievable_retrieve_secret
secret_retrievable_retrieve_secret_finish
secret_retrievable_retrieve_secret_sync
</SECTION>
<SECTION>
<FILE>secret-schema</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SECRET_SCHEMA_NOTE
SECRET_SCHEMA_COMPAT_NETWORK
SecretSchema
SecretSchemaFlags
SecretSchemaAttribute
SecretSchemaAttributeType
secret_schema_new
secret_schema_newv
secret_schema_ref
secret_schema_unref
SecretSchemaType
secret_get_schema
<SUBSECTION Standard>
secret_schema_get_type
secret_schema_attribute_get_type
secret_schema_attribute_type_get_type
secret_schema_flags_get_type
SECRET_TYPE_SCHEMA_FLAGS
SECRET_TYPE_SCHEMA_ATTRIBUTE_TYPE
</SECTION>
<SECTION>
<FILE>secret-prompt</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SecretPrompt
SecretPromptClass
secret_prompt_perform
secret_prompt_perform_finish
secret_prompt_perform_sync
secret_prompt_run
<SUBSECTION Standard>
SECRET_IS_PROMPT
SECRET_IS_PROMPT_CLASS
SECRET_PROMPT
SECRET_PROMPT_CLASS
SECRET_PROMPT_GET_CLASS
SECRET_TYPE_PROMPT
SecretPromptPrivate
secret_prompt_get_type
</SECTION>
<SECTION>
<FILE>secret-service</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SecretService
SecretServiceClass
SecretServiceFlags
secret_service_get
secret_service_get_sync
secret_service_get_finish
secret_service_disconnect
secret_service_open
secret_service_open_finish
secret_service_open_sync
secret_service_get_collections
secret_service_get_flags
secret_service_get_session_algorithms
secret_service_ensure_session
secret_service_ensure_session_finish
secret_service_ensure_session_sync
secret_service_load_collections
secret_service_load_collections_finish
secret_service_load_collections_sync
SecretSearchFlags
secret_service_search
secret_service_search_finish
secret_service_search_sync
secret_service_lock
secret_service_lock_finish
secret_service_lock_sync
secret_service_unlock
secret_service_unlock_finish
secret_service_unlock_sync
secret_service_store
secret_service_store_finish
secret_service_store_sync
secret_service_lookup
secret_service_lookup_finish
secret_service_lookup_sync
secret_service_clear
secret_service_clear_finish
secret_service_clear_sync
secret_service_prompt
secret_service_prompt_finish
secret_service_prompt_sync
secret_service_set_alias
secret_service_set_alias_finish
secret_service_set_alias_sync
secret_service_get_collection_gtype
secret_service_get_item_gtype
<SUBSECTION Standard>
SECRET_IS_SERVICE
SECRET_IS_SERVICE_CLASS
SECRET_SERVICE
SECRET_SERVICE_CLASS
SECRET_SERVICE_GET_CLASS
SECRET_TYPE_SEARCH_FLAGS
SECRET_TYPE_SERVICE
SECRET_TYPE_SERVICE_FLAGS
SecretServicePrivate
secret_search_flags_get_type
secret_service_flags_get_type
secret_service_get_type
</SECTION>
<SECTION>
<FILE>secret-paths</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
secret_collection_new_for_dbus_path
secret_collection_new_for_dbus_path_finish
secret_collection_new_for_dbus_path_sync
secret_item_new_for_dbus_path
secret_item_new_for_dbus_path_finish
secret_item_new_for_dbus_path_sync
secret_service_get_session_dbus_path
secret_service_search_for_dbus_paths
secret_service_search_for_dbus_paths_finish
secret_service_search_for_dbus_paths_sync
secret_collection_search_for_dbus_paths
secret_collection_search_for_dbus_paths_finish
secret_collection_search_for_dbus_paths_sync
secret_service_get_secrets_for_dbus_paths
secret_service_get_secrets_for_dbus_paths_finish
secret_service_get_secrets_for_dbus_paths_sync
secret_service_get_secret_for_dbus_path
secret_service_get_secret_for_dbus_path_finish
secret_service_get_secret_for_dbus_path_sync
secret_service_lock_dbus_paths
secret_service_lock_dbus_paths_finish
secret_service_lock_dbus_paths_sync
secret_service_unlock_dbus_paths
secret_service_unlock_dbus_paths_finish
secret_service_unlock_dbus_paths_sync
secret_service_prompt_at_dbus_path
secret_service_prompt_at_dbus_path_finish
secret_service_prompt_at_dbus_path_sync
secret_service_create_collection_dbus_path
secret_service_create_collection_dbus_path_finish
secret_service_create_collection_dbus_path_sync
secret_service_create_item_dbus_path
secret_service_create_item_dbus_path_finish
secret_service_create_item_dbus_path_sync
secret_service_delete_item_dbus_path
secret_service_delete_item_dbus_path_finish
secret_service_delete_item_dbus_path_sync
secret_service_read_alias_dbus_path
secret_service_read_alias_dbus_path_finish
secret_service_read_alias_dbus_path_sync
secret_service_set_alias_to_dbus_path
secret_service_set_alias_to_dbus_path_finish
secret_service_set_alias_to_dbus_path_sync
secret_service_encode_dbus_secret
secret_service_decode_dbus_secret
</SECTION>
<SECTION>
<FILE>secret-value</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
SecretValue
secret_value_new
secret_value_new_full
secret_value_get
secret_value_get_text
secret_value_get_content_type
secret_value_ref
secret_value_unref
secret_value_unref_to_password
<SUBSECTION Standard>
SECRET_TYPE_VALUE
secret_value_get_type
</SECTION>
<SECTION>
<FILE>secret-attributes</FILE>
<INCLUDE>libsecret/secret.h</INCLUDE>
secret_attributes_build
secret_attributes_buildv
</SECTION>
<SECTION>
<FILE>SecretGenService</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenCollection</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenItem</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenSession</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenPrompt</FILE>
</SECTION>
<SECTION>
<FILE>secret-backend</FILE>
SECRET_BACKEND_EXTENSION_POINT_NAME
SECRET_TYPE_BACKEND
SECRET_TYPE_BACKEND_FLAGS
SECRET_TYPE_SCHEMA_TYPE
SecretBackend
SecretBackendFlags
SecretBackendInterface
secret_backend_flags_get_type
secret_backend_get
secret_backend_get_finish
</SECTION>
<SECTION>
<FILE>secret-version</FILE>
SECRET_CHECK_VERSION
SECRET_MAJOR_VERSION
SECRET_MICRO_VERSION
SECRET_MINOR_VERSION
</SECTION>

95
docs/reference/libsecret/libsecret-simple-api.md Normal file
View File

@ -0,0 +1,95 @@
Title: Simple API
Slug: libsecret-simple-api
# Simple API
## SecretPassword
Simple password storage and lookup.
This is a simple API for storing passwords and retrieving passwords in the
Secret Service.
Each password is associated with a set of attributes. Attribute values can be
either strings, integers or booleans.
The names and types of allowed attributes for a given password are defined with
a schema. Certain schemas are predefined. Additional schemas can be defined via
the [struct@Schema] structure.
Each of the functions accept a variable list of attributes names and their
values. Include a `NULL` to terminate the list of attributes.
## SecretSchema
Represents a set of attributes that are stored with an item. These schemas are
used for interoperability between various services storing the same types of
items.
Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
set of attributes, and types (string, integer, boolean) for those attributes.
Attributes are stored as strings in the Secret Service, and the attribute types
simply define standard ways to store integer and boolean values as strings.
Attributes are represented in libsecret via a [struct@GLib.HashTable] with
string keys and values. Even for values that defined as an integer or boolean in
the schema, the attribute values in the [struct@GLib.HashTable] are strings.
Boolean values are stored as the strings 'true' and 'false'. Integer values are
stored in decimal, with a preceding negative sign for negative integers.
Schemas are handled entirely on the client side by this library. The name of the
schema is automatically stored as an attribute on the item.
Normally when looking up passwords only those with matching schema names are
returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
then lookups will not check that the schema name matches that on the item, only
the schema's attributes are matched. This is useful when you are looking up
items that are not stored by the libsecret library. Other libraries such as
libgnome-keyring don't store the schema name.
Additional schemas can be defined via the %SecretSchema structure like this:
```c
// in a header:
const SecretSchema * example_get_schema (void) G_GNUC_CONST;
#define EXAMPLE_SCHEMA example_get_schema ()
// in a .c file
const SecretSchema *
example_get_schema (void)
{
static const SecretSchema the_schema = {
"org.example.Password", SECRET_SCHEMA_NONE,
{
{ "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
{ "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
{ "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
{ NULL, 0 },
}
};
return &the_schema;
}
```
## Secret Attributes
Each item has a set of attributes, which are used to locate the item later.
These are not stored or transferred in a secure manner. Each attribute has a
string name and a string value. These attributes are represented by a
[struct@GLib.HashTable] with string keys and values.
Use [func@attributes_build] to simply build up a set of attributes.
## DBus Path Related Functions
Secret Service functions which operate on DBus object paths
These are low level functions which operate on DBus object paths of collections
or items, instead of the [class@Collection] or [class@Item] objects themselves.
You can use these functions if you wish to manage access to the secret service
using the DBus API directly, and only wish to use a few calls in libsecret.

69
docs/reference/libsecret/libsecret-tpm2.md Normal file
View File

@ -0,0 +1,69 @@
Title: Extending file backend to use a TPM
Slug: libsecret-tpm2
# Extending file backend to use a TPM
## Introduction
The current implementation of file backend uses an encryption key derived from
the user's login password. Security wise this not an ideal situation. Because,
the entire security of the file backend relies on the user's login password
(single point of failure). This situation can be improved if the keys are
protected/generated by hardware. A Trusted Platform Module (TPM) is a such
hardware security module found in modern computer systems.
The new `EGG_TPM2` API based on the "TSS Enhanced System API (ESAPI)"
```c
EggTpm2Context *egg_tpm2_initialize (GError **);
void egg_tpm2_finalize (EggTpm2Context *);
GBytes *egg_tpm2_generate_master_password (EggTpm2Context *,
GError **);
GBytes *egg_tpm2_decrypt_master_password (EggTpm2Context *,
GBytes *,
GError **);
```
## Build and test libsecret with TPM2 support
In order to try out the `TPM2 support` use the `-Dtpm2=true` build option/flag
during the `meson _build` process.
You can alter the default build and install process as the following:
```sh
meson _build -Dtpm2=true
ninja -C _build
ninja -C _build install
```
For testing the TPM2 support you need a physical TPM or a TPM emulator. The
following sections demonstrate how to setup
[swtpm](https://github.com/stefanberger/swtpm) emulator and testing out the TPM2
support. If you have access to a TPM you can ignore the emulator section.
swtpm emulator setup:
```sh
dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel
eval `dbus-launch --sh-syntax`
export XDG_CONFIG_HOME=$HOME/.config/swtpm
/usr/share/swtpm/swtpm-create-user-config-files --root
mkdir -p ${XDG_CONFIG_HOME}/mytpm1
swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display
swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon
tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all &amp;
export TCTI=tabrmd:bus_type=session
```
Test TPM2 support:
```sh
cd libsecret
meson _build -Dtpm2=true
ninja -C _build
export SECRET_BACKEND=file
export SECRET_FILE_TEST_PATH=$PWD/keyring
./_build/tool/secret-tool store --label=foo bar baz
ls # keyring
```

67
docs/reference/libsecret/libsecret-tpm2.sgml
View File

@ -1,67 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<part>
<title>Extending file backend to use a TPM</title>
<chapter>
<title>Introduction</title>
<para>The current implementation of file backend uses an encryption key derived from the user's login password. Security wise this not an ideal situation. Because, the entire security of the file backend relies on the user's login password (single point of failure). This situation can be improved if the keys are protected/generated by hardware. A Trusted Platform Module (TPM) is a such hardware security module found in modern computer systems.</para>
<para>The new <application>EGG_TPM2 API</application> based on the <application>TSS Enhanced System API (ESAPI)</application></para>
<informalexample><programlisting>
EggTpm2Context *egg_tpm2_initialize (GError **);
void egg_tpm2_finalize (EggTpm2Context *);
GBytes *egg_tpm2_generate_master_password (EggTpm2Context *,
GError **);
GBytes *egg_tpm2_decrypt_master_password (EggTpm2Context *,
GBytes *,
GError **);
</programlisting></informalexample>
</chapter>
<chapter>
<title>Build and test libsecret with TPM2 support</title>
<para>In order to try out the <application>TPM2 support</application> use the <literal>-Dtpm2=true</literal> build option/flag during the <literal>meson _build</literal> process.</para>
<para>You can alter the default build and install process as the following:</para>
<informalexample><programlisting>
$ meson _build -Dtpm2=true
$ ninja -C _build
$ ninja -C _build install
</programlisting></informalexample>
<para>For testing the TPM2 support you need a physical TPM or a TPM emulator. The following sections demonstrate how to setup <ulink url="https://github.com/stefanberger/swtpm">swtpm</ulink> emulator and testing out the TPM2 support. If you have access to a TPM you can ignore the emulator section.</para>
<para>swtpm emulator setup:</para>
<informalexample><programlisting>
$ dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel
$ eval `dbus-launch --sh-syntax`
$ export XDG_CONFIG_HOME=$HOME/.config/swtpm
$ /usr/share/swtpm/swtpm-create-user-config-files --root
$ mkdir -p ${XDG_CONFIG_HOME}/mytpm1
$ swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display
$ swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon
$ tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all &amp;
$ export TCTI=tabrmd:bus_type=session
</programlisting></informalexample>
<para>Test TPM2 support:</para>
<informalexample><programlisting>
$ cd libsecret
$ meson _build -Dtpm2=true
$ ninja -C _build
$ export SECRET_BACKEND=file
$ export SECRET_FILE_TEST_PATH=$PWD/keyring
$ ./_build/tool/secret-tool store --label=foo bar baz
$ ls # keyring
</programlisting></informalexample>
</chapter>
</part>

80
docs/reference/libsecret/libsecret-using.md Normal file
View File

@ -0,0 +1,80 @@
Title: Using libsecret
Slug: libsecret-using
# Using libsecret in builds or scripts
## C: Compiling with libsecret
Like other GNOME libraries, libsecret uses `pkg-config` to provide compiler
options. The package name is `libsecret-1`. So in your `configure.ac` script,you
might specify something like:
```
PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
```
Code using libsecret should include the header like this:
```c
#include <libsecret/secret.h>;
```
Including individual headers besides the main header files is not permitted and
will cause an error.
Some parts of the libsecret API are not yet stable. To use them you need use the
`libsecret-unstable` package. The API contained in this package will change from
time to time. Here's how you would do it:
```
PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
```
## Javascript: Importing libsecret
In Javascript use the standard introspection import mechanism to get at
libsecret:
```js
const Secret = imports.gi.Secret;
// ... and here's a sample line of code which uses the import
var schema = new Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
```
## Python: Importing libsecret
In python use the standard introspection import mechanism to get at libsecret:
```python
from gi.repository import Secret
# ... and a here's sample line of code which uses the import
schema = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
```
## Vala: Compiling with libsecret
The package name is `libsecret-1`. You can use it like
this in your `Makefile.am` file:
```
AM_VALAFLAGS = \
--pkg=libsecret-1
```
Some parts of the libsecret API are not yet stable.
To use them you need to define the `SECRET_WITH_UNSTABLE` C preprocessor
macro to use them, or else the build will fail:
```
AM_CPPFLAGS = \
-DSECRET_WITH_UNSTABLE=1
```

112
docs/reference/libsecret/libsecret-using.sgml
View File

@ -1,112 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<part id="using">
<title>Using libsecret in builds or scripts</title>
<chapter id="using-c">
<title>C: Compiling with libsecret</title>
<para>Like other GNOME libraries, <application>libsecret</application> uses
<application>pkg-config</application> to provide compiler options. The package
name is "<literal>libsecret-1</literal>". So in your
<literal>configure.ac</literal> script,you might specify something like:</para>
<informalexample><programlisting>
PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
</programlisting></informalexample>
<para>
Code using <application>libsecret</application> should include the header like this:
</para>
<informalexample><programlisting>
#include &lt;libsecret/secret.h&gt;
</programlisting></informalexample>
<para>
Including individual headers besides the main header files is not
permitted and will cause an error.
</para>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
To use them you need use the <literal>libsecret-unstable</literal> package.
The API contained in this package will change from time to time. Here's how
you would do it:
</para>
<informalexample><programlisting>
PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
</programlisting></informalexample>
</chapter>
<chapter id="using-js">
<title>Javascript: Importing libsecret</title>
<para>
In javascript use the standard introspection import mechanism to get at
<application>libsecret</application>:
</para>
<informalexample><programlisting language="javascript">
const Secret = imports.gi.Secret;
// ... and here's a sample line of code which uses the import
var schema = new Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
</programlisting></informalexample>
</chapter>
<chapter id="using-python">
<title>Python: Importing libsecret</title>
<para>
In python use the standard introspection import mechanism to get at
<application>libsecret</application>:
</para>
<informalexample><programlisting language="py">
from gi.repository import Secret
# ... and a here's sample line of code which uses the import
schema = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
</programlisting></informalexample>
</chapter>
<chapter id="using-vala">
<title>Vala: Compiling with libsecret</title>
<para>
The package name is "<literal>libsecret-1</literal>". You can use it like
this in your <literal>Makefile.am</literal> file:
</para>
<informalexample><programlisting>
AM_VALAFLAGS = \
--pkg=libsecret-1
</programlisting></informalexample>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
To use them you need to define the SECRET_WITH_UNSTABLE C preprocessor
macro to use them, or else the build will fail:
</para>
<informalexample><programlisting>
AM_CPPFLAGS = \
-DSECRET_WITH_UNSTABLE=1
</programlisting></informalexample>
</chapter>
</part>

157
docs/reference/libsecret/libsecret-vala-examples.md Normal file
View File

@ -0,0 +1,157 @@
Title: Vala Examples
Slug: libsecret-vala-example
# Vala Examples
## Define a password schema
Each stored password has a set of attributes which are later
used to lookup the password. The names and types of the attributes
are defined in a schema. The schema is usually defined once globally.
Here's how to define a schema:
```vala
var example = new Secret.Schema ("org.example.Password", Secret.SchemaFlags.NONE,
"number", Secret.SchemaAttributeType.INTEGER,
"string", Secret.SchemaAttributeType.STRING,
"even", Secret.SchemaAttributeType.BOOLEAN);
```
See the [other examples](#store-a-password) for how
to use the schema.
## Store a password
Here's how to store a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are later
used to lookup the password. The attributes should not contain
secrets, as they are not stored in an encrypted fashion.
These examples use the [example schema](#define-a-password-schema).
This first example stores a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```vala
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null, (obj, async_res) => {
bool res = Secret.password_store.end (async_res);
/* ... do something now that the password has been stored */
});
```
If you are already inside of an async function, you can also
use the yield keyword:
```vala
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
bool res = yield Secret.password_storev (example_schema, attributes,
Secret.COLLECTION_DEFAULT, "The label",
"the password", null);
```
If you would like to avoid creating a hash table for the
attributes you can just use the variadic version:
```vala
bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label",
"the password", null, "number", 8, "string", "eight",
"even", true);
```
This next example stores a password synchronously. The function
call will block until the password is stored. So this is appropriate for
non GUI applications.
```vala
Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT,
"The label", "the password", null,
"number", 9, "string", "nine", "even", false);
```
## Lookup a password
Here's how to lookup a password in the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to lookup the password. If multiple passwords match the
lookup attributes, then the one stored most recently is returned.
These examples use the [example schema](#define-a-password-schema).
This first example looks up a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```vala
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
string password = Secret.password_lookup.end (async_res);
});
```
This next example looks up a password synchronously. The function
call will block until the lookup completes. So this is appropriate for
non GUI applications.
```vala
string password = Secret.password_lookup_sync (example_schema, attributes, null,
"number", 9, "string", "nine", "even", false);
/* password will be null, if no matching password found */
```
## Remove a password
Here's how to remove a password from the running secret service,
like gnome-keyring or ksecretservice.
Each stored password has a set of attributes which are
used to find which password to remove. If multiple passwords match the
attributes, then the one stored most recently is removed.
These examples use the [example schema](#define-a-password-schema).
This first example removes a password asynchronously, and is
appropriate for GUI applications so that the UI does not block.
```vala
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
Secret.password_clearv.begin (example_schema, attributes, null, (obj, async_res) => {
bool removed = Secret.password_clearv.end (async_res);
});
```
This next example removes a password synchronously. The function
call will block until the removal completes. So this is appropriate for
non GUI applications.
```vala
var attributes = new GLib.HashTable<string,string> ();
attributes["number"] = "8";
attributes["string"] = "eight";
attributes["even"] = "true";
bool removed = Secret.password_clear_sync (example_schema, null,
"number", 8, "string", "eight", "even", true);
/* removed will be true if the password was removed */
```

52
docs/reference/libsecret/libsecret.toml.in Normal file
View File

@ -0,0 +1,52 @@
[library]
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/libsecret"
repository_url = "https://gitlab.gnome.org/GNOME/libsecret.git"
docs_url = "https://gnome.pages.gitlab.gnome.org/libsecret/"
website_url = "https://gnome.pages.gitlab.gnome.org/libsecret/"
authors = "Stef Walter, Daiki Ueno, and Niels De Graef"
license = "LGPL-2.1-or-later"
description = "Secret Service D-Bus client library"
dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base type system library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."Gio-2.0"]
name = "GIO"
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master"
[extra]
# The same order will be used when generating the index
content_files = [
'libsecret-using.md',
'libsecret-simple-api.md',
"libsecret-c-examples.md",
"libsecret-js-examples.md",
"libsecret-python-examples.md",
"libsecret-vala-examples.md",
"libsecret-tpm2.md",
"migrating-libgnome-keyring.md",
]
content_images = [
]
urlmap_file = "urlmap.js"

7
docs/reference/libsecret/libsecret.types
View File

@ -1,7 +0,0 @@
secret_collection_get_type
secret_error_get_type
secret_item_get_type
secret_prompt_get_type
secret_value_get_type
secret_service_flags_get_type
secret_service_get_type

71
docs/reference/libsecret/meson.build
View File

@ -1,39 +1,48 @@
reference_content_files = [
'libsecret-examples.sgml',
'libsecret-using.sgml',
'libsecret-tpm2.sgml',
'migrating-libgnome-keyring.xml',
expand_content_md_files = [
'libsecret-c-examples.md',
'libsecret-js-examples.md',
'libsecret-python-examples.md',
'libsecret-simple-api.md',
'libsecret-tpm2.md',
'libsecret-using.md',
'libsecret-vala-examples.md',
'migrating-libgnome-keyring.md',
]
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
reference_expanded_content_files = [
'migrating-libgnome-keyring.xml',
]
toml_data = configuration_data()
toml_data.set('VERSION', meson.project_version())
reference_ignore_headers = [
'mock-service.h',
'secret-dbus-generated.h',
'secret-private.h',
]
configure_file(
input: 'version.xml.in',
output: '@BASENAME@',
configuration: {'VERSION': meson.project_version()},
libsecret_toml = configure_file(
input: 'libsecret.toml.in',
output: 'libsecret.toml',
configuration: toml_data
)
gnome.gtkdoc('libsecret',
main_sgml: 'libsecret-docs.sgml',
content_files: reference_content_files,
src_dir: include_directories('../../../libsecret'),
dependencies: libsecret_dep,
gobject_typesfile: 'libsecret.types',
mkdb_args: '--expand-content-files=' + ' '.join(reference_expanded_content_files),
scan_args: [
'--deprecated-guards=SECRET_DISABLE_DEPRECATED',
'--rebuild-types',
'--ignore-headers=' + ' '.join(reference_ignore_headers),
dependency('gi-docgen', version: '>= 2021.7',
fallback: ['gi-docgen', 'dummy_dep'],
native: true,
required: get_option('gtk_doc'))
gidocgen = find_program('gi-docgen')
docs_dir = get_option('datadir') / 'doc'
custom_target('libsecret-doc',
input: [ libsecret_toml, libsecret_gir[0] ],
output: 'libsecret-@0@'.format(api_version_major),
command: [
gidocgen,
'generate',
'--quiet',
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../libsecret'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--no-namespace-dir',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
module_version: api_version_major,
depend_files: [ expand_content_md_files ],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

823
docs/reference/libsecret/migrating-libgnome-keyring.md Normal file
View File

@ -0,0 +1,823 @@
Title: Migrating from libgnome-keyring
Slug: migrating-libgnome-keyring
# Migrating from libgnome-keyring
## Introduction
Conceptually, libgnome-keyring and libsecret are fairly similar. Both
have keyrings, items, and ways to store and retrieve passwords. In both
cases items have attributes. The keys and values of attributes are used
to lookup a password that was stored.
There is a
<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
which is the easiest and recommended way to store passwords. And then
there is a more complicated API which models all the various collections
and items, along with all the possible actions that can be performed on them.
libsecret uses the
<ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink>
to communicate with gnome-keyring-daemon, and as such exposes features
based on that DBus API.
libsecret has been designed to be threadsafe, and uses the 'GDBus'
code in gio to accomplish this.
Keyrings are called 'collections' in libsecret.
See the relevant section for specifics about how to port the
libgnome-keyring functions or symbols in your project.
## API conversion
Here are some clues on how to migrate various libgnome-keyring
API functions and their logical equivalents in libsecret.
### Item attributes
Remember that attributes are not, and never have been stored in
an encrypted fashion. They are not part of the 'secret', but instead
are a way to lookup a secret item.
All attributes in libsecret are stored as strings. Sets of attributes
are represented by [struct@GLib.HashTable]s and the keys and values of
these hash tables are strings.
libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>,
and encourages users to define a [struct@Schema] for their password storage.
The schema defines which attributes are allowed an item. Each schema has
a name which is usually a dotted string (eg: `org.gnome.MyProject.Password`).
This schema name is stored internally in the item attributes.
Schemas define whether an attribute should look like an integer,
a boolean, or a free-form string. These types are used when validating
the attribute values, even though the attribute values are stored and
matched as strings. Since attribute values are used primarily
for lookup of items it's important that the string representations of
integers and booleans are always identical. Boolean values are stored
as the strings `true` and `false`.
Integer values are stored in decimal, with a preceding negative sign
for negative integers. libsecret facilitates this using the
[func@attributes_build] and [func@attributes_buildv] functions.
Attributes are meant to be used for lookup of items; they're not
designed to be used as a generic key/value database. Although you can
force libsecret to do the latter, it's better to store your account
information elsewhere if possible, and use libsecret to store the password
or other secret.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td>GnomeKeyringAttributeList</td>
<td>a [struct@GLib.HashTable] of string keys and values</td>
</tr>
<tr>
<td>GnomeKeyringAttribute</td>
<td>a key/value pair in a [struct@GLib.HashTable] of strings</td>
</tr>
<tr>
<td>GnomeKeyringAttributeType</td>
<td>[struct@Schema]AttributeType</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</code></td>
<td><code>SECRET_SCHEMA_ATTRIBUTE_STRING</code></td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</code></td>
<td><code>SECRET_SCHEMA_ATTRIBUTE_INTEGER</code></td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_index()</code></td>
<td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_get_string()</code></td>
<td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_get_uint32()</code></td>
<td>no equivalent, use [func@GLib.HashTable.lookup]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_append_string()</code></td>
<td>[func@attributes_build]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_append_uint32()</code></td>
<td>[func@attributes_build]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_copy()</code></td>
<td>[func@GLib.HashTable.ref]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_free()</code></td>
<td>[func@GLib.HashTable.unref]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_index()</code></td>
<td>no equivalent, use [func@GLib.HashTable.lookup]</td>
</tr>
<tr>
<td><code>gnome_keyring_attribute_list_new()</code></td>
<td>[func@attributes_build]</td>
</tr>
</table>
## Working with schemas
libsecret is far more focused on schemas, and encourages users to
define a [struct@Schema] for their password storage. The schema defines
which attributes are allowed an item. Each schema has a name which
is usually a dotted string (eg: `org.gnome.MyProject.Password`).
This name is stored in the item attributes. The schema name is also
used when looking up an item, to make sure that the stored schema
matches that used during the lookup. If you wish to lookup items that
were stored by libgnome-keyring, you should specify the
`SECRET_SCHEMA_DONT_MATCH_NAME` flag in the schema so that the schema
name is not matched, since it was not stored by libgnome-keyring.
Schemas define whether an attribute should look like an integer,
a boolean, or a free-form string. These types are used when validating
the attribute values stored, even though the attribute values are
stored and matched as strings.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td>GnomeKeyringPasswordSchema</td>
<td>[struct@Schema]</td>
</tr>
<tr>
<td>GnomeKeyringPasswordSchemaAttribute</td>
<td>[struct@Schema]Attribute</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_APPLICATION_SECRET</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_PK_STORAGE</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_GENERIC_SECRET</code></td>
<td>no equivalent, define a specific schema with an appropriate dotted name</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</code></td>
<td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_NOTE</code></td>
<td>the <code>SECRET_SCHEMA_NOTE</code> schema</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_NETWORK_PASSWORD</code></td>
<td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
</tr>
</table>
## Storing passwords and items
It's encouraged to use a [struct@Schema] when storing items and
passwords.
By default most ways of storing an item will now overwrite
another item with the same attributes in the same keyring. To manually
control this behavior use the [func@Item.create].
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>GNOME_KEYRING_DEFAULT</code></td>
<td>[const@COLLECTION_DEFAULT]</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_SESSION</code></td>
<td>[const@COLLECTION_SESSION]</td>
</tr>
<tr>
<td><code>gnome_keyring_store_password()</code></td>
<td>[func@password_store]</td>
</tr>
<tr>
<td><code>gnome_keyring_store_password_sync()</code></td>
<td>[func@password_store_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_set_network_password()</code></td>
<td>[func@password_store] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
although this is not recommended for new uses.</td>
</tr>
<tr>
<td><code>gnome_keyring_set_network_password_sync()</code></td>
<td>[func@password_store_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
although this is not recommended for new uses.</td>
</tr>
<tr>
<td><code>gnome_keyring_item_create()</code></td>
<td>[func@Item.create], although using [func@password_store]
is simpler.</td>
</tr>
<tr>
<td><code>gnome_keyring_item_create_sync()</code></td>
<td>[func@Item.create], although using [func@password_store_sync]
is simpler.</td>
</tr>
</table>
## Searching for passwords and items
In general libsecret tries not to unlocking keyrings
where not necessary. Many search methods only return one item or
password that matches, preferring already unlocked items, and recently stored
items.
Attributes are meant to be used for lookup of items; they're not
designed to be used as a generic key/value database. Although you can
force libsecret to do the latter, it's better to store your account
information elsewhere if possible, and use libsecret to store the password
or other secret. Because of this many search methods return just the
password or secret.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_find_password()</code></td>
<td>[func@password_lookup]</td>
</tr>
<tr>
<td><code>gnome_keyring_find_password_sync()</code></td>
<td>[func@password_lookup_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_find_items()</code></td>
<td>[method@Service.search], with flags to fine tune behavior</td>
</tr>
<tr>
<td><code>gnome_keyring_find_itemsv()</code></td>
<td>[method@Service.search], with flags to fine tune behavior</td>
</tr>
<tr>
<td><code>gnome_keyring_find_items_sync()</code></td>
<td>[method@Service.search_sync], with flags to fine tune behavior</td>
</tr>
<tr>
<td><code>gnome_keyring_find_itemsv_sync()</code></td>
<td>[method@Service.search], with flags to fine tune behavior</td>
</tr>
<tr>
<td>GnomeKeyringFound</td>
<td>no equivalent, [method@Service.search] returns a [struct@GLib.List] of
[class@Item]<!-- -->s, and other methods return passwords directly.</td>
</tr>
<tr>
<td><code>gnome_keyring_found_copy()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_found_free()</code></td>
<td>[method@GObject.Object.unref] on the each of the items returned from
[method@Service.search]</td>
</tr>
<tr>
<td><code>gnome_keyring_found_list_free()</code></td>
<td>[func@GLib.List.free_full] used with [method@GObject.Object.unref] on the items returned from
[method@Service.search]</td>
</tr>
<tr>
<td><code>gnome_keyring_find_network_password()</code></td>
<td>[func@password_lookup] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
although this only returns one password and no attributes</td>
</tr>
<tr>
<td><code>gnome_keyring_find_network_password_sync()</code></td>
<td>[func@password_lookup_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
although this only returns one password and no attributes</td>
</tr>
<tr>
<td>GnomeKeyringNetworkPasswordData</td>
<td>no equivalent, [func@password_lookup] gets the password directly
and no attributes</td>
</tr>
<tr>
<td><code>gnome_keyring_network_password_free()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_network_password_list_free()</code></td>
<td>no equivalent</td>
</tr>
</table>
## Removing passwords and icons
Neither libgnome-keyring or libsecret allow deletion of locked
items. libsecret tries to make it easier to delete all unlocked items
matching certain attributes.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_delete_password()</code></td>
<td>[func@password_clear], although we now try to delete
all unlocked matching items</td>
</tr>
<tr>
<td><code>gnome_keyring_delete_password_sync()</code></td>
<td>[func@password_clear_sync], although we now try to delete
all unlocked matching items</td>
</tr>
<tr>
<td><code>gnome_keyring_item_delete()</code></td>
<td>[method@Item.delete]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_delete_sync()</code></td>
<td>[method@Item.delete_sync]</td>
</tr>
</table>
## Item management
In libsecret items are no longer identified by an unsigned integer.
Applications should retrieve items based on their attributes. It is also
possible to identify an item by its DBus object path.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_item_create()</code></td>
<td>[func@Item.create], although [func@password_store] may be simpler</td>
</tr>
<tr>
<td><code>gnome_keyring_item_create_sync()</code></td>
<td>[func@Item.create_sync], although [func@password_store_sync] may be simpler</td>
</tr>
<tr>
<td><code>gnome_keyring_item_delete()</code></td>
<td>[method@Item.delete], although [func@password_clear] may be simpler</td>
</tr>
<tr>
<td><code>gnome_keyring_item_delete_sync()</code></td>
<td>[method@Item.delete_sync], although [func@password_clear_sync] may be simpler</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_info()</code></td>
<td>properties are loaded on a [class@Item] automatically, use
[method@Item.load_secret] to load the secret</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_info_sync()</code></td>
<td>properties are loaded on a [class@Item] automatically, use
[method@Item.load_secret_sync] to load the secret</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_info_full()</code></td>
<td>properties are loaded on a [class@Item] automatically, use
[method@Item.load_secret] to load the secret</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_info_full_sync()</code></td>
<td>properties are loaded on a [class@Item] automatically, use
[method@Item.load_secret_sync] to load the secret</td>
</tr>
<tr>
<td><code>gnome_keyring_item_set_info()</code></td>
<td>use the appropriate setter methods on [class@Item]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_set_info_sync()</code></td>
<td>use the appropriate setter methods on [class@Item]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_attributes()</code></td>
<td>[method@Item.get_attributes]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_get_attributes_sync()</code></td>
<td>[method@Item.get_attributes]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_set_attributes()</code></td>
<td>[method@Item.set_attributes]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_set_attributes_sync()</code></td>
<td>[method@Item.set_attributes_sync]</td>
</tr>
<tr>
<td>GnomeKeyringItemType</td>
<td>replaced by the name of a [struct@Schema]</td>
</tr>
<tr>
<td>GnomeKeyringItemInfo</td>
<td>[class@Item]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_new()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_copy()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_free()</code></td>
<td>[method@GObject.Object.unref] on the [class@Item]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_get_display_name()</code></td>
<td>[method@Item.get_label]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_set_display_name()</code></td>
<td>[method@Item.set_label]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_get_ctime()</code></td>
<td>[method@Item.get_created]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_get_mtime()</code></td>
<td>[method@Item.get_modified]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_get_type()</code></td>
<td>[method@Item.get_schema_name]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_set_type()</code></td>
<td>[method@Item.set_attributes] with appropriate schema</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_get_secret()</code></td>
<td>[method@Item.get_secret]</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_set_secret()</code></td>
<td>[method@Item.set_secret] and [method@Item.set_secret_sync]</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_INFO_BASICS</code></td>
<td>no equivalent, all basic item properties are loaded on [class@Item]
automatically</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_ITEM_INFO_SECRET</code></td>
<td>use [method@Item.load_secret] and [method@Item.load_secret_sync] to load
the secret for an item.</td>
</tr>
<tr>
<td><code>gnome_keyring_item_info_set_display_name()</code></td>
<td></td>
</tr>
</table>
## Keyring management
In libsecret keyrings are called 'collections'. This is the same
lingo as the underlying Secret Service DBus API. Keyrings are no longer
identified by simple keyring names. Normally applications just use the
default keyrings and these are identified by the aliases
[const@COLLECTION_DEFAULT] and [const@COLLECTION_SESSION]. It is also
possible to identify collections by their DBus object paths.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_create()</code></td>
<td>[func@Collection.create]</td>
</tr>
<tr>
<td><code>gnome_keyring_create_sync()</code></td>
<td>[func@Collection.create_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_delete()</code></td>
<td>[method@Collection.delete]</td>
</tr>
<tr>
<td><code>gnome_keyring_delete_sync()</code></td>
<td>[method@Collection.delete_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_change_password()</code></td>
<td>no equivalent, use platform specific DBus APIs</td>
</tr>
<tr>
<td><code>gnome_keyring_change_password_sync()</code></td>
<td>no equivalent, use platform specific DBus APIs</td>
</tr>
<tr>
<td><code>gnome_keyring_list_keyring_names()</code></td>
<td>[method@Service.load_collections] and [method@Service.get_collections]</td>
</tr>
<tr>
<td><code>gnome_keyring_list_keyring_names_sync()</code></td>
<td>[method@Service.load_collections_sync] and [method@Service.get_collections]</td>
</tr>
<tr>
<td><code>gnome_keyring_set_default_keyring()</code></td>
<td>[method@Service.set_alias]</td>
</tr>
<tr>
<td><code>gnome_keyring_set_default_keyring_sync()</code></td>
<td>[method@Service.set_alias_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_get_default_keyring()</code></td>
<td>[func@Collection.for_alias] with [const@COLLECTION_DEFAULT]</td>
</tr>
<tr>
<td><code>gnome_keyring_get_default_keyring_sync()</code></td>
<td>[func@Collection.for_alias_sync] with [const@COLLECTION_DEFAULT]</td>
</tr>
<tr>
<td><code>gnome_keyring_list_item_ids()</code></td>
<td>[method@Collection.load_items] and [method@Collection.get_items]</td>
</tr>
<tr>
<td><code>gnome_keyring_list_item_ids_sync()</code></td>
<td>[method@Collection.load_items_sync] and [method@Collection.get_items]</td>
</tr>
<tr>
<td>GnomeKeyringInfo</td>
<td>[class@Collection] and properties</td>
</tr>
<tr>
<td><code>gnome_keyring_get_info()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_get_info_sync()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_set_info()</code></td>
<td>no equivalent, use property setters on [class@Collection]</td>
</tr>
<tr>
<td><code>gnome_keyring_set_info_sync()</code></td>
<td>no equivalent, use property setters on [class@Collection]</td>
</tr>
<tr>
<td><code>gnome_keyring_info_free()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_copy()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_set_lock_on_idle()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_get_lock_on_idle()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_set_lock_timeout()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_get_lock_timeout()</code></td>
<td>no equivalent</td>
</tr>
<tr>
<td><code>gnome_keyring_info_get_mtime()</code></td>
<td>[method@Collection.get_modified]</td>
</tr>
<tr>
<td><code>gnome_keyring_info_get_ctime()</code></td>
<td>[method@Collection.get_created]</td>
</tr>
<tr>
<td><code>gnome_keyring_info_get_is_locked()</code></td>
<td>[method@Collection.get_locked]</td>
</tr>
</table>
## Locking and unlocking
In libsecret you can unlock items directly, and the result is
(with gnome-keyring daemon) that the enclosing collection will be unlocked.
It is no longer possible to pass a password to unlock keyrings.
These are automatically prompted for.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_unlock()</code></td>
<td>[method@Service.unlock]</td>
</tr>
<tr>
<td><code>gnome_keyring_unlock_sync()</code></td>
<td>[method@Service.unlock_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_lock()</code></td>
<td>[method@Service.lock]</td>
</tr>
<tr>
<td><code>gnome_keyring_lock_sync()</code></td>
<td>[method@Service.lock_sync]</td>
</tr>
<tr>
<td><code>gnome_keyring_lock_all()</code></td>
<td>no equivalent, use platform specific DBus APIs</td>
</tr>
<tr>
<td><code>gnome_keyring_lock_all_sync()</code></td>
<td>no equivalent, use platform specific DBus APIs</td>
</tr>
</table>
## Non-pageable memory
libsecret no longer provides a full API for using non-pageable
memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.
You can request that passwords are returned in non-pageable
memory by using the [func@password_lookup_nonpageable_sync] and
[func@password_lookup_nonpageable_finish] functions.
In addition the contents of [struct@Value] items is stored in
non-pageable memory, unless the system doesn't support this.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_memory_alloc()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_free()</code></td>
<td>[func@password_free], although this only works on strings</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_is_secure()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_new()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_realloc()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_strdup()</code></td>
<td>no equivalent, use [struct@Value] which is ref-counted, or use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_try_alloc()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_memory_try_realloc()</code></td>
<td>no equivalent, use Gcr</td>
</tr>
<tr>
<td><code>gnome_keyring_free_password()</code></td>
<td>[func@password_free]</td>
</tr>
</table>
## Errors and cancellation
libsecret uses standard the standard [class@Gio.Cancellable] idiom
to cancel operations.
It is not necessary to check whether the keyring daemon is
available before using it. It is started automatically.
Errors are returned as standard [struct@GLib.Error] in the usual way.
There are fewer errors that are worth handling in an intelligent way,
exceptions are in the #SecretError enumeration. It is not recommended
to display any [struct@GLib.Error] message returned by libsecret to the user. Most
of the possible errors are DBus communication problems or similar.
Replacements for related libgnome-keyring functions and types
are described below:
<table>
<tr>
<th>libgnome-keyring</th><th>libsecret</th>
</tr>
<tr>
<td><code>gnome_keyring_cancel_request()</code></td>
<td>[method@Gio.Cancellable.cancel] on a [class@Gio.Cancellable] passed to the relevant operation</td>
</tr>
<tr>
<td><code>gnome_keyring_is_available()</code></td>
<td>no equivalent, the secret service is autostarted as necessary</td>
</tr>
<tr>
<td><code>gnome_keyring_result_to_message()</code></td>
<td>use the message in the [struct@GLib.Error], although most failures are not appropriate for display to the user</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_OK</code></td>
<td>no [struct@GLib.Error] returned</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_DENIED</code></td>
<td>no longer used, item or collection is simply not unlocked</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</code></td>
<td><code>G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</code></td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</code></td>
<td>no error, success returned</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</code></td>
<td>keyrings no longer have names, accessing an missing DBus object has usual failure</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_BAD_ARGUMENTS</code></td>
<td><code>G_DBUS_ERROR_INVALID_ARGS</code> or precondition failure in libsecret, this is always
a programmer error</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_IO_ERROR</code></td>
<td>relevant DBus errors, or <code>SECRET_ERROR_PROTOCOL</code></td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_CANCELLED</code></td>
<td><code>G_IO_ERROR_CANCELLED</code></td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</code></td>
<td>no error, simply returns already existing keyring</td>
</tr>
<tr>
<td><code>GNOME_KEYRING_RESULT_NO_MATCH</code></td>
<td>on error, an empty list is returned</td>
</tr>
<tr>
<td><code>gnome_keyring_string_list_free()</code></td>
<td>no equivalent</td>
</tr>
</table>

839
docs/reference/libsecret/migrating-libgnome-keyring.xml
View File

@ -1,839 +0,0 @@
<part id="migrating">
<title>Migrating from libgnome-keyring</title>
<chapter id="migrating-introduction">
<title>Introduction</title>
<para>Conceptually, libgnome-keyring and libsecret are fairly similar. Both
have keyrings, items, and ways to store and retrieve passwords. In both
cases items have attributes. The keys and values of attributes are used
to lookup a password that was stored.</para>
<para>There is a
<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
which is the easiest and recommended way to store passwords. And then
there is a more complicated API which models all the various collections
and items, along with all the possible actions that can be performed on them.</para>
<para>libsecret uses the
<ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink>
to communicate with gnome-keyring-daemon, and as such exposes features
based on that DBus API.</para>
<para>libsecret has been designed to be threadsafe, and uses the 'GDBus'
code in gio to accomplish this.</para>
<para>Keyrings are called 'collections' in libsecret.</para>
<para>See the relevant section for specifics about how to port the
libgnome-keyring functions or symbols in your project.</para>
</chapter>
<chapter id="migrating-api">
<title>API conversion</title>
<para>Here are some clues on how to migrate various libgnome-keyring
API functions and their logical equivalents in libsecret.</para>
<section id="migrating-attributes">
<title>Item attributes</title>
<para>Remember that attributes are not, and never have been stored in
an encrypted fashion. They are not part of the 'secret', but instead
are a way to lookup a secret item.</para>
<para>All attributes in libsecret are stored as strings. Sets of attributes
are represented by #GHashTable<!-- -->s and the keys and values of
these hash tables are strings.</para>
<para>libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>,
and encourages users to define a #SecretSchema for their password storage.
The schema defines which attributes are allowed an item. Each schema has
a name which is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>).
This schema name is stored internally in the item attributes.</para>
<para>Schemas define whether an attribute should look like an integer,
a boolean, or a free-form string. These types are used when validating
the attribute values, even though the attribute values are stored and
matched as strings. Since attribute values are used primarily
for lookup of items it's important that the string representations of
integers and booleans are always identical. Boolean values are stored
as the strings <literal>true</literal> and <literal>false</literal>.
Integer values are stored in decimal, with a preceding negative sign
for negative integers. libsecret facilitates this using the
secret_attributes_build() and secret_attributes_buildv() functions.</para>
<para>Attributes are meant to be used for lookup of items; they're not
designed to be used as a generic key/value database. Although you can
force libsecret to do the latter, it's better to store your account
information elsewhere if possible, and use libsecret to store the password
or other secret.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>#GnomeKeyringAttributeList</entry>
<entry>a #GHashTable of string keys and values</entry>
</row>
<row>
<entry>#GnomeKeyringAttribute</entry>
<entry>a key/value pair in a #GHashTable of strings</entry>
</row>
<row>
<entry>#GnomeKeyringAttributeType</entry>
<entry>#SecretSchemaAttributeType</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</entry>
<entry>%SECRET_SCHEMA_ATTRIBUTE_STRING</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</entry>
<entry>%SECRET_SCHEMA_ATTRIBUTE_INTEGER</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_index()</entry>
<entry>use g_hash_table_lookup() on the attributes hash table</entry>
</row>
<row>
<entry>gnome_keyring_attribute_get_string()</entry>
<entry>use g_hash_table_lookup() on the attributes hash table</entry>
</row>
<row>
<entry>gnome_keyring_attribute_get_uint32()</entry>
<entry>no equivalent, use g_hash_table_lookup()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_append_string()</entry>
<entry>secret_attributes_build()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_append_uint32()</entry>
<entry>secret_attributes_build()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_copy()</entry>
<entry>g_hash_table_ref()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_free()</entry>
<entry>g_hash_table_unref()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_index()</entry>
<entry>no equivalent, use g_hash_table_lookup()</entry>
</row>
<row>
<entry>gnome_keyring_attribute_list_new()</entry>
<entry>secret_attributes_build()</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-schemas">
<title>Working with schemas</title>
<para>libsecret is far more focused on schemas, and encourages users to
define a #SecretSchema for their password storage. The schema defines
which attributes are allowed an item. Each schema has a name which
is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>).
This name is stored in the item attributes. The schema name is also
used when looking up an item, to make sure that the stored schema
matches that used during the lookup. If you wish to lookup items that
were stored by libgnome-keyring, you should specify the
%SECRET_SCHEMA_DONT_MATCH_NAME flag in the schema so that the schema
name is not matched, since it was not stored by libgnome-keyring.</para>
<para>Schemas define whether an attribute should look like an integer,
a boolean, or a free-form string. These types are used when validating
the attribute values stored, even though the attribute values are
stored and matched as strings.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>#GnomeKeyringPasswordSchema</entry>
<entry>#SecretSchema</entry>
</row>
<row>
<entry>#GnomeKeyringPasswordSchemaAttribute</entry>
<entry>#SecretSchemaAttribute</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_APPLICATION_SECRET</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_PK_STORAGE</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_GENERIC_SECRET</entry>
<entry>no equivalent, define a specific schema with an appropriate dotted name</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_NETWORK_PASSWORD</entry>
<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_NOTE</entry>
<entry>the %SECRET_SCHEMA_NOTE schema</entry>
</row>
<row>
<entry>%GNOME_KEYRING_NETWORK_PASSWORD</entry>
<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-storing">
<title>Storing passwords and items</title>
<para>It's encouraged to use a #SecretSchema when storing items and
passwords.</para>
<para>By default most ways of storing an item will now overwrite
another item with the same attributes in the same keyring. To manually
control this behavior use the secret_item_create().</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>%GNOME_KEYRING_DEFAULT</entry>
<entry>%SECRET_COLLECTION_DEFAULT</entry>
</row>
<row>
<entry>%GNOME_KEYRING_SESSION</entry>
<entry>%SECRET_COLLECTION_SESSION</entry>
</row>
<row>
<entry>gnome_keyring_store_password()</entry>
<entry>secret_password_store()</entry>
</row>
<row>
<entry>gnome_keyring_store_password_sync()</entry>
<entry>secret_password_store_sync()</entry>
</row>
<row>
<entry>gnome_keyring_set_network_password()</entry>
<entry>secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK
although this is not recommended for new uses.</entry>
</row>
<row>
<entry>gnome_keyring_set_network_password_sync()</entry>
<entry>secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK
although this is not recommended for new uses.</entry>
</row>
<row>
<entry>gnome_keyring_item_create()</entry>
<entry>secret_item_create(), although using secret_password_store()
is simpler.</entry>
</row>
<row>
<entry>gnome_keyring_item_create_sync()</entry>
<entry>secret_item_create(), although using secret_password_store_sync()
is simpler.</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-searching">
<title>Searching for passwords and items</title>
<para>In general libsecret tries not to unlocking keyrings
where not necessary. Many search methods only return one item or
password that matches, preferring already unlocked items, and recently stored
items.</para>
<para>Attributes are meant to be used for lookup of items; they're not
designed to be used as a generic key/value database. Although you can
force libsecret to do the latter, it's better to store your account
information elsewhere if possible, and use libsecret to store the password
or other secret. Because of this many search methods return just the
password or secret.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_find_password()</entry>
<entry>secret_password_lookup()</entry>
</row>
<row>
<entry>gnome_keyring_find_password_sync()</entry>
<entry>secret_password_lookup_sync()</entry>
</row>
<row>
<entry>gnome_keyring_find_items()</entry>
<entry>secret_service_search(), with flags to fine tune behavior</entry>
</row>
<row>
<entry>gnome_keyring_find_itemsv()</entry>
<entry>secret_service_search(), with flags to fine tune behavior</entry>
</row>
<row>
<entry>gnome_keyring_find_items_sync()</entry>
<entry>secret_service_search_sync(), with flags to fine tune behavior</entry>
</row>
<row>
<entry>gnome_keyring_find_itemsv_sync()</entry>
<entry>secret_service_search(), with flags to fine tune behavior</entry>
</row>
<row>
<entry>GnomeKeyringFound</entry>
<entry>no equivalent, secret_service_search() returns a #GList of
#SecretItem<!-- -->s, and other methods return passwords directly.</entry>
</row>
<row>
<entry>gnome_keyring_found_copy()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_found_free()</entry>
<entry>g_object_unref() on the each of the items returned from
secret_service_search()</entry>
</row>
<row>
<entry>gnome_keyring_found_list_free()</entry>
<entry>g_list_free_full() used with g_object_unref() on the items returned from
secret_service_search()</entry>
</row>
<row>
<entry>gnome_keyring_find_network_password()</entry>
<entry>secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK,
although this only returns one password and no attributes</entry>
</row>
<row>
<entry>gnome_keyring_find_network_password_sync()</entry>
<entry>secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK,
although this only returns one password and no attributes</entry>
</row>
<row>
<entry>#GnomeKeyringNetworkPasswordData</entry>
<entry>no equivalent, secret_password_lookup() gets the password directly
and no attributes</entry>
</row>
<row>
<entry>gnome_keyring_network_password_free()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_network_password_list_free()</entry>
<entry>no equivalent</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-removing">
<title>Removing passwords and icons</title>
<para>Neither libgnome-keyring or libsecret allow deletion of locked
items. libsecret tries to make it easier to delete all unlocked items
matching certain attributes.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_delete_password()</entry>
<entry>secret_password_clear(), although we now try to delete
all unlocked matching items</entry>
</row>
<row>
<entry>gnome_keyring_delete_password_sync()</entry>
<entry>secret_password_clear_sync(), although we now try to delete
all unlocked matching items</entry>
</row>
<row>
<entry>gnome_keyring_item_delete()</entry>
<entry>secret_item_delete()</entry>
</row>
<row>
<entry>gnome_keyring_item_delete_sync()</entry>
<entry>secret_item_delete_sync()</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-items">
<title>Item management</title>
<para>In libsecret items are no longer identified by an unsigned integer.
Applications should retrieve items based on their attributes. It is also
possible to identify an item by its DBus object path.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_item_create()</entry>
<entry>secret_item_create(), although secret_password_store() may be simpler</entry>
</row>
<row>
<entry>gnome_keyring_item_create_sync()</entry>
<entry>secret_item_create_sync(), although secret_password_store_sync() may be simpler</entry>
</row>
<row>
<entry>gnome_keyring_item_delete()</entry>
<entry>secret_item_delete(), although secret_password_clear() may be simpler</entry>
</row>
<row>
<entry>gnome_keyring_item_delete_sync()</entry>
<entry>secret_item_delete_sync(), although secret_password_clear_sync() may be simpler</entry>
</row>
<row>
<entry>gnome_keyring_item_get_info()</entry>
<entry>properties are loaded on a #SecretItem automatically, use
secret_item_load_secret() to load the secret</entry>
</row>
<row>
<entry>gnome_keyring_item_get_info_sync()</entry>
<entry>properties are loaded on a #SecretItem automatically, use
secret_item_load_secret_sync() to load the secret</entry>
</row>
<row>
<entry>gnome_keyring_item_get_info_full()</entry>
<entry>properties are loaded on a #SecretItem automatically, use
secret_item_load_secret() to load the secret</entry>
</row>
<row>
<entry>gnome_keyring_item_get_info_full_sync()</entry>
<entry>properties are loaded on a #SecretItem automatically, use
secret_item_load_secret_sync() to load the secret</entry>
</row>
<row>
<entry>gnome_keyring_item_set_info()</entry>
<entry>use the appropriate setter methods on #SecretItem</entry>
</row>
<row>
<entry>gnome_keyring_item_set_info_sync()</entry>
<entry>use the appropriate setter methods on #SecretItem</entry>
</row>
<row>
<entry>gnome_keyring_item_get_attributes()</entry>
<entry>secret_item_get_attributes()</entry>
</row>
<row>
<entry>gnome_keyring_item_get_attributes_sync()</entry>
<entry>secret_item_get_attributes()</entry>
</row>
<row>
<entry>gnome_keyring_item_set_attributes()</entry>
<entry>secret_item_set_attributes()</entry>
</row>
<row>
<entry>gnome_keyring_item_set_attributes_sync()</entry>
<entry>secret_item_set_attributes_sync()</entry>
</row>
<row>
<entry>#GnomeKeyringItemType</entry>
<entry>replaced by the name of a #SecretSchema</entry>
</row>
<row>
<entry>#GnomeKeyringItemInfo</entry>
<entry>#SecretItem</entry>
</row>
<row>
<entry>gnome_keyring_item_info_new()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_item_info_copy()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_item_info_free()</entry>
<entry>g_object_unref() on the #SecretItem</entry>
</row>
<row>
<entry>gnome_keyring_item_info_get_display_name()</entry>
<entry>secret_item_get_label()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_set_display_name()</entry>
<entry>secret_item_set_label()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_get_ctime()</entry>
<entry>secret_item_get_created()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_get_mtime()</entry>
<entry>secret_item_get_modified()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_get_type()</entry>
<entry>secret_item_get_schema_name()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_set_type()</entry>
<entry>secret_item_set_attributes() with appropriate schema</entry>
</row>
<row>
<entry>gnome_keyring_item_info_get_secret()</entry>
<entry>secret_item_get_secret()</entry>
</row>
<row>
<entry>gnome_keyring_item_info_set_secret()</entry>
<entry>secret_item_set_secret() and secret_item_set_secret_sync()</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_INFO_BASICS</entry>
<entry>no equivalent, all basic item properties are loaded on #SecretItem
automatically</entry>
</row>
<row>
<entry>%GNOME_KEYRING_ITEM_INFO_SECRET</entry>
<entry>use secret_item_load_secret() and secret_item_load_secret_sync() to load
the secret for an item.</entry>
</row>
<row>
<entry>gnome_keyring_item_info_set_display_name()</entry>
<entry></entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-keyrings">
<title>Keyring management</title>
<para>In libsecret keyrings are called 'collections'. This is the same
lingo as the underlying Secret Service DBus API. Keyrings are no longer
identified by simple keyring names. Normally applications just use the
default keyrings and these are identified by the aliases
%SECRET_COLLECTION_DEFAULT and %SECRET_COLLECTION_SESSION. It is also
possible to identify collections by their DBus object paths.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_create()</entry>
<entry>secret_collection_create()</entry>
</row>
<row>
<entry>gnome_keyring_create_sync()</entry>
<entry>secret_collection_create_sync()</entry>
</row>
<row>
<entry>gnome_keyring_delete()</entry>
<entry>secret_collection_delete()</entry>
</row>
<row>
<entry>gnome_keyring_delete_sync()</entry>
<entry>secret_collection_delete_sync()</entry>
</row>
<row>
<entry>gnome_keyring_change_password()</entry>
<entry>no equivalent, use platform specific DBus APIs</entry>
</row>
<row>
<entry>gnome_keyring_change_password_sync()</entry>
<entry>no equivalent, use platform specific DBus APIs</entry>
</row>
<row>
<entry>gnome_keyring_list_keyring_names()</entry>
<entry>secret_service_load_collections() and secret_service_get_collections()</entry>
</row>
<row>
<entry>gnome_keyring_list_keyring_names_sync()</entry>
<entry>secret_service_load_collections_sync() and secret_service_get_collections()</entry>
</row>
<row>
<entry>gnome_keyring_set_default_keyring()</entry>
<entry>secret_service_set_alias()</entry>
</row>
<row>
<entry>gnome_keyring_set_default_keyring_sync()</entry>
<entry>secret_service_set_alias_sync()</entry>
</row>
<row>
<entry>gnome_keyring_get_default_keyring()</entry>
<entry>secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT</entry>
</row>
<row>
<entry>gnome_keyring_get_default_keyring_sync()</entry>
<entry>secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT</entry>
</row>
<row>
<entry>gnome_keyring_list_item_ids()</entry>
<entry>secret_collection_load_items() and secret_collection_get_items()</entry>
</row>
<row>
<entry>gnome_keyring_list_item_ids_sync()</entry>
<entry>secret_collection_load_items_sync() and secret_collection_get_items()</entry>
</row>
<row>
<entry>#GnomeKeyringInfo</entry>
<entry>#SecretCollection and properties</entry>
</row>
<row>
<entry>gnome_keyring_get_info()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_get_info_sync()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_set_info()</entry>
<entry>no equivalent, use property setters on #SecretCollection</entry>
</row>
<row>
<entry>gnome_keyring_set_info_sync()</entry>
<entry>no equivalent, use property setters on #SecretCollection</entry>
</row>
<row>
<entry>gnome_keyring_info_free()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_copy()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_set_lock_on_idle()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_get_lock_on_idle()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_set_lock_timeout()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_get_lock_timeout()</entry>
<entry>no equivalent</entry>
</row>
<row>
<entry>gnome_keyring_info_get_mtime()</entry>
<entry>secret_collection_get_modified()</entry>
</row>
<row>
<entry>gnome_keyring_info_get_ctime()</entry>
<entry>secret_collection_get_created()</entry>
</row>
<row>
<entry>gnome_keyring_info_get_is_locked()</entry>
<entry>secret_collection_get_locked()</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-locking">
<title>Locking and unlocking</title>
<para>In libsecret you can unlock items directly, and the result is
(with gnome-keyring daemon) that the enclosing collection will be unlocked.</para>
<para>It is no longer possible to pass a password to unlock keyrings.
These are automatically prompted for.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_unlock()</entry>
<entry>secret_service_unlock()</entry>
</row>
<row>
<entry>gnome_keyring_unlock_sync()</entry>
<entry>secret_service_unlock_sync()</entry>
</row>
<row>
<entry>gnome_keyring_lock()</entry>
<entry>secret_service_lock()</entry>
</row>
<row>
<entry>gnome_keyring_lock_sync()</entry>
<entry>secret_service_lock_sync()</entry>
</row>
<row>
<entry>gnome_keyring_lock_all()</entry>
<entry>no equivalent, use platform specific DBus APIs</entry>
</row>
<row>
<entry>gnome_keyring_lock_all_sync()</entry>
<entry>no equivalent, use platform specific DBus APIs</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-memory">
<title>Non-pageable memory</title>
<para>libsecret no longer provides a full API for using non-pageable
memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.</para>
<para>You can request that passwords are returned in non-pageable
memory by using the secret_password_lookup_nonpageable_sync() and
secret_password_lookup_nonpageable_finish() functions.
In addition the contents of #SecretValue items is stored in
non-pageable memory, unless the system doesn't support this.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_memory_alloc()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_free()</entry>
<entry>secret_password_free(), although this only works on strings</entry>
</row>
<row>
<entry>gnome_keyring_memory_is_secure()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_new()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_realloc()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_strdup()</entry>
<entry>no equivalent, use #SecretValue which is ref-counted, or use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_try_alloc()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_memory_try_realloc()</entry>
<entry>no equivalent, use Gcr</entry>
</row>
<row>
<entry>gnome_keyring_free_password()</entry>
<entry>secret_password_free()</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
<section id="migrating-misc">
<title>Errors and cancellation</title>
<para>libsecret uses standard the standard #GCancellable idiom
to cancel operations.</para>
<para>It is not necessary to check whether the keyring daemon is
available before using it. It is started automatically.</para>
<para>Errors are returned as standard #GError in the usual way.
There are fewer errors that are worth handling in an intelligent way,
exceptions are in the #SecretError enumeration. It is not recommended
to display any #GError message returned by libsecret to the user. Most
of the possible errors are DBus communication problems or similar.</para>
<para>Replacements for related libgnome-keyring functions and types
are described below:
<table><tgroup cols="2">
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
<tbody>
<row>
<entry>gnome_keyring_cancel_request()</entry>
<entry>g_cancellable_cancel() on a #GCancellable passed to the relevant operation</entry>
</row>
<row>
<entry>gnome_keyring_is_available()</entry>
<entry>no equivalent, the secret service is autostarted as necessary</entry>
</row>
<row>
<entry>gnome_keyring_result_to_message()</entry>
<entry>use the message in the #GError, although most failures are not appropriate for display to the user</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_OK</entry>
<entry>no #GError returned</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_DENIED</entry>
<entry>no longer used, item or collection is simply not unlocked</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</entry>
<entry>%G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</entry>
<entry>no error, success returned</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</entry>
<entry>keyrings no longer have names, accessing an missing DBus object has usual failure</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_BAD_ARGUMENTS</entry>
<entry>%G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always
a programmer error</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_IO_ERROR</entry>
<entry>relevant DBus errors, or %SECRET_ERROR_PROTOCOL</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_CANCELLED</entry>
<entry>%G_IO_ERROR_CANCELLED</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</entry>
<entry>no error, simply returns already existing keyring</entry>
</row>
<row>
<entry>%GNOME_KEYRING_RESULT_NO_MATCH</entry>
<entry>on error, an empty list is returned</entry>
</row>
<row>
<entry>gnome_keyring_string_list_free()</entry>
<entry>no equivalent</entry>
</row>
</tbody>
</tgroup></table></para>
</section>
</chapter>
</part>

6
docs/reference/libsecret/urlmap.js Normal file
View File

@ -0,0 +1,6 @@
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
]

1
docs/reference/libsecret/version-major.xml.in
View File

@ -1 +0,0 @@
@SECRET_MAJOR@

1
docs/reference/libsecret/version.xml.in
View File

@ -1 +0,0 @@
@VERSION@

17
libsecret/secret-attributes.c
View File

@ -19,19 +19,6 @@
#include <string.h>
/**
* SECTION:secret-attributes
* @title: Secret Attributes
* @short_description: secret attributes
*
* Each item has a set of attributes, which are used to locate the item later.
* These are not stored or transferred in a secure manner. Each attribute has
* a string name and a string value. These attributes are represented by a
* #GHashTable with string keys and values.
*
* Use secret_attributes_build() to simply build up a set of attributes.
*/
GVariant *
_secret_attributes_to_variant (GHashTable *attributes,
const gchar *schema_name)
@ -87,7 +74,7 @@ _secret_attributes_for_variant (GVariant *variant)
* @schema. The list of attributes should be terminated with a %NULL.
*
* Returns: (transfer full) (element-type utf8 utf8): a new table of
* attributes, to be released with g_hash_table_unref()
* attributes, to be released with [func@GLib.HashTable.unref]
*/
GHashTable *
secret_attributes_build (const SecretSchema *schema,
@ -116,7 +103,7 @@ secret_attributes_build (const SecretSchema *schema,
* @schema. The list of attributes should be terminated with a %NULL.
*
* Returns: (transfer full) (element-type utf8 utf8): a new table of
* attributes, to be released with g_hash_table_unref()
* attributes, to be released with [func@GLib.HashTable.unref]
*/
GHashTable *
secret_attributes_buildv (const SecretSchema *schema,

24
libsecret/secret-backend.c
View File

@ -25,9 +25,9 @@
#include "libsecret/secret-enum-types.h"
/**
* SECTION:secret-backend
* @title: SecretBackend
* @short_description: A backend implementation of password storage
* SecretBackend
*
* A backend implementation of password storage
*
* #SecretBackend represents a backend implementation of password
* storage.
@ -48,14 +48,14 @@
* @parent_iface: the parent interface
* @ensure_for_flags: implementation of reinitialization step in constructor, optional
* @ensure_for_flags_finish: implementation of reinitialization step in constructor, optional
* @store: implementation of secret_password_store(), required
* @store_finish: implementation of secret_password_store_finish(), required
* @lookup: implementation of secret_password_lookup(), required
* @lookup_finish: implementation of secret_password_lookup_finish(), required
* @clear: implementation of secret_password_clear(), required
* @clear_finish: implementation of secret_password_clear_finish(), required
* @search: implementation of secret_password_search(), required
* @search_finish: implementation of secret_password_search_finish(), required
* @store: implementation of [func@password_store], required
* @store_finish: implementation of [func@password_store_finish], required
* @lookup: implementation of [func@password_lookup], required
* @lookup_finish: implementation of [func@password_lookup_finish], required
* @clear: implementation of [func@password_clear], required
* @clear_finish: implementation of [func@password_clear_finish], required
* @search: implementation of [func@password_search], required
* @search_finish: implementation of [func@password_search_finish], required
*
* The interface for #SecretBackend.
*
@ -264,7 +264,7 @@ secret_backend_get (SecretBackendFlags flags,
* Complete an asynchronous operation to get a #SecretBackend.
*
* Returns: (transfer full): a new reference to a #SecretBackend proxy, which
* should be released with g_object_unref().
* should be released with [method@GObject.Object.unref].
*
* Since: 0.19.0
*/

142
libsecret/secret-collection.c
View File

@ -27,29 +27,24 @@
#include <glib/gi18n-lib.h>
/**
* SECTION:secret-collection
* @title: SecretCollection
* @short_description: A collection of secret items
* SecretCollection:
*
* A proxy object representing a collection of secrets in the Secret Service.
*
* #SecretCollection represents a collection of secret items stored in the
* Secret Service.
*
* A collection can be in a locked or unlocked state. Use secret_service_lock()
* or secret_service_unlock() to lock or unlock the collection.
* A collection can be in a locked or unlocked state. Use
* [method@SecretService.lock] or [method@SecretService.unlock] to lock or
* unlock the collection.
*
* Use the SecretCollection::items property or secret_collection_get_items() to
* lookup the items in the collection. There may not be any items exposed when
* the collection is locked.
* Use the [property@SecretCollection:items] property or
* [method@SecretCollection.get_items] to lookup the items in the collection.
* There may not be any items exposed when the collection is locked.
*
* Stability: Stable
*/
/**
* SecretCollection:
*
* A proxy object representing a collection of secrets in the Secret Service.
*/
/**
* SecretCollectionClass:
* @parent_class: the parent class
@ -69,22 +64,22 @@
* SecretCollectionCreateFlags:
* @SECRET_COLLECTION_CREATE_NONE: no flags
*
* Flags for secret_collection_create().
* Flags for [func@Collection.create].
*/
/**
* SECRET_COLLECTION_DEFAULT:
*
* An alias to the default collection. This can be passed to secret_password_store()
* secret_collection_for_alias().
* An alias to the default collection. This can be passed to
* [func@password_store] [func@Collection.for_alias].
*/
/**
* SECRET_COLLECTION_SESSION:
*
* An alias to the session collection, which will be cleared when the user ends
* the session. This can be passed to secret_password_store(),
* secret_collection_for_alias() or similar functions.
* the session. This can be passed to [func@password_store],
* [func@Collection.for_alias] or similar functions.
*/
enum {
@ -429,9 +424,9 @@ secret_collection_class_init (SecretCollectionClass *klass)
proxy_class->g_signal = secret_collection_signal;
/**
* SecretCollection:service:
* SecretCollection:service: (attributes org.gtk.Property.get=secret_collection_get_service)
*
* The #SecretService object that this collection is associated with and
* The [class@Service] object that this collection is associated with and
* uses to interact with the actual D-Bus Secret Service.
*/
g_object_class_install_property (gobject_class, PROP_SERVICE,
@ -439,7 +434,7 @@ secret_collection_class_init (SecretCollectionClass *klass)
SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:flags:
* SecretCollection:flags: (attributes org.gtk.Property.get=secret_collection_get_flags)
*
* A set of flags describing which parts of the secret collection have
* been initialized.
@ -450,9 +445,9 @@ secret_collection_class_init (SecretCollectionClass *klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:items:
* SecretCollection:items: (attributes org.gtk.Property.get=secret_collection_get_items)
*
* A list of #SecretItem objects representing the items that are in
* A list of [class@Item] objects representing the items that are in
* this collection. This list will be empty if the collection is locked.
*/
g_object_class_install_property (gobject_class, PROP_ITEMS,
@ -460,32 +455,32 @@ secret_collection_class_init (SecretCollectionClass *klass)
_secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:label:
* SecretCollection:label: (attributes org.gtk.Property.get=secret_collection_get_label org.gtk.Property.set=secret_collection_set_label)
*
* The human readable label for the collection.
*
* Setting this property will result in the label of the collection being
* set asynchronously. To properly track the changing of the label use the
* secret_collection_set_label() function.
* [method@Collection.set_label] function.
*/
g_object_class_install_property (gobject_class, PROP_LABEL,
g_param_spec_string ("label", "Label", "Item label",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:locked:
* SecretCollection:locked: (attributes org.gtk.Property.get=secret_collection_get_locked)
*
* Whether the collection is locked or not.
*
* To lock or unlock a collection use the secret_service_lock() or
* secret_service_unlock() functions.
* To lock or unlock a collection use the [method@Service.lock] or
* [method@Service.unlock] functions.
*/
g_object_class_install_property (gobject_class, PROP_LOCKED,
g_param_spec_boolean ("locked", "Locked", "Item locked",
TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:created:
* SecretCollection:created: (attributes org.gtk.Property.get=secret_collection_get_created)
*
* The date and time (in seconds since the UNIX epoch) that this
* collection was created.
@ -495,7 +490,7 @@ secret_collection_class_init (SecretCollectionClass *klass)
0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:modified:
* SecretCollection:modified: (attributes org.gtk.Property.get=secret_collection_get_modified)
*
* The date and time (in seconds since the UNIX epoch) that this
* collection was last modified.
@ -765,10 +760,10 @@ on_load_item (GObject *source,
*
* Ensure that the #SecretCollection proxy has loaded all the items present
* in the Secret Service. This affects the result of
* secret_collection_get_items().
* [method@Collection.get_items].
*
* For collections returned from secret_service_get_collections() the items
* will have already been loaded.
* For collections returned from [method@Service.get_collections] the items will
* have already been loaded.
*
* This method will return immediately and complete asynchronously.
*/
@ -859,9 +854,9 @@ secret_collection_load_items_finish (SecretCollection *self,
*
* Ensure that the #SecretCollection proxy has loaded all the items present
* in the Secret Service. This affects the result of
* secret_collection_get_items().
* [method@Collection.get_items].
*
* For collections returned from secret_service_get_collections() the items
* For collections returned from [method@Service.get_collections] the items
* will have already been loaded.
*
* This method may block indefinitely and should not be used in user interface
@ -1050,7 +1045,7 @@ _secret_collection_properties_new (const gchar *label)
* Create a new collection in the secret service.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that are required.
*
* An @alias is a well-known tag for a collection, such as 'default' (ie: the
@ -1059,8 +1054,8 @@ _secret_collection_properties_new (const gchar *label)
* collection with that alias already exists, then a new collection will not
* be created. The previous one will be returned instead.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get the
* default [class@Service] proxy.
*/
void
secret_collection_create (SecretService *service,
@ -1108,7 +1103,7 @@ secret_collection_create (SecretService *service,
* Finish operation to create a new collection in the secret service.
*
* Returns: (transfer full): the new collection, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretCollection *
secret_collection_create_finish (GAsyncResult *result,
@ -1140,20 +1135,20 @@ secret_collection_create_finish (GAsyncResult *result,
* Create a new collection in the secret service.
*
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. secret_service_prompt()
* threads. The secret service may prompt the user. [method@Service.prompt]
* will be used to handle any prompts that are required.
*
* An @alias is a well-known tag for a collection, such as 'default' (ie: the
* An @alias is a well-known tag for a collection, such as `default` (ie: the
* default collection to store items in). This allows other applications to
* easily identify and share a collection. If you specify an @alias, and a
* collection with that alias already exists, then a new collection will not
* be created. The previous one will be returned instead.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get the
* default [class@Service] proxy.
*
* Returns: (transfer full): the new collection, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretCollection *
secret_collection_create_sync (SecretService *service,
@ -1395,7 +1390,7 @@ on_search_paths (GObject *source,
* search and be returned. If the unlock fails, the search does not fail.
*
* If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have
* their secret values loaded and available via secret_item_get_secret().
* their secret values loaded and available via [method@Item.get_secret].
*
* This function returns immediately and completes asynchronously.
*/
@ -1443,7 +1438,7 @@ secret_collection_search (SecretCollection *self,
* Complete asynchronous operation to search for items in a collection.
*
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
* a list of items that matched the search
*/
GList *
secret_collection_search_finish (SecretCollection *self,
@ -1526,13 +1521,13 @@ collection_load_items_sync (SecretCollection *self,
* search and be returned. If the unlock fails, the search does not fail.
*
* If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have
* their secret values loaded and available via secret_item_get_secret().
* their secret values loaded and available via [method@Item.get_secret].
*
* This function may block indefinitely. Use the asynchronous version
* in user interface threads.
*
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
* a list of items that matched the search
*/
GList *
secret_collection_search_sync (SecretCollection *self,
@ -1610,7 +1605,7 @@ on_service_delete_path (GObject *source,
* Delete this collection.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that show up.
*/
void
@ -1671,9 +1666,9 @@ secret_collection_delete_finish (SecretCollection *self,
*
* Delete this collection.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. [method@Service.prompt] will
* be used to handle any prompts that show up.
*
* Returns: whether the collection was successfully deleted or not
*/
@ -1705,7 +1700,7 @@ secret_collection_delete_sync (SecretCollection *self,
}
/**
* secret_collection_get_service:
* secret_collection_get_service: (attributes org.gtk.Method.get_property=service)
* @self: a collection
*
* Get the Secret Service object that this collection was created with.
@ -1720,14 +1715,14 @@ secret_collection_get_service (SecretCollection *self)
}
/**
* secret_collection_get_flags:
* secret_collection_get_flags: (attributes org.gtk.Method.get_property=flags)
* @self: the secret collection proxy
*
* Get the flags representing what features of the #SecretCollection proxy
* have been initialized.
*
* Use secret_collection_load_items() to initialize further features
* and change the flags.
* Use [method@Collection.load_items] to initialize further features and change
* the flags.
*
* Returns: the flags for features initialized
*/
@ -1749,14 +1744,14 @@ secret_collection_get_flags (SecretCollection *self)
}
/**
* secret_collection_get_items:
* secret_collection_get_items: (attributes org.gtk.Method.get_property=items)
* @self: a collection
*
* Get the list of items in this collection.
*
* Returns: (transfer full) (element-type Secret.Item): a list of items,
* when done, the list should be freed with g_list_free, and each item should
* be released with g_object_unref()
* Returns: (transfer full) (element-type Secret.Item): a list of items, when
* done, the list should be freed with [func@GLib.List.free], and each item
* should be released with [method@GObject.Object.unref]
*/
GList *
secret_collection_get_items (SecretCollection *self)
@ -1792,12 +1787,13 @@ _secret_collection_find_item_instance (SecretCollection *self,
}
/**
* secret_collection_get_label:
* secret_collection_get_label: (attributes org.gtk.Method.get_property=label)
* @self: a collection
*
* Get the label of this collection.
*
* Returns: (transfer full): the label, which should be freed with g_free()
* Returns: (transfer full): the label, which should be freed with
* [func@GLib.free]
*/
gchar *
secret_collection_get_label (SecretCollection *self)
@ -1817,7 +1813,7 @@ secret_collection_get_label (SecretCollection *self)
}
/**
* secret_collection_set_label:
* secret_collection_set_label: (attributes org.gtk.Method.set_property=label)
* @self: a collection
* @label: a new label
* @cancellable: (nullable): optional cancellation object
@ -1895,12 +1891,12 @@ secret_collection_set_label_sync (SecretCollection *self,
}
/**
* secret_collection_get_locked:
* secret_collection_get_locked: (attributes org.gtk.Method.get_property=locked)
* @self: a collection
*
* Get whether the collection is locked or not.
*
* Use secret_service_lock() or secret_service_unlock() to lock or unlock the
* Use [method@Service.lock] or [method@Service.unlock] to lock or unlock the
* collection.
*
* Returns: whether the collection is locked or not
@ -1923,7 +1919,7 @@ secret_collection_get_locked (SecretCollection *self)
}
/**
* secret_collection_get_created:
* secret_collection_get_created: (attributes org.gtk.Method.get_property=created)
* @self: a collection
*
* Get the created date and time of the collection. The return value is
@ -1949,7 +1945,7 @@ secret_collection_get_created (SecretCollection *self)
}
/**
* secret_collection_get_modified:
* secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified)
* @self: a collection
*
* Get the modified date and time of the collection. The return value is
@ -2091,8 +2087,8 @@ on_read_alias_service (GObject *source,
* Lookup which collection is assigned to this alias. Aliases help determine
* well known collections, such as 'default'.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get the
* default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*/
@ -2167,10 +2163,10 @@ secret_collection_for_alias_finish (GAsyncResult *result,
* @error: location to place error on failure
*
* Lookup which collection is assigned to this alias. Aliases help determine
* well known collections, such as 'default'.
* well known collections, such as `default`.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get the
* default [class@Service] proxy.
*
* This method may block and should not be used in user interface threads.
*

80
libsecret/secret-item.c
View File

@ -29,38 +29,32 @@
#include <glib/gi18n-lib.h>
/**
* SECTION:secret-item
* @title: SecretItem
* @short_description: A secret item
* SecretItem:
*
* A secret item
*
* #SecretItem represents a secret item stored in the Secret Service.
*
* Each item has a value, represented by a #SecretValue, which can be
* retrieved by secret_item_get_secret() or set by secret_item_set_secret().
* Each item has a value, represented by a [struct@Value], which can be
* retrieved by [method@Item.get_secret] or set by [method@Item.set_secret].
* The item is only available when the item is not locked.
*
* Items can be locked or unlocked using the secret_service_lock() or
* secret_service_unlock() functions. The Secret Service may not be able to
* Items can be locked or unlocked using the [method@Service.lock] or
* [method@Service.unlock] functions. The Secret Service may not be able to
* unlock individual items, and may unlock an entire collection when a single
* item is unlocked.
*
* Each item has a set of attributes, which are used to locate the item later.
* These are not stored or transferred in a secure manner. Each attribute has
* a string name and a string value. Use secret_service_search() to search for
* items based on their attributes, and secret_item_set_attributes() to change
* a string name and a string value. Use [method@Service.search] to search for
* items based on their attributes, and [method@Item.set_attributes] to change
* the attributes associated with an item.
*
* Items can be created with secret_item_create() or secret_service_store().
* Items can be created with [func@Item.create] or [method@Service.store].
*
* Stability: Stable
*/
/**
* SecretItem:
*
* A proxy object representing a secret item in the Secret Service.
*/
/**
* SecretItemClass:
* @parent_class: the parent class
@ -81,7 +75,7 @@
* @SECRET_ITEM_CREATE_NONE: no flags
* @SECRET_ITEM_CREATE_REPLACE: replace an item with the same attributes.
*
* Flags for secret_item_create().
* Flags for [func@Item.create].
*/
enum {
@ -335,9 +329,9 @@ secret_item_class_init (SecretItemClass *klass)
proxy_class->g_properties_changed = secret_item_properties_changed;
/**
* SecretItem:service:
* SecretItem:service: (attributes org.gtk.Property.get=secret_item_get_service)
*
* The #SecretService object that this item is associated with and
* The [class@Service] object that this item is associated with and
* uses to interact with the actual D-Bus Secret Service.
*/
g_object_class_install_property (gobject_class, PROP_SERVICE,
@ -345,7 +339,7 @@ secret_item_class_init (SecretItemClass *klass)
SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
/**
* SecretItem:flags:
* SecretItem:flags: (attributes org.gtk.Property.get=secret_item_get_flags)
*
* A set of flags describing which parts of the secret item have
* been initialized.
@ -370,18 +364,18 @@ secret_item_class_init (SecretItemClass *klass)
*
* Setting this property will result in the label of the item being
* set asynchronously. To properly track the changing of the label use the
* secret_item_set_label() function.
* [method@Item.set_label] function.
*/
g_object_class_override_property (gobject_class, PROP_LABEL, "label");
/**
* SecretItem:locked:
* SecretItem:locked: (attributes org.gtk.Property.get=secret_item_get_locked)
*
* Whether the item is locked or not. An item may not be independently
* lockable separate from other items in its collection.
*
* To lock or unlock a item use the secret_service_lock() or
* secret_service_unlock() functions.
* To lock or unlock a item use the [method@Service.lock] or
* [method@Service.unlock] functions.
*/
g_object_class_install_property (gobject_class, PROP_LOCKED,
g_param_spec_boolean ("locked", "Locked", "Item locked",
@ -734,7 +728,7 @@ item_properties_new (const gchar *label,
* instead of creating a new one.
*
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. secret_service_prompt()
* threads. The secret service may prompt the user. [method@Service.prompt]
* will be used to handle any prompts that are required.
*/
void
@ -790,7 +784,7 @@ secret_item_create (SecretCollection *collection,
* Finish operation to create a new item in the secret service.
*
* Returns: (transfer full): the new item, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretItem *
secret_item_create_finish (GAsyncResult *result,
@ -828,11 +822,11 @@ secret_item_create_finish (GAsyncResult *result,
* instead of creating a new one.
*
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. secret_service_prompt()
* threads. The secret service may prompt the user. [method@Service.prompt]
* will be used to handle any prompts that are required.
*
* Returns: (transfer full): the new item, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretItem *
secret_item_create_sync (SecretCollection *collection,
@ -908,7 +902,7 @@ on_item_deleted (GObject *source,
* Delete this item.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that show up.
*/
void
@ -971,7 +965,7 @@ secret_item_delete_finish (SecretItem *self,
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*
* Returns: whether the item was successfully deleted or not
*/
@ -1003,13 +997,13 @@ secret_item_delete_sync (SecretItem *self,
}
/**
* secret_item_get_flags:
* secret_item_get_flags: (attributes org.gtk.Method.get_property=flags)
* @self: the secret item proxy
*
* Get the flags representing what features of the #SecretItem proxy
* have been initialized.
*
* Use secret_item_load_secret() to initialize further features
* Use [method@Item.load_secret] to initialize further features
* and change the flags.
*
* Returns: the flags for features initialized
@ -1033,7 +1027,7 @@ secret_item_get_flags (SecretItem *self)
}
/**
* secret_item_get_service:
* secret_item_get_service: (attributes org.gtk.Method.get_property=service)
* @self: an item
*
* Get the Secret Service object that this item was created with.
@ -1055,10 +1049,10 @@ secret_item_get_service (SecretItem *self)
* Get the secret value of this item. If this item is locked or the secret
* has not yet been loaded then this will return %NULL.
*
* To load the secret call the secret_item_load_secret() method.
* To load the secret call the [method@Item.load_secret] method.
*
* Returns: (transfer full) (nullable): the secret value which should be
* released with secret_value_unref(), or %NULL
* released with [method@Value.unref], or %NULL
*/
SecretValue *
secret_item_get_secret (SecretItem *self)
@ -1189,7 +1183,7 @@ secret_item_load_secret (SecretItem *self,
* Complete asynchronous operation to load the secret value of this item.
*
* The newly loaded secret value can be accessed by calling
* secret_item_get_secret().
* [method@Item.get_secret].
*
* Returns: whether the secret item successfully loaded or not
*/
@ -1394,7 +1388,7 @@ on_loads_secrets_session (GObject *source,
*
* Load the secret values for a secret item stored in the service.
*
* The @items must all have the same SecretItem::service property.
* The @items must all have the same [property@Item:service] property.
*
* This function returns immediately and completes asynchronously.
*/
@ -1488,7 +1482,7 @@ secret_item_load_secrets_finish (GAsyncResult *result,
*
* Load the secret values for a secret item stored in the service.
*
* The @items must all have the same SecretItem::service property.
* The @items must all have the same [property@Item:service] property.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -1698,7 +1692,7 @@ secret_item_set_secret_sync (SecretItem *self,
* @self: an item
*
* Gets the name of the schema that this item was stored with. This is also
* available at the <literal>xdg:schema</literal> attribute.
* available at the `xdg:schema` attribute.
*
* Returns: (nullable) (transfer full): the schema name
*/
@ -1730,11 +1724,11 @@ secret_item_get_schema_name (SecretItem *self)
* or transferred securely by the secret service.
*
* Do not modify the attributes returned by this method. Use
* secret_item_set_attributes() instead.
* [method@Item.set_attributes] instead.
*
* Returns: (transfer full) (element-type utf8 utf8): a new reference
* to the attributes, which should not be modified, and
* released with g_hash_table_unref()
* to the attributes, which should not be modified, and
* released with [func@GLib.HashTable.unref]
*/
GHashTable *
secret_item_get_attributes (SecretItem *self)
@ -1865,7 +1859,7 @@ secret_item_set_attributes_sync (SecretItem *self,
*
* Get the label of this item.
*
* Returns: (transfer full): the label, which should be freed with g_free()
* Returns: (transfer full): the label, which should be freed with [func@GLib.free]
*/
gchar *
secret_item_get_label (SecretItem *self)

86
libsecret/secret-methods.c
View File

@ -33,7 +33,7 @@
* @SECRET_SEARCH_UNLOCK: unlock locked items while searching
* @SECRET_SEARCH_LOAD_SECRETS: while searching load secrets for items that are not locked
*
* Various flags to be used with secret_service_search() and secret_service_search_sync().
* Various flags to be used with [method@Service.search] and [method@Service.search_sync].
*/
typedef struct {
@ -273,8 +273,8 @@ on_search_service (GObject *source,
* Search for items matching the @attributes. All collections are searched.
* The @attributes should be a table of string keys and string values.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the
* search will be returned. Otherwise only the first item will be returned.
@ -285,7 +285,7 @@ on_search_service (GObject *source,
* search and be returned. If the unlock fails, the search does not fail.
*
* If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have
* their secret values loaded and available via secret_item_get_secret().
* their secret values loaded and available via [method@Item.get_secret].
*
* This function returns immediately and completes asynchronously.
*/
@ -345,7 +345,7 @@ secret_service_search (SecretService *service,
* Complete asynchronous operation to search for items.
*
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
* a list of items that matched the search
*/
GList *
secret_service_search_finish (SecretService *service,
@ -413,8 +413,8 @@ service_load_items_sync (SecretService *service,
* Search for items matching the @attributes. All collections are searched.
* The @attributes should be a table of string keys and string values.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the
* search will be returned. Otherwise only the first item will be returned.
@ -426,14 +426,14 @@ service_load_items_sync (SecretService *service,
*
* If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items' secret
* values will be loaded for any unlocked items. Loaded item secret values
* are available via secret_item_get_secret(). If the load of a secret values
* are available via [method@Item.get_secret]. If the load of a secret values
* fail, then the
*
* This function may block indefinitely. Use the asynchronous version
* in user interface threads.
*
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
* a list of items that matched the search
*/
GList *
secret_service_search_sync (SecretService *service,
@ -735,11 +735,11 @@ service_xlock_finish (SecretService *service,
* The secret service may not be able to lock items individually, and may
* lock an entire collection instead.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that show up.
*/
void
@ -797,12 +797,12 @@ secret_service_lock_finish (SecretService *service,
* The secret service may not be able to lock items individually, and may
* lock an entire collection instead.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*
* Returns: the number of items or collections that were locked
*/
@ -849,12 +849,12 @@ secret_service_lock_sync (SecretService *service,
* The secret service may not be able to unlock items individually, and may
* unlock an entire collection instead.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*/
void
secret_service_unlock (SecretService *service,
@ -911,12 +911,12 @@ secret_service_unlock_finish (SecretService *service,
* The secret service may not be able to unlock items individually, and may
* unlock an entire collection instead.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*
* Returns: the number of items or collections that were unlocked
*/
@ -1131,11 +1131,11 @@ on_store_service (GObject *source,
* If the attributes match a secret item already stored in the collection, then
* the item will be updated with these new values.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* If @collection is not specified, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* This method will return immediately and complete asynchronously.
@ -1251,11 +1251,11 @@ secret_service_store_finish (SecretService *service,
* the item will be updated with these new values.
*
* If @collection is %NULL, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -1427,8 +1427,8 @@ on_lookup_service (GObject *source,
*
* The @attributes should be a set of key and value string pairs.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*/
@ -1485,8 +1485,8 @@ secret_service_lookup (SecretService *service,
*
* If no secret is found then %NULL is returned.
*
* Returns: (transfer full): a newly allocated #SecretValue, which should be
* released with secret_value_unref(), or %NULL if no secret found
* Returns: (transfer full): a newly allocated [struct@Value], which should be
* released with [method@Value.unref], or %NULL if no secret found
*/
SecretValue *
secret_service_lookup_finish (SecretService *service,
@ -1520,14 +1520,14 @@ secret_service_lookup_finish (SecretService *service,
*
* The @attributes should be a set of key and value string pairs.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user interface
* threads.
*
* Returns: (transfer full): a newly allocated #SecretValue, which should be
* released with secret_value_unref(), or %NULL if no secret found
* Returns: (transfer full): a newly allocated [struct@Value], which should be
* released with [method@Value.unref], or %NULL if no secret found
*/
SecretValue *
secret_service_lookup_sync (SecretService *service,
@ -1674,8 +1674,8 @@ on_delete_service (GObject *source,
*
* The @attributes should be a set of key and value string pairs.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*/
@ -1765,8 +1765,8 @@ secret_service_clear_finish (SecretService *service,
*
* The @attributes should be a set of key and value string pairs.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -1878,8 +1878,8 @@ on_set_alias_service (GObject *source,
* Assign a collection to this alias. Aliases help determine
* well known collections, such as 'default'.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*/
@ -1967,8 +1967,8 @@ secret_service_set_alias_finish (SecretService *service,
* Assign a collection to this alias. Aliases help determine
* well known collections, such as 'default'.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block and should not be used in user interface threads.
*

99
libsecret/secret-password.c
View File

@ -23,27 +23,6 @@
#include <egg/egg-secure-memory.h>
/**
* SECTION:secret-password
* @title: Password storage
* @short_description: Simple password storage and lookup
*
* This is a simple API for storing passwords and retrieving passwords in the
* Secret Service.
*
* Each password is associated with a set of attributes. Attribute values can
* be either strings, integers or booleans.
*
* The names and types of allowed attributes for a given password are defined
* with a schema. Certain schemas are predefined. Additional schemas can be
* defined via the %SecretSchema structure.
*
* Each of the functions accept a variable list of attributes names and their
* values. Include a %NULL to terminate the list of attributes.
*
* Stability: Stable
*/
/**
* secret_password_store: (skip)
* @schema: the schema for attributes
@ -67,7 +46,7 @@
* the item will be updated with these new values.
*
* If @collection is %NULL, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* This method will return immediately and complete asynchronously.
@ -195,7 +174,7 @@ on_store_backend (GObject *source,
* the item will be updated with these new values.
*
* If @collection is %NULL, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* This method will return immediately and complete asynchronously.
@ -240,9 +219,9 @@ secret_password_storev (const SecretSchema *schema,
* secret_password_store_binary: (skip)
* @schema: the schema for attributes
* @collection: (nullable): a collection alias, or D-Bus object path of the
* collection where to store the secret
* collection where to store the secret
* @label: label for the secret
* @value: a #SecretValue
* @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object
* @callback: called when the operation completes
* @user_data: data to be passed to the callback
@ -250,8 +229,8 @@ secret_password_storev (const SecretSchema *schema,
*
* Store a password in the secret service.
*
* This is similar to secret_password_store(), but takes a
* #SecretValue as the argument instead of a null-terminated password.
* This is similar to [func@password_store], but takes a
* [struct@Value] as the argument instead of a null-terminated password.
*
* This method will return immediately and complete asynchronously.
*
@ -296,15 +275,15 @@ secret_password_store_binary (const SecretSchema *schema,
* @collection: (nullable): a collection alias, or D-Bus object path of the
* collection where to store the secret
* @label: label for the secret
* @value: a #SecretValue
* @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object
* @callback: (scope async): called when the operation completes
* @user_data: data to be passed to the callback
*
* Store a password in the secret service.
*
* This is similar to secret_password_storev(), but takes a
* #SecretValue as the argument instead of a null-terminated password.
* This is similar to [func@password_storev], but takes a
* [struct@Value] as the argument instead of a null-terminated password.
*
* This method will return immediately and complete asynchronously.
*
@ -387,7 +366,7 @@ secret_password_store_finish (GAsyncResult *result,
* the item will be updated with these new values.
*
* If @collection is %NULL, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* This method may block indefinitely and should not be used in user interface
@ -448,7 +427,7 @@ secret_password_store_sync (const SecretSchema *schema,
* the item will be updated with these new values.
*
* If @collection is %NULL, then the default collection will be
* used. Use #SECRET_COLLECTION_SESSION to store the password in the session
* used. Use [const@COLLECTION_SESSION] to store the password in the session
* collection, which doesn't get stored across login sessions.
*
* This method may block indefinitely and should not be used in user interface
@ -500,15 +479,15 @@ secret_password_storev_sync (const SecretSchema *schema,
* @collection: (nullable): a collection alias, or D-Bus object path of the
* collection where to store the secret
* @label: label for the secret
* @value: a #SecretValue
* @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object
* @error: location to place an error on failure
* @...: the attribute keys and values, terminated with %NULL
*
* Store a password in the secret service.
*
* This is similar to secret_password_store_sync(), but takes a
* #SecretValue as the argument instead of a null terminated password.
* This is similar to [func@password_store_sync], but takes a
* [struct@Value] as the argument instead of a null terminated password.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -558,14 +537,14 @@ secret_password_store_binary_sync (const SecretSchema *schema,
* @collection: (nullable): a collection alias, or D-Bus object path of the
* collection where to store the secret
* @label: label for the secret
* @value: a #SecretValue
* @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object
* @error: location to place an error on failure
*
* Store a password in the secret service.
*
* This is similar to secret_password_storev_sync(), but takes a
* #SecretValue as the argument instead of a null-terminated passwords.
* This is similar to [func@password_storev_sync], but takes a [struct@Value] as
* the argument instead of a null-terminated passwords.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -779,7 +758,7 @@ secret_password_lookupv (const SecretSchema *schema,
* Finish an asynchronous operation to lookup a password in the secret service.
*
* Returns: (transfer full): a new password string stored in nonpageable memory
* which must be freed with secret_password_free() when done
* which must be freed with [func@password_free] when done
*/
gchar *
secret_password_lookup_nonpageable_finish (GAsyncResult *result,
@ -804,8 +783,8 @@ secret_password_lookup_nonpageable_finish (GAsyncResult *result,
*
* Finish an asynchronous operation to lookup a password in the secret service.
*
* Returns: (transfer full): a newly allocated #SecretValue, which should be
* released with secret_value_unref(), or %NULL if no secret found
* Returns: (transfer full): a newly allocated [struct@Value], which should be
* released with [method@Value.unref], or %NULL if no secret found
*
* Since: 0.19.0
*/
@ -827,7 +806,7 @@ secret_password_lookup_binary_finish (GAsyncResult *result,
* Finish an asynchronous operation to lookup a password in the secret service.
*
* Returns: (transfer full): a new password string which should be freed with
* secret_password_free() or may be freed with g_free() when done
* [func@password_free] or may be freed with [func@GLib.free] when done
*/
gchar *
secret_password_lookup_finish (GAsyncResult *result,
@ -865,7 +844,7 @@ secret_password_lookup_finish (GAsyncResult *result,
* threads.
*
* Returns: (transfer full): a new password string which should be freed with
* secret_password_free() or may be freed with g_free() when done
* [func@password_free] or may be freed with [func@GLib.free] when done
*/
gchar *
secret_password_lookup_sync (const SecretSchema *schema,
@ -917,7 +896,7 @@ secret_password_lookup_sync (const SecretSchema *schema,
* threads.
*
* Returns: (transfer full): a new password string stored in nonpageable memory
* which must be freed with secret_password_free() when done
* which must be freed with [func@password_free] when done
*/
gchar *
secret_password_lookup_nonpageable_sync (const SecretSchema *schema,
@ -966,7 +945,7 @@ secret_password_lookup_nonpageable_sync (const SecretSchema *schema,
* threads.
*
* Returns: (transfer full): a new password string stored in non pageable memory
* which should be freed with secret_password_free() when done
* which should be freed with [func@password_free] when done
*/
gchar *
secret_password_lookupv_nonpageable_sync (const SecretSchema *schema,
@ -1010,14 +989,14 @@ secret_password_lookupv_nonpageable_sync (const SecretSchema *schema,
*
* Lookup a password in the secret service.
*
* This is similar to secret_password_lookup_sync(), but returns a
* #SecretValue instead of a null-terminated password.
* This is similar to [func@password_lookup_sync], but returns a
* [struct@Value] instead of a null-terminated password.
*
* This method may block indefinitely and should not be used in user interface
* threads.
*
* Returns: (transfer full): a newly allocated #SecretValue, which should be
* released with secret_value_unref(), or %NULL if no secret found
* Returns: (transfer full): a newly allocated [struct@Value], which should be
* released with [method@Value.unref], or %NULL if no secret found
*
* Since: 0.19.0
*/
@ -1060,14 +1039,14 @@ secret_password_lookup_binary_sync (const SecretSchema *schema,
*
* Lookup a password in the secret service.
*
* This is similar to secret_password_lookupv_sync(), but returns a
* #SecretValue instead of a null-terminated password.
* This is similar to [func@password_lookupv_sync], but returns a
* [struct@Value] instead of a null-terminated password.
*
* This method may block indefinitely and should not be used in user interface
* threads.
*
* Returns: (transfer full): a newly allocated #SecretValue, which should be
* released with secret_value_unref(), or %NULL if no secret found
* Returns: (transfer full): a newly allocated [struct@Value], which should be
* released with [method@Value.unref], or %NULL if no secret found
*
* Since: 0.19.0
*/
@ -1121,7 +1100,7 @@ secret_password_lookupv_binary_sync (const SecretSchema *schema,
* threads.
*
* Returns: (transfer full): a new password string which should be freed with
* secret_password_free() or may be freed with g_free() when done
* [func@password_free] or may be freed with [func@GLib.free] when done
*/
gchar *
secret_password_lookupv_sync (const SecretSchema *schema,
@ -1613,7 +1592,7 @@ secret_password_searchv (const SecretSchema *schema,
* Finish an asynchronous operation to search for items in the secret service.
*
* Returns: (transfer full) (element-type Secret.Retrievable): a list of
* #SecretRetrievable containing attributes of the matched items
* [iface@Retrievable] containing attributes of the matched items
*
* Since: 0.19.0
*/
@ -1648,7 +1627,7 @@ secret_password_search_finish (GAsyncResult *result,
* threads.
*
* Returns: (transfer full) (element-type Secret.Retrievable): a list of
* #SecretRetrievable containing attributes of the matched items
* [iface@Retrievable] containing attributes of the matched items
*
* Since: 0.19.0
*/
@ -1701,7 +1680,7 @@ secret_password_search_sync (const SecretSchema *schema,
* threads.
*
* Returns: (transfer full) (element-type Secret.Retrievable): a list of
* #SecretRetrievable containing attributes of the matched items
* [iface@Retrievable] containing attributes of the matched items
*
* Since: 0.19.0
*/
@ -1746,9 +1725,9 @@ secret_password_searchv_sync (const SecretSchema *schema,
* Clear the memory used by a password, and then free it.
*
* This function must be used to free nonpageable memory returned by
* secret_password_lookup_nonpageable_finish(),
* secret_password_lookup_nonpageable_sync() or
* secret_password_lookupv_nonpageable_sync().
* [func@password_lookup_nonpageable_finish],
* [func@password_lookup_nonpageable_sync] or
* [func@password_lookupv_nonpageable_sync].
*/
void
secret_password_free (gchar *password)

192
libsecret/secret-paths.c
View File

@ -23,22 +23,6 @@
#include "secret-value.h"
/**
* SECTION:secret-paths
* @title: DBus Path Related Functions
* @short_description: Secret Service functions which operate on DBus object paths
*
* These are low level functions which operate on DBus object paths of
* collections or items, instead of the #SecretCollection or #SecretItem
* objects themselves.
*
* You can use these functions if you wish to manage access to the secret
* service using the DBus API directly, and only wish to use a few calls
* in libsecret.
*
* Stability: Unstable
*/
/**
* secret_collection_new_for_dbus_path: (skip)
* @service: (nullable): a secret service object
@ -50,8 +34,8 @@
*
* Get a new collection proxy for a collection in the secret service.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*
@ -95,7 +79,7 @@ secret_collection_new_for_dbus_path (SecretService *service,
* collection in the secret service.
*
* Returns: (transfer full): the new collection, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretCollection *
secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
@ -128,8 +112,8 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
*
* Get a new collection proxy for a collection in the secret service.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [funcService.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -137,7 +121,7 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
* Stability: Unstable
*
* Returns: (transfer full): the new collection, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretCollection *
secret_collection_new_for_dbus_path_sync (SecretService *service,
@ -179,8 +163,8 @@ secret_collection_new_for_dbus_path_sync (SecretService *service,
*
* Get a new item proxy for a secret item in the secret service.
*
* If @service is %NULL, then secret_service_get() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [funcService.get] will be called to get
* the default [class@Service] proxy.
*
* This method will return immediately and complete asynchronously.
*
@ -226,7 +210,7 @@ secret_item_new_for_dbus_path (SecretService *service,
* Stability: Unstable
*
* Returns: (transfer full): the new item, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretItem *
secret_item_new_for_dbus_path_finish (GAsyncResult *result,
@ -256,8 +240,8 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result,
*
* Get a new item proxy for a secret item in the secret service.
*
* If @service is %NULL, then secret_service_get_sync() will be called to get
* the default #SecretService proxy.
* If @service is %NULL, then [funcService.get_sync] will be called to get
* the default [class@Service] proxy.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -265,7 +249,7 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result,
* Stability: Unstable
*
* Returns: (transfer full): the new item, which should be unreferenced
* with g_object_unref()
* with [method@GObject.Object.unref]
*/
SecretItem *
secret_item_new_for_dbus_path_sync (SecretService *service,
@ -332,10 +316,10 @@ on_search_items_complete (GObject *source,
*
* This function returns immediately and completes asynchronously.
*
* When your callback is called use secret_collection_search_for_dbus_paths_finish()
* When your callback is called use [method@Collection.search_for_dbus_paths_finish]
* to get the results of this function. Only the DBus object paths of the
* items will be returned. If you would like #SecretItem objects to be returned
* instead, then use the secret_collection_search() function.
* items will be returned. If you would like [class@Item] objects to be returned
* instead, then use the [method@Collection.search] function.
*
* Stability: Unstable
*/
@ -382,13 +366,13 @@ secret_collection_search_for_dbus_paths (SecretCollection *collection,
* Complete asynchronous operation to search for items in a collection.
*
* DBus object paths of the items will be returned. If you would to have
* #SecretItem objects to be returned instead, then use the
* secret_collection_search() and secret_collection_search_finish() functions.
* [class@Item] objects to be returned instead, then use the
* [method@Collection.search] and [method@Collection.search_finish] functions.
*
* Stability: Unstable
*
* Returns: (transfer full) (array zero-terminated=1): an array of DBus object
* paths for matching items.
* paths for matching items.
*/
gchar **
secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
@ -429,13 +413,13 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
* in user interface threads.
*
* DBus object paths of the items will be returned. If you would to have
* #SecretItem objects to be returned instead, then use the
* secret_collection_search_sync() function.
* [class@Item] objects to be returned instead, then use the
* [method@Collection.search_sync] function.
*
* Stability: Unstable
*
* Returns: (transfer full) (array zero-terminated=1): an array of DBus object
* paths for matching items.
* paths for matching items.
*/
gchar **
secret_collection_search_for_dbus_paths_sync (SecretCollection *collection,
@ -483,10 +467,10 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection,
*
* This function returns immediately and completes asynchronously.
*
* When your callback is called use secret_service_search_for_dbus_paths_finish()
* When your callback is called use [method@Service.search_for_dbus_paths_finish]
* to get the results of this function. Only the D-Bus object paths of the
* items will be returned. If you would like #SecretItem objects to be returned
* instead, then use the secret_service_search() function.
* items will be returned. If you would like [class@Item] objects to be returned
* instead, then use the [method@Service.search] function.
*
* Stability: Unstable
*/
@ -558,9 +542,9 @@ _secret_service_search_for_paths_variant (SecretService *self,
* in the @locked or @unlocked arrays respectively.
*
* D-Bus object paths of the items will be returned in the @unlocked or
* @locked arrays. If you would to have #SecretItem objects to be returned
* instead, then us the secret_service_search() and
* secret_service_search_finish() functions.
* @locked arrays. If you would to have [class@Item] objects to be returned
* instead, then us the [method@Service.search] and
* [method@Service.search_finish] functions.
*
* Stability: Unstable
*
@ -626,8 +610,8 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
* in the @locked or @unlocked arrays respectively.
*
* D-Bus object paths of the items will be returned in the @unlocked or
* @locked arrays. If you would to have #SecretItem objects to be returned
* instead, then use the secret_service_search_sync() function.
* @locked arrays. If you would to have [class@Item] objects to be returned
* instead, then use the [method@Service.search_sync] function.
*
* Stability: Unstable
*
@ -736,7 +720,7 @@ on_get_secrets_session (GObject *source,
* Get the secret value for a secret item stored in the service.
*
* The item is represented by its D-Bus object path. If you already have a
* #SecretItem proxy object, use use secret_item_get_secret() to more simply
* [class@Item] proxy object, use use [method@Item.get_secret] to more simply
* get its secret value.
*
* This function returns immediately and completes asynchronously.
@ -784,7 +768,7 @@ secret_service_get_secret_for_dbus_path (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (nullable): the newly allocated secret value
* for the item, which should be released with secret_value_unref()
* for the item, which should be released with [method@Value.unref]
*/
SecretValue *
secret_service_get_secret_for_dbus_path_finish (SecretService *self,
@ -818,7 +802,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self,
* Get the secret value for a secret item stored in the service.
*
* The item is represented by its D-Bus object path. If you already have a
* #SecretItem proxy object, use use secret_item_load_secret_sync() to more simply
* [class@Item] proxy object, use use [method@Item.load_secret_sync] to more simply
* get its secret value.
*
* This method may block indefinitely and should not be used in user interface
@ -829,7 +813,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (nullable): the newly allocated secret value
* for the item, which should be released with secret_value_unref()
* the item, which should be released with [method@Value.unref]
*/
SecretValue *
secret_service_get_secret_for_dbus_path_sync (SecretService *self,
@ -872,7 +856,7 @@ secret_service_get_secret_for_dbus_path_sync (SecretService *self,
* Get the secret values for a secret item stored in the service.
*
* The items are represented by their D-Bus object paths. If you already have
* #SecretItem proxy objects, use use secret_item_load_secrets() to more simply
* [class@Item] proxy objects, use use [func@Item.load_secrets] to more simply
* get their secret values.
*
* This function returns immediately and completes asynchronously.
@ -920,8 +904,8 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue
* values.
* allocated hash table of item_path keys to [struct@Value]
* values.
*/
GHashTable *
secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
@ -955,7 +939,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
* Get the secret values for a secret item stored in the service.
*
* The items are represented by their D-Bus object paths. If you already have
* #SecretItem proxy objects, use use secret_item_load_secrets_sync() to more
* [class@Item] proxy objects, use use [func@Item.load_secrets_sync] to more
* simply get their secret values.
*
* This method may block indefinitely and should not be used in user interface
@ -966,8 +950,8 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue
* values.
* allocated hash table of item_path keys to [struct@Value]
* values.
*/
GHashTable *
secret_service_get_secrets_for_dbus_paths_sync (SecretService *self,
@ -1158,15 +1142,15 @@ _secret_service_xlock_paths_finish (SecretService *self,
* Lock items or collections in the secret service.
*
* The items or collections are represented by their D-Bus object paths. If you
* already have #SecretItem and #SecretCollection proxy objects, use use
* secret_service_lock_sync() instead.
* already have [class@Item] and [class@Collection] proxy objects, use use
* [method@Service.lock_sync] instead.
*
* The secret service may not be able to lock items individually, and may
* lock an entire collection instead.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*
* Stability: Unstable
*
@ -1215,14 +1199,14 @@ secret_service_lock_dbus_paths_sync (SecretService *self,
* Lock items or collections in the secret service.
*
* The items or collections are represented by their D-Bus object paths. If you
* already have #SecretItem and #SecretCollection proxy objects, use use
* secret_service_lock() instead.
* already have [class@Item] and [class@Collection] proxy objects, use use
* [method@Service.lock] instead.
*
* The secret service may not be able to lock items individually, and may
* lock an entire collection instead.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that show up.
*
* Stability: Unstable
@ -1288,15 +1272,15 @@ secret_service_lock_dbus_paths_finish (SecretService *self,
* Unlock items or collections in the secret service.
*
* The items or collections are represented by their D-Bus object paths. If you
* already have #SecretItem and #SecretCollection proxy objects, use use
* secret_service_unlock_sync() instead.
* already have [class@Item] and [class@Collection] proxy objects, use use
* [method@Service.unlock_sync] instead.
*
* The secret service may not be able to unlock items individually, and may
* unlock an entire collection instead.
*
* This method may block indefinitely and should not be used in user
* interface threads. The secret service may prompt the user.
* secret_service_prompt() will be used to handle any prompts that show up.
* [method@Service.prompt] will be used to handle any prompts that show up.
*
* Stability: Unstable
*
@ -1346,14 +1330,14 @@ secret_service_unlock_dbus_paths_sync (SecretService *self,
* Unlock items or collections in the secret service.
*
* The items or collections are represented by their D-Bus object paths. If you
* already have #SecretItem and #SecretCollection proxy objects, use use
* secret_service_unlock() instead.
* already have [class@Item] and [class@Collection] proxy objects, use use
* [method@Service.unlock] instead.
*
* The secret service may not be able to unlock items individually, and may
* unlock an entire collection instead.
*
* This method returns immediately and completes asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that show up.
*
* Stability: Unstable
@ -1540,7 +1524,7 @@ _secret_service_delete_path_finish (SecretService *self,
* Delete a secret item from the secret service.
*
* The item is represented by its D-Bus object path. If you already have a
* #SecretItem proxy objects, use use secret_item_delete() instead.
* [class@Item] proxy objects, use use [method@Item.delete] instead.
*
* This method will return immediately and complete asynchronously.
*
@ -1591,7 +1575,7 @@ secret_service_delete_item_dbus_path_finish (SecretService *self,
* Delete a secret item from the secret service.
*
* The item is represented by its D-Bus object path. If you already have a
* #SecretItem proxy objects, use use secret_item_delete_sync() instead.
* [class@Item] proxy objects, use use [method@Item.delete_sync] instead.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -1716,7 +1700,7 @@ on_create_collection_called (GObject *source,
*
* Using this method requires that you setup a correct hash table of D-Bus
* properties for the new collection. You may prefer to use
* secret_collection_create() which does handles this for you.
* [func@Collection.create] which does handles this for you.
*
* An @alias is a well-known tag for a collection, such as 'default' (ie: the
* default collection to store items in). This allows other applications to
@ -1727,13 +1711,13 @@ on_create_collection_called (GObject *source,
*
* @properties is a set of properties for the new collection. The keys in the
* hash table should be interface.property strings like
* <literal>org.freedesktop.Secret.Collection.Label</literal>. The values
* in the hash table should be #GVariant values of the properties.
* `org.freedesktop.Secret.Collection.Label`. The values
* in the hash table should be [struct@GLib.Variant] values of the properties.
*
* If you wish to have a
*
* This method will return immediately and complete asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that are required.
*
* Stability: Unstable
@ -1794,7 +1778,7 @@ secret_service_create_collection_dbus_path (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full): a new string containing the D-Bus object path
* of the collection
* of the collection
*/
gchar *
secret_service_create_collection_dbus_path_finish (SecretService *self,
@ -1832,7 +1816,7 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
*
* Using this method requires that you setup a correct hash table of D-Bus
* properties for the new collection. You may prefer to use
* secret_collection_create() which does handles this for you.
* [func@Collection.create] which does handles this for you.
*
* An @alias is a well-known tag for a collection, such as 'default' (ie: the
* default collection to store items in). This allows other applications to
@ -1843,11 +1827,11 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
*
* @properties is a set of properties for the new collection. The keys in the
* hash table should be interface.property strings like
* <literal>org.freedesktop.Secret.Collection.Label</literal>. The values
* in the hash table should be #GVariant values of the properties.
* `org.freedesktop.Secret.Collection.Label`. The values
* in the hash table should be [struct@GLib.Variant] values of the properties.
*
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. secret_service_prompt()
* threads. The secret service may prompt the user. [method@Service.prompt]
* will be used to handle any prompts that are required.
*
* Stability: Unstable
@ -2018,7 +2002,7 @@ on_create_item_session (GObject *source,
* Create a new item in a secret service collection and return its D-Bus
* object path.
*
* It is often easier to use secret_password_store() or secret_item_create()
* It is often easier to use [func@password_store] or [func@Item.create]
* rather than using this function. Using this method requires that you setup
* a correct hash table of D-Bus @properties for the new collection.
*
@ -2028,11 +2012,11 @@ on_create_item_session (GObject *source,
*
* @properties is a set of properties for the new collection. The keys in the
* hash table should be interface.property strings like
* <literal>org.freedesktop.Secret.Item.Label</literal>. The values
* in the hash table should be #GVariant values of the properties.
* `org.freedesktop.Secret.Item.Label`. The values
* in the hash table should be [struct@GLib.Variant] values of the properties.
*
* This method will return immediately and complete asynchronously. The secret
* service may prompt the user. secret_service_prompt() will be used to handle
* service may prompt the user. [method@Service.prompt] will be used to handle
* any prompts that are required.
*
* Stability: Unstable
@ -2085,7 +2069,7 @@ secret_service_create_item_dbus_path (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full): a new string containing the D-Bus object path
* of the item
* of the item
*/
gchar *
secret_service_create_item_dbus_path_finish (SecretService *self,
@ -2139,7 +2123,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
* Create a new item in a secret service collection and return its D-Bus
* object path.
*
* It is often easier to use secret_password_store_sync() or secret_item_create_sync()
* It is often easier to use [func@password_store_sync] or [func@Item.create_sync]
* rather than using this function. Using this method requires that you setup
* a correct hash table of D-Bus @properties for the new collection.
*
@ -2149,11 +2133,11 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
*
* @properties is a set of properties for the new collection. The keys in the
* hash table should be interface.property strings like
* <literal>org.freedesktop.Secret.Item.Label</literal>. The values
* in the hash table should be #GVariant values of the properties.
* `org.freedesktop.Secret.Item.Label`. The values
* in the hash table should be [struct@GLib.Variant] values of the properties.
*
* This method may block indefinitely and should not be used in user interface
* threads. The secret service may prompt the user. secret_service_prompt()
* threads. The secret service may prompt the user. [method@Service.prompt]
* will be used to handle any prompts that are required.
*
* Stability: Unstable
@ -2240,7 +2224,7 @@ secret_service_read_alias_dbus_path (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (nullable): the collection dbus object path,
* or %NULL if none assigned to the alias
* or %NULL if none assigned to the alias
*/
gchar *
secret_service_read_alias_dbus_path_finish (SecretService *self,
@ -2449,11 +2433,11 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self,
* @return_type: (nullable): the variant type of the prompt result
* @error: location to place error on failure
*
* Perform prompting for a #SecretPrompt.
* Perform prompting for a [class@Prompt].
*
* Override the #SecretServiceClass <literal>prompt_async</literal> virtual method
* Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method
* to change the behavior of the propmting. The default behavior is to simply
* run secret_prompt_perform() on the prompt.
* run [method@Prompt.perform] on the prompt.
*
* Returns a variant result if the prompt was completed and not dismissed. The
* type of result depends on the action the prompt is completing, and is defined
@ -2464,7 +2448,7 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an
* error occurred, a variant result if the prompt was successful
* error occurred, a variant result if the prompt was successful
*/
GVariant *
secret_service_prompt_at_dbus_path_sync (SecretService *self,
@ -2497,14 +2481,14 @@ secret_service_prompt_at_dbus_path_sync (SecretService *self,
* @callback: called when the operation completes
* @user_data: data to be passed to the callback
*
* Perform prompting for a #SecretPrompt.
* Perform prompting for a [class@Prompt].
*
* This function is called by other parts of this library to handle prompts
* for the various actions that can require prompting.
*
* Override the #SecretServiceClass <literal>prompt_async</literal> virtual method
* Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method
* to change the behavior of the propmting. The default behavior is to simply
* run secret_prompt_perform() on the prompt.
* run [method@Prompt.perform] on the prompt.
*
* Stability: Unstable
*/
@ -2533,7 +2517,7 @@ secret_service_prompt_at_dbus_path (SecretService *self,
* @result: the asynchronous result passed to the callback
* @error: location to place an error on failure
*
* Complete asynchronous operation to perform prompting for a #SecretPrompt.
* Complete asynchronous operation to perform prompting for a [class@Prompt].
*
* Returns a variant result if the prompt was completed and not dismissed. The
* type of result depends on the action the prompt is completing, and is defined
@ -2542,7 +2526,7 @@ secret_service_prompt_at_dbus_path (SecretService *self,
* Stability: Unstable
*
* Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an
* error occurred, a variant result if the prompt was successful
* error occurred, a variant result if the prompt was successful
*/
GVariant *
secret_service_prompt_at_dbus_path_finish (SecretService *self,
@ -2561,12 +2545,12 @@ secret_service_prompt_at_dbus_path_finish (SecretService *self,
* @service: the service
* @value: the secret value
*
* Encodes a #SecretValue into GVariant for use with the Secret Service
* DBus API.
* Encodes a [struct@Value] into [struct@GLib.Variant] for use with the Secret
* Service DBus API.
*
* The resulting GVariant will have a <literal>(oayays)</literal> signature.
* The resulting [struct@GLib.Variant] will have a `(oayays)` signature.
*
* A session must have already been established by the #SecretService.
* A session must have already been established by the [class@Service].
*
* Returns: (transfer floating): the encoded secret
*/
@ -2590,12 +2574,12 @@ secret_service_encode_dbus_secret (SecretService *service,
* @service: the service
* @value: the encoded secret
*
* Decode a #SecretValue into GVariant received with the Secret Service
* Decode a [struct@Value] into [struct@GLib.Variant] received with the Secret Service
* DBus API.
*
* The GVariant should have a <literal>(oayays)</literal> signature.
* The [struct@GLib.Variant] should have a `(oayays)` signature.
*
* A session must have already been established by the #SecretService, and
* A session must have already been established by the [class@Service], and
* the encoded secret must be valid for that session.
*
* Returns: (transfer full): the decoded secret value

48
libsecret/secret-prompt.c
View File

@ -22,32 +22,26 @@
#include <glib/gi18n-lib.h>
/**
* SECTION:secret-prompt
* @title: SecretPrompt
* @short_description: a prompt in the Service
* SecretPrompt:
*
* A #SecretPrompt represents a prompt in the Secret Service.
* A prompt in the Service
*
* A proxy object representing a prompt that the Secret Service will display
* to the user.
*
* Certain actions on the Secret Service require user prompting to complete,
* such as creating a collection, or unlocking a collection. When such a prompt
* is necessary, then a #SecretPrompt object is created by this library, and
* passed to the secret_service_prompt() method. In this way it is handled
* passed to the [method@Service.prompt] method. In this way it is handled
* automatically.
*
* In order to customize prompt handling, override the
* SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
* virtual methods of the #SecretService class.
* [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual
* methods of the [class@Service] class.
*
* Stability: Stable
*/
/**
* SecretPrompt:
*
* A proxy object representing a prompt that the Secret Service will display
* to the user.
*/
/**
* SecretPromptClass:
* @parent_class: the parent class
@ -131,10 +125,10 @@ _secret_prompt_instance (SecretService *service,
* API specification.
*
* If @window_id is non-null then it is used as an XWindow id on Linux. The API
* expects this id to be converted to a string using the <literal>%d</literal>
* printf format. The Secret Service can make its prompt transient for the window
* with this id. In some Secret Service implementations this is not possible, so
* the behavior depending on this should degrade gracefully.
* expects this id to be converted to a string using the `%d` printf format. The
* Secret Service can make its prompt transient for the window with this id. In
* some Secret Service implementations this is not possible, so the behavior
* depending on this should degrade gracefully.
*
* This runs the dialog in a recursive mainloop. When run from a user interface
* thread, this means the user interface will remain responsive. Care should be
@ -191,10 +185,10 @@ secret_prompt_run (SecretPrompt *self,
* API specification.
*
* If @window_id is non-null then it is used as an XWindow id on Linux. The API
* expects this id to be converted to a string using the <literal>%d</literal>
* printf format. The Secret Service can make its prompt transient for the window
* with this id. In some Secret Service implementations this is not possible,
* so the behavior depending on this should degrade gracefully.
* expects this id to be converted to a string using the `%d` printf format. The
* Secret Service can make its prompt transient for the window with this id. In
* some Secret Service implementations this is not possible, so the behavior
* depending on this should degrade gracefully.
*
* This method may block indefinitely and should not be used in user interface
* threads.
@ -412,10 +406,10 @@ on_prompt_cancelled (GCancellable *cancellable,
* was completed and not dismissed.
*
* If @window_id is non-null then it is used as an XWindow id on Linux. The API
* expects this id to be converted to a string using the <literal>%d</literal>
* printf format. The Secret Service can make its prompt transient for the window
* with this id. In some Secret Service implementations this is not possible, so
* the behavior depending on this should degrade gracefully.
* expects this id to be converted to a string using the `%d` printf format. The
* Secret Service can make its prompt transient for the window with this id. In
* some Secret Service implementations this is not possible, so the behavior
* depending on this should degrade gracefully.
*
* This method will return immediately and complete asynchronously.
*/
@ -505,7 +499,7 @@ secret_prompt_perform (SecretPrompt *self,
* defined in the Secret Service DBus API specification.
*
* Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred,
* a variant result if the prompt was successful
* a variant result if the prompt was successful
*/
GVariant *
secret_prompt_perform_finish (SecretPrompt *self,

40
libsecret/secret-retrievable.c
View File

@ -18,16 +18,16 @@
#include "secret-private.h"
/**
* SECTION:secret-retrievable
* @title: SecretRetrievable
* @short_description: A read-only secret item
* SecretRetrievable
*
* A read-only secret item
*
* #SecretRetrievable provides a read-only view of a secret item
* stored in the Secret Service.
*
* Each item has a value, represented by a #SecretValue, which can be
* retrieved by secret_retrievable_retrieve_secret() and
* secret_retrievable_retrieve_secret_finish().
* Each item has a value, represented by a [struct@Value], which can be
* retrieved by [method@Retrievable.retrieve_secret] and
* [method@Retrievable.retrieve_secret_finish].
*
* Stability: Stable
*/
@ -44,10 +44,10 @@
/**
* SecretRetrievableInterface:
* @parent_iface: the parent interface
* @retrieve_secret: implementation of secret_retrievable_retrieve_secret(),
* @retrieve_secret: implementation of [method@Retrievable.retrieve_secret],
* required
* @retrieve_secret_finish: implementation of
* secret_retrievable_retrieve_secret_finish(), required
* [method@Retrievable.retrieve_secret_finish], required
*
* The interface for #SecretRetrievable.
*
@ -60,7 +60,7 @@ static void
secret_retrievable_default_init (SecretRetrievableInterface *iface)
{
/**
* SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full)
* SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) (attributes org.gtk.Property.get=secret_retrievable_get_attributes)
*
* The attributes set on this item. Attributes are used to locate an
* item. They are not guaranteed to be stored or transferred securely.
@ -72,7 +72,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface)
G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretRetrievable:label:
* SecretRetrievable:label: (attributes org.gtk.Property.get=secret_retrievable_get_label)
*
* The human readable label for the item.
*
@ -83,7 +83,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface)
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretRetrievable:created:
* SecretRetrievable:created: (attributes org.gtk.Property.get=secret_retrievable_get_created)
*
* The date and time (in seconds since the UNIX epoch) that this
* item was created.
@ -95,7 +95,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface)
0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretRetrievable:modified:
* SecretRetrievable:modified: (attributes org.gtk.Property.get=secret_retrievable_get_modified)
*
* The date and time (in seconds since the UNIX epoch) that this
* item was last modified.
@ -146,7 +146,7 @@ secret_retrievable_retrieve_secret (SecretRetrievable *self,
* Complete asynchronous operation to retrieve the secret value of this object.
*
* Returns: (transfer full) (nullable): the secret value which should be
* released with secret_value_unref(), or %NULL
* released with [method@Value.unref], or %NULL
*
* Since: 0.19.0
*/
@ -178,7 +178,7 @@ secret_retrievable_retrieve_secret_finish (SecretRetrievable *self,
* threads.
*
* Returns: (transfer full) (nullable): the secret value which should be
* released with secret_value_unref(), or %NULL
* released with [method@Value.unref], or %NULL
*
* Since: 0.19.0
*/
@ -213,7 +213,7 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self,
}
/**
* secret_retrievable_get_attributes:
* secret_retrievable_get_attributes: (attributes org.gtk.Method.get_property=attributes)
* @self: a retrievable object
*
* Get the attributes of this object.
@ -225,8 +225,8 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self,
* Do not modify the attribute returned by this method.
*
* Returns: (transfer full) (element-type utf8 utf8): a new reference
* to the attributes, which should not be modified, and
* released with g_hash_table_unref()
* to the attributes, which should not be modified, and
* released with [func@GLib.HashTable.unref]
*
* Since: 0.19.0
*/
@ -247,7 +247,7 @@ secret_retrievable_get_attributes (SecretRetrievable *self)
*
* Get the label of this item.
*
* Returns: (transfer full): the label, which should be freed with g_free()
* Returns: (transfer full): the label, which should be freed with [func@GLib.free]
*
* Since: 0.19.0
*/
@ -263,7 +263,7 @@ secret_retrievable_get_label (SecretRetrievable *self)
}
/**
* secret_retrievable_get_created:
* secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created)
* @self: a retrievable object
*
* Get the created date and time of the object. The return value is
@ -285,7 +285,7 @@ secret_retrievable_get_created (SecretRetrievable *self)
}
/**
* secret_retrievable_get_modified:
* secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified)
* @self: a retrievable object
*
* Get the modified date and time of the object. The return value is

90
libsecret/secret-schema.c
View File

@ -22,82 +22,6 @@
#include "egg/egg-secure-memory.h"
/**
* SECTION:secret-schema
* @title: SecretSchema
* @short_description: Schema for defining which attributes are on items
*
* Each password is associated with a set of attributes. Attribute values can
* be either strings, integers or booleans.
*
* The names and types of allowed attributes for a given password are defined
* with a schema.
*
* Additional schemas can be defined via the %SecretSchema structure like this:
*
* <informalexample><programlisting language="c">
* /<!-- -->* in a header: *<!-- -->/
*
* const SecretSchema * example_get_schema (void) G_GNUC_CONST;
*
* #define EXAMPLE_SCHEMA example_get_schema ()
*
*
* /<!-- -->* in a .c file: *<!-- -->/
*
* const SecretSchema *
* example_get_schema (void)
* {
* static const SecretSchema the_schema = {
* "org.example.Password", SECRET_SCHEMA_NONE,
* {
* { "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
* { "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
* { "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
* { NULL, 0 },
* }
* };
* return &the_schema;
* }
* </programlisting></informalexample>
*
* Stability: Stable
*/
/**
* SecretSchema:
* @name: the dotted name of the schema
* @flags: flags for the schema
* @attributes: the attribute names and types of those attributes
*
* Represents a set of attributes that are stored with an item. These schemas
* are used for interoperability between various services storing the same types
* of items.
*
* Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines
* a set of attributes, and types (string, integer, boolean) for those attributes.
*
* Attributes are stored as strings in the Secret Service, and the attribute
* types simply define standard ways to store integer and boolean values as strings.
* Attributes are represented in libsecret via a #GHashTable with string keys and
* values. Even for values that defined as an integer or boolean in the schema,
* the attribute values in the #GHashTable are strings. Boolean values are stored
* as the strings 'true' and 'false'. Integer values are stored in decimal, with
* a preceding negative sign for negative integers.
*
* Schemas are handled entirely on the client side by this library. The name of the
* schema is automatically stored as an attribute on the item.
*
* Normally when looking up passwords only those with matching schema names are
* returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag,
* then lookups will not check that the schema name matches that on the item, only
* the schema's attributes are matched. This is useful when you are looking up items
* that are not stored by the libsecret library. Other libraries such as libgnome-keyring
* don't store the schema name.
*
* Stability: Stable
*/
/**
* SecretSchemaFlags:
* @SECRET_SCHEMA_NONE: no flags for the schema
@ -161,12 +85,12 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute,
* schemas are used for interoperability between various services storing the
* same types of items.
*
* Each schema has an @name like "org.gnome.keyring.NetworkPassword", and
* Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and
* defines a set of attributes names, and types (string, integer, boolean) for
* those attributes.
*
* Each key in the @attributes table should be a attribute name strings, and
* the values in the table should be integers from the #SecretSchemaAttributeType
* the values in the table should be integers from the [enum@SchemaAttributeType]
* enumeration, representing the attribute type for each attribute name.
*
* Normally when looking up passwords only those with matching schema names are
@ -177,7 +101,7 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute,
* don't store the schema name.
*
* Returns: (transfer full): the new schema, which should be unreferenced with
* secret_schema_unref() when done
* [method@Schema.unref] when done
*/
SecretSchema *
secret_schema_newv (const gchar *name,
@ -244,13 +168,13 @@ secret_schema_newv (const gchar *name,
* schemas are used for interoperability between various services storing the
* same types of items.
*
* Each schema has an @name like "org.gnome.keyring.NetworkPassword", and
* Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and
* defines a set of attributes names, and types (string, integer, boolean) for
* those attributes.
*
* The variable argument list should contain pairs of a) The attribute name as
* a null-terminated string, followed by b) integers from the
* #SecretSchemaAttributeType enumeration, representing the attribute type for
* [enum@SchemaAttributeType] enumeration, representing the attribute type for
* each attribute name. The list of attributes should be terminated with a %NULL.
*
* Normally when looking up passwords only those with matching schema names are
@ -261,7 +185,7 @@ secret_schema_newv (const gchar *name,
* don't store the schema name.
*
* Returns: (transfer full): the new schema, which should be unreferenced with
* secret_schema_unref() when done
* [method@Schema.unref] when done
*/
SecretSchema *
secret_schema_new (const gchar *name,
@ -304,7 +228,7 @@ secret_schema_new (const gchar *name,
* allocated, then this function will copy the schema.
*
* Returns: (transfer full): the referenced schema, which should be later
* unreferenced with secret_schema_unref()
* unreferenced with [method@Schema.unref]
*/
SecretSchema *
secret_schema_ref (SecretSchema *schema)

44
libsecret/secret-schemas.c
View File

@ -17,18 +17,6 @@
#include "secret-schema.h"
#include "secret-schemas.h"
/**
* SECRET_SCHEMA_NOTE: (skip)
*
* A predefined schema for personal passwords stored by the user in the
* password manager. This schema has no attributes, and the items are not
* meant to be used automatically by applications.
*
* When used to search for items using this schema, it will only match
* items that have the same schema. Items stored via libgnome-keyring with the
* <literal>GNOME_KEYRING_ITEM_NOTE</literal> item type will match.
*/
static const SecretSchema note_schema = {
"org.gnome.keyring.Note",
SECRET_SCHEMA_NONE,
@ -39,37 +27,6 @@ static const SecretSchema note_schema = {
const SecretSchema * SECRET_SCHEMA_NOTE = &note_schema;
/**
* SECRET_SCHEMA_COMPAT_NETWORK: (skip)
*
* A predefined schema that is compatible with items stored via the
* libgnome-keyring 'network password' functions. This is meant to be used by
* applications migrating from libgnome-keyring which stored their secrets as
* 'network passwords'. It is not recommended that new code use this schema.
*
* When used to search for items using this schema, it will only match
* items that have the same schema. Items stored via libgnome-keyring with the
* <literal>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</literal> item type will match.
*
* The following attributes exist in the schema:
* <variablelist><title>Attributes:</title>
* <varlistentry><term><literal>user</literal>:</term>
* <listitem><para>The user name (string).</para></listitem></varlistentry>
* <varlistentry><term><literal>domain</literal>:</term>
* <listitem><para>The login domain or realm (string).</para></listitem></varlistentry>
* <varlistentry><term><literal>object</literal>:</term>
* <listitem><para>The object or path (string).</para></listitem></varlistentry>
* <varlistentry><term><literal>protocol</literal>:</term>
* <listitem><para>The protocol (a string like 'http').</para></listitem></varlistentry>
* <varlistentry><term><literal>port</literal>:</term>
* <listitem><para>The network port (integer).</para></listitem></varlistentry>
* <varlistentry><term><literal>server</literal>:</term>
* <listitem><para>The hostname or server (string).</para></listitem></varlistentry>
* <varlistentry><term><literal>authtype</literal>:</term>
* <listitem><para>The authentication type (string).</para></listitem></varlistentry>
* </variablelist>
*/
static const SecretSchema network_schema = {
"org.gnome.keyring.NetworkPassword",
SECRET_SCHEMA_NONE,
@ -97,6 +54,7 @@ const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK = &network_schema;
* language bindings cannot, and must use this accessor.
*
* Returns: (transfer none): schema type
*
* Since: 0.18.6
*/
const SecretSchema *

61
libsecret/secret-schemas.h
View File

@ -39,12 +39,67 @@ extern const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK;
/**
* SecretSchemaType:
* @SECRET_SCHEMA_TYPE_NOTE: Personal passwords; see %SECRET_SCHEMA_NOTE
* @SECRET_SCHEMA_TYPE_NOTE: Personal passwords
* @SECRET_SCHEMA_TYPE_COMPAT_NETWORK: Network passwords from older
* libgnome-keyring storage; see %SECRET_SCHEMA_COMPAT_NETWORK
* libgnome-keyring storage
*
* Different types of schemas for storing secrets, intended for use with
* secret_get_schema().
* [func@get_schema].
*
* ## @SECRET_SCHEMA_NOTE
*
* A predefined schema for personal passwords stored by the user in the
* password manager. This schema has no attributes, and the items are not
* meant to be used automatically by applications.
*
* When used to search for items using this schema, it will only match
* items that have the same schema. Items stored via libgnome-keyring with the
* `GNOME_KEYRING_ITEM_NOTE` item type will match.
*
* ## @SECRET_SCHEMA_COMPAT_NETWORK
*
* A predefined schema that is compatible with items stored via the
* libgnome-keyring 'network password' functions. This is meant to be used by
* applications migrating from libgnome-keyring which stored their secrets as
* 'network passwords'. It is not recommended that new code use this schema.
*
* When used to search for items using this schema, it will only match
* items that have the same schema. Items stored via libgnome-keyring with the
* `GNOME_KEYRING_ITEM_NETWORK_PASSWORD` item type will match.
*
* The following attributes exist in the schema:
*
* ### Attributes:
*
* <table>
* <tr>
* <td><tt>user</tt>:</td>
* <td>The user name (string).</td>
* </tr>
* <tr>
* <td><tt>domain</tt>:</td>
* <td>The login domain or realm (string).</td></tr>
* <tr>
* <td><tt>object</tt>:</td>
* <td>The object or path (string).</td>
* </tr>
* <tr>
* <td><tt>protocol</tt>:</td>
* <td>The protocol (a string like 'http').</td>
* </tr>
* <tr>
* <td><tt>port</tt>:</td>
* <td>The network port (integer).</td>
* </tr>
* <tr>
* <td><tt>server</tt>:</td>
* <td>The hostname or server (string).</td>
* </tr>
* <tr>
* <td><tt>authtype</tt>:</td>
* <td>The authentication type (string).</td>
* </tr>
* </table>
*
* Since: 0.18.6
*/

121
libsecret/secret-service.c
View File

@ -30,59 +30,54 @@
#include "egg/egg-secure-memory.h"
/**
* SECTION:secret-service
* @title: SecretService
* @short_description: the Secret Service
* SecretService:
*
* A proxy object representing the Secret Service.
*
* A #SecretService object represents the Secret Service implementation which
* runs as a D-Bus service.
*
* Normally a single #SecretService object can be shared between multiple
* callers. The secret_service_get() method is used to access this #SecretService
* callers. The [func@Service.get] method is used to access this #SecretService
* object. If a new independent #SecretService object is required, use
* secret_service_open().
* [func@Service.open].
*
* In order to securely transfer secrets to the Sercret Service, a session
* is established. This session can be established while initializing a
* #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag
* to the secret_service_get() or secret_service_open() functions. In order to
* to the [func@Service.get] or [func@Service.open] functions. In order to
* establish a session on an already existing #SecretService, use the
* secret_service_ensure_session() function.
* [method@Service.ensure_session] function.
*
* To search for items, use the secret_service_search() method.
* To search for items, use the [method@Service.search] method.
*
* Multiple collections can exist in the Secret Service, each of which contains
* secret items. In order to instantiate #SecretCollection objects which
* secret items. In order to instantiate [class@Collection] objects which
* represent those collections while initializing a #SecretService then pass
* the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or
* secret_service_open() functions. In order to establish a session on an already
* existing #SecretService, use the secret_service_load_collections() function.
* To access the list of collections use secret_service_get_collections().
* the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the [func@Service.get] or
* [func@Service.open] functions. In order to establish a session on an already
* existing #SecretService, use the [method@Service.load_collections] function.
* To access the list of collections use [method@Service.get_collections].
*
* Certain actions on the Secret Service require user prompting to complete,
* such as creating a collection, or unlocking a collection. When such a prompt
* is necessary, then a #SecretPrompt object is created by this library, and
* passed to the secret_service_prompt() method. In this way it is handled
* is necessary, then a [class@Prompt] object is created by this library, and
* passed to the [method@Service.prompt] method. In this way it is handled
* automatically.
*
* In order to customize prompt handling, override the <literal>prompt_async</literal>
* and <literal>prompt_finish</literal> virtual methods of the #SecretService class.
* In order to customize prompt handling, override the
* [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual
* methods of the #SecretService class.
*
* Stability: Stable
*/
/**
* SecretService:
*
* A proxy object representing the Secret Service.
*/
/**
* SecretServiceClass:
* @parent_class: the parent class
* @collection_gtype: the #GType of the #SecretCollection objects instantiated
* @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated
* by the #SecretService proxy
* @item_gtype: the #GType of the #SecretItem objects instantiated by the
* @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the
* #SecretService proxy
* @prompt_async: called to perform asynchronous prompting when necessary
* @prompt_finish: called to complete an asynchronous prompt operation
@ -104,7 +99,7 @@
* #SecretService
*
* Flags which determine which parts of the #SecretService proxy are initialized
* during a secret_service_get() or secret_service_open() operation.
* during a [func@Service.get] or [func@Service.open] operation.
*/
EGG_SECURE_DEFINE_GLIB_GLOBALS ();
@ -587,15 +582,15 @@ secret_service_class_init (SecretServiceClass *klass)
g_object_class_override_property (object_class, PROP_FLAGS, "flags");
/**
* SecretService:collections:
* SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections)
*
* A list of #SecretCollection objects representing the collections in
* A list of [class@Collection] objects representing the collections in
* the Secret Service. This list may be %NULL if the collections have
* not been loaded.
*
* To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS
* initialization flag when calling the secret_service_get() or
* secret_service_open() functions. Or call the secret_service_load_collections()
* initialization flag when calling the [func@Service.get] or
* [func@Service.open] functions. Or call the [method@Service.load_collections]
* method.
*/
g_object_class_install_property (object_class, PROP_COLLECTIONS,
@ -1002,7 +997,7 @@ secret_service_get (SecretServiceFlags flags,
* Secret Service.
*
* Returns: (transfer full): a new reference to a #SecretService proxy, which
* should be released with g_object_unref().
* should be released with [method@GObject.Object.unref].
*/
SecretService *
secret_service_get_finish (GAsyncResult *result,
@ -1058,7 +1053,7 @@ secret_service_get_finish (GAsyncResult *result,
* threads.
*
* Returns: (transfer full): a new reference to a #SecretService proxy, which
* should be released with g_object_unref().
* should be released with [method@GObject.Object.unref].
*/
SecretService *
secret_service_get_sync (SecretServiceFlags flags,
@ -1090,8 +1085,8 @@ secret_service_get_sync (SecretServiceFlags flags,
/**
* secret_service_disconnect:
*
* Disconnect the default #SecretService proxy returned by secret_service_get()
* and secret_service_get_sync().
* Disconnect the default #SecretService proxy returned by [func@Service.get]
* and [func@Service.get_sync].
*
* It is not necessary to call this function, but you may choose to do so at
* program exit. It is useful for testing that memory is not leaked.
@ -1117,7 +1112,7 @@ secret_service_disconnect (void)
*
* Create a new #SecretService proxy for the Secret Service.
*
* This function is rarely used, see secret_service_get() instead.
* This function is rarely used, see [func@Service.get] instead.
*
* The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the type
* of a derived class.
@ -1155,7 +1150,7 @@ secret_service_open (GType service_gtype,
* the Secret Service.
*
* Returns: (transfer full): a new reference to a #SecretService proxy, which
* should be released with g_object_unref().
* should be released with [method@GObject.Object.unref].
*/
SecretService *
secret_service_open_finish (GAsyncResult *result,
@ -1188,7 +1183,7 @@ secret_service_open_finish (GAsyncResult *result,
*
* Create a new #SecretService proxy for the Secret Service.
*
* This function is rarely used, see secret_service_get_sync() instead.
* This function is rarely used, see [func@Service.get_sync] instead.
*
* The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the
* type of a derived class.
@ -1202,7 +1197,7 @@ secret_service_open_finish (GAsyncResult *result,
* threads.
*
* Returns: (transfer full): a new reference to a #SecretService proxy, which
* should be released with g_object_unref().
* should be released with [method@GObject.Object.unref].
*/
SecretService *
secret_service_open_sync (GType service_gtype,
@ -1226,7 +1221,7 @@ secret_service_open_sync (GType service_gtype,
* Get the flags representing what features of the #SecretService proxy
* have been initialized.
*
* Use secret_service_ensure_session() or secret_service_load_collections()
* Use [method@Service.ensure_session] or [method@Service.load_collections]
* to initialize further features and change the flags.
*
* Returns: the flags for features initialized
@ -1251,18 +1246,18 @@ secret_service_get_flags (SecretService *self)
}
/**
* secret_service_get_collections:
* secret_service_get_collections: (attributes org.gtk.Method.get_property=collections)
* @self: the secret service proxy
*
* Get a list of #SecretCollection objects representing all the collections
* Get a list of [class@Collection] objects representing all the collections
* in the secret service.
*
* If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when
* initializing #SecretService proxy object, then this method will return
* %NULL. Use secret_service_load_collections() to load the collections.
* %NULL. Use [method@Service.load_collections] to load the collections.
*
* Returns: (transfer full) (element-type Secret.Collection) (nullable): a
* list of the collections in the secret service
* list of the collections in the secret service
*/
GList *
secret_service_get_collections (SecretService *self)
@ -1364,7 +1359,7 @@ _secret_service_take_session (SecretService *self,
* secret service proxy and the Secret Service itself.
*
* This will be %NULL if no session has been established. Use
* secret_service_ensure_session() to establish a session.
* [method@Service.ensure_session] to establish a session.
*
* Returns: (nullable): a string representing the algorithms for transferring
* secrets
@ -1394,10 +1389,10 @@ secret_service_get_session_algorithms (SecretService *self)
* secrets between this secret service proxy and the Secret Service itself.
*
* This will be %NULL if no session has been established. Use
* secret_service_ensure_session() to establish a session.
* [method@Service.ensure_session] to establish a session.
*
* Returns: (nullable): a string representing the D-Bus object path of the
* session
* session
*/
const gchar *
secret_service_get_session_dbus_path (SecretService *self)
@ -1428,7 +1423,7 @@ secret_service_get_session_dbus_path (SecretService *self)
*
* It is not normally necessary to call this method, as the session is
* established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
* to secret_service_get() in order to ensure that a session has been established
* to [func@Service.get] in order to ensure that a session has been established
* by the time you get the #SecretService proxy.
*
* This method will return immediately and complete asynchronously.
@ -1500,7 +1495,7 @@ secret_service_ensure_session_finish (SecretService *self,
*
* It is not normally necessary to call this method, as the session is
* established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
* to secret_service_get_sync() in order to ensure that a session has been
* to [func@Service.get_sync] in order to ensure that a session has been
* established by the time you get the #SecretService proxy.
*
* This method may block indefinitely and should not be used in user interface
@ -1638,10 +1633,10 @@ on_ensure_collection (GObject *source,
*
* Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of
* secret_service_get_collections().
* [method@Service.get_collections].
*
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* secret_service_get_sync() in order to ensure that the collections have been
* [func@Service.get_sync] in order to ensure that the collections have been
* loaded by the time you get the #SecretService proxy.
*
* This method will return immediately and complete asynchronously.
@ -1735,10 +1730,10 @@ secret_service_load_collections_finish (SecretService *self,
*
* Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of
* secret_service_get_collections().
* [method@Service.get_collections].
*
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* secret_service_get_sync() in order to ensure that the collections have been
* [func@Service.get_sync] in order to ensure that the collections have been
* loaded by the time you get the #SecretService proxy.
*
* This method may block indefinitely and should not be used in user interface
@ -1801,7 +1796,7 @@ secret_service_load_collections_sync (SecretService *self,
* @return_type: the variant type of the prompt result
* @error: location to place an error on failure
*
* Perform prompting for a #SecretPrompt.
* Perform prompting for a [class@Prompt].
*
* Runs a prompt and performs the prompting. Returns a variant result if the
* prompt was completed and not dismissed. The type of result depends on the
@ -1811,12 +1806,12 @@ secret_service_load_collections_sync (SecretService *self,
* This function is called by other parts of this library to handle prompts
* for the various actions that can require prompting.
*
* Override the #SecretServiceClass <literal>prompt_sync</literal> virtual method
* Override the #SecretServiceClass [vfunc@Service.prompt_sync] virtual method
* to change the behavior of the prompting. The default behavior is to simply
* run secret_prompt_perform_sync() on the prompt with a %NULL <literal>window_id</literal>.
* run [method@Prompt.perform_sync] on the prompt with a %NULL `window_id`.
*
* Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred,
* a variant result if the prompt was successful
* a variant result if the prompt was successful
*/
GVariant *
secret_service_prompt_sync (SecretService *self,
@ -1847,14 +1842,14 @@ secret_service_prompt_sync (SecretService *self,
* @callback: called when the operation completes
* @user_data: data to be passed to the callback
*
* Perform prompting for a #SecretPrompt.
* Perform prompting for a [class@Prompt].
*
* This function is called by other parts of this library to handle prompts
* for the various actions that can require prompting.
*
* Override the #SecretServiceClass <literal>prompt_async</literal> virtual method
* Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method
* to change the behavior of the prompting. The default behavior is to simply
* run secret_prompt_perform() on the prompt.
* run [method@Prompt.perform] on the prompt.
*/
void
secret_service_prompt (SecretService *self,
@ -1882,14 +1877,14 @@ secret_service_prompt (SecretService *self,
* @result: the asynchronous result passed to the callback
* @error: location to place an error on failure
*
* Complete asynchronous operation to perform prompting for a #SecretPrompt.
* Complete asynchronous operation to perform prompting for a [class@Prompt].
*
* Returns a variant result if the prompt was completed and not dismissed. The
* type of result depends on the action the prompt is completing, and is defined
* in the Secret Service DBus API specification.
*
* Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred,
* a variant result if the prompt was successful
* a variant result if the prompt was successful
*/
GVariant *
secret_service_prompt_finish (SecretService *self,
@ -1913,7 +1908,7 @@ secret_service_prompt_finish (SecretService *self,
* @self: the secret service
*
* Get the GObject type for collections instantiated by this service.
* This will always be either #SecretCollection or derived from it.
* This will always be either [class@Collection] or derived from it.
*
* Returns: the gobject type for collections
*/
@ -1941,7 +1936,7 @@ secret_service_get_collection_gtype (SecretService *self)
* @self: the service
*
* Get the GObject type for items instantiated by this service.
* This will always be either #SecretItem or derived from it.
* This will always be either [class@Item] or derived from it.
*
* Returns: the gobject type for items
*/

6
libsecret/secret-util.c
View File

@ -20,9 +20,9 @@
#include <string.h>
/**
* SECTION:secret-error
* @title: SecretError
* @short_description: libsecret errors
* SecretError
*
* libsecret errors
*
* Various errors reported by the libsecret library. No error returned from
* the libsecret API is suitable for direct display to the user. It is up

32
libsecret/secret-value.c
View File

@ -22,33 +22,27 @@
#include <string.h>
/**
* SECTION:secret-value
* @title: SecretValue
* @short_description: a value containing a secret
* SecretValue:
*
* A value containing a secret
*
* A #SecretValue contains a password or other secret value.
*
* Use secret_value_get() to get the actual secret data, such as a password.
* Use [method@Value.get] to get the actual secret data, such as a password.
* The secret data is not necessarily null-terminated, unless the content type
* is "text/plain".
*
* Each #SecretValue has a content type. For passwords, this is "text/plain".
* Use secret_value_get_content_type() to look at the content type.
* Each #SecretValue has a content type. For passwords, this is `text/plain`.
* Use [method@Value.get_content_type] to look at the content type.
*
* #SecretValue is reference counted and immutable. The secret data is only
* freed when all references have been released via secret_value_unref().
* freed when all references have been released via [method@Value.unref].
*
* Stability: Stable
*/
static gboolean is_password_value (SecretValue *value);
/**
* SecretValue:
*
* A secret value, like a password or other binary secret.
*/
EGG_SECURE_DECLARE (secret_value);
struct _SecretValue {
@ -153,8 +147,8 @@ secret_value_new_full (gchar *secret,
* @length: the length of the secret
*
* Get the secret data in the #SecretValue. The value is not necessarily
* null-terminated unless it was created with secret_value_new() or a
* null-terminated string was passed to secret_value_new_full().
* null-terminated unless it was created with [ctor@Value.new] or a
* null-terminated string was passed to [ctor@Value.new_full].
*
* Returns: (array length=length) (element-type guint8): the secret data
*/
@ -173,7 +167,7 @@ secret_value_get (SecretValue *value,
* @value: the value
*
* Get the secret data in the #SecretValue if it contains a textual
* value. The content type must be <literal>text/plain</literal>.
* value. The content type must be `text/plain`.
*
* Returns: (nullable): the content type
*/
@ -193,7 +187,7 @@ secret_value_get_text (SecretValue *value)
* @value: the value
*
* Get the content type of the secret value, such as
* <literal>text/plain</literal>.
* `text/plain`.
*
* Returns: the content type
*/
@ -209,7 +203,7 @@ secret_value_get_content_type (SecretValue *value)
* @value: value to reference
*
* Add another reference to the #SecretValue. For each reference
* secret_value_unref() should be called to unreference the value.
* [method@Value.unref] should be called to unreference the value.
*
* Returns: (transfer full): the value
*/
@ -265,7 +259,7 @@ is_password_value (SecretValue *value)
* #SecretValue as nonpageable memory.
*
* Returns: (transfer full): a new password string stored in nonpageable memory
* which must be freed with secret_password_free() when done
* which must be freed with [func@password_free] when done
*
* Since: 0.19.0
*/

8
libsecret/secret-version.h.in
View File

@ -19,14 +19,6 @@
#ifndef __SECRET_VERSION_H__
#define __SECRET_VERSION_H__
/**
* SECTION:secret-version
* @short_description: Variables and macros to check the libsecret version
* @title: Version Information
*
* Stability: Stable
*/
/**
* SECRET_MAJOR_VERSION:
*

2
meson_options.txt
View File

@ -2,7 +2,7 @@ option('manpage', type: 'boolean', value: true, description: 'Build man pages')
option('gcrypt', type: 'boolean', value: true, description: 'With gcrypt and transport encryption')
option('debugging', type: 'boolean', value: false, description: 'Turn debugging on/off')
option('vapi', type: 'boolean', value: true, description: 'Create VAPI file.')
option('gtk_doc', type: 'boolean', value: true, description: 'Build reference documentation using gtk-doc')
option('gtk_doc', type: 'boolean', value: true, description: 'Build reference documentation using gi-docgen')
option('introspection', type: 'boolean', value: true, description: 'Create GIR file.')
option('bashcompdir', type: 'string', value: '', description: 'Override default location for bash completion files')
option('bash_completion', type: 'feature', value: 'auto', description: 'Install bash completion files')

6
subprojects/gi-docgen.wrap Normal file
View File

@ -0,0 +1,6 @@
[wrap-git]
directory=gi-docgen
url=https://gitlab.gnome.org/GNOME/gi-docgen.git
push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
revision=main
depth=1