Commit Graph

50 Commits

Author SHA1 Message Date
Philip Withnall
7feeafd9db gio: Fix docs links to description of I/O priority
There are a lot of links to the description of I/O priority in the GIO
docs, and they’re all currently broken since the docs build was ported
to gi-docgen.

Use a simple find and replace (see below) to fix them. This doesn’t port
any of the surrounding docs to gi-docgen format, but should still
improve things overall.
```sh
git search-replace --fix '\[I/O priority\]\[io-priority\]///[I/O priority](iface.AsyncResult.html#io-priority)'
```

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3250
2024-03-22 00:53:05 +00:00
Sophie Herold
0d268c4825 Remove all nicks and blurbs from param specs
Nicks and blurbs don't have any practical use for gio/gobject libraries.
Leaving tests untouched since this features is still used by other libraries.

Closes #2991
2023-11-29 13:41:34 +00:00
Philip Withnall
8af86abefb docs: Move the GTlsConnection SECTION
Move it to the struct docs.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-14 14:32:19 +00:00
Philip Withnall
5942cd7984 gio: Add SPDX license headers automatically
Add SPDX license (but not copyright) headers to all files which follow a
certain pattern in their existing non-machine-readable header comment.

This commit was entirely generated using the command:
```
git ls-files gio/*.[ch] | xargs perl -0777 -pi -e 's/\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/\n \*\n \* SPDX-License-Identifier: LGPL-2.1-or-later\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/igs'
```

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Helps: #1415
2022-05-18 09:18:52 +01:00
Michael Catanzaro
69a1867d51 gtlsconnection: fix typo in docs
Grrr, copy/paste error detected.
2022-03-16 10:38:34 +00:00
Michael Catanzaro
82999879bc gtlsconnection: warn about footguns of using a non-default database
Since
https://gitlab.gnome.org/GNOME/glib-networking/-/merge_requests/173,
there is now a really surprising implication to using a non-default
GTlsDatabase: your database could do nothing at all other than wrap the
default database, which you would expect to result in no behavior
changes, but in fact it causes fewer security checks to be performed
during certificate verification. This is because certificate
verification moved from GTlsDatabase to GTlsConnection, allowing for
more security checks to be performed. But if using a non-default
GTlsDatabase, we have to fall back to letting GTlsDatabase to the
verification, as before.

This is the best we can do. It's not a regression for applications,
because it means applications get the previous pre-2.72 behavior. But it
does mean that new security checks added in 2.72 are not applied, which
is unfortunate, so we should warn developers about this.
2021-11-22 15:56:56 +00:00
Michael Catanzaro
780af9cff3 Document potential footgun with GTlsCertificateFlags
Once upon a time, we tried to return all possible certificate errors,
but it never actually worked reliably and nowadays we have given up.
This needs to be documented because a reasonable developer would not
expect it.

Because mistakes could be security-critical, I decided to copy the same
warning in several different places rather than relying only on
cross-referencese.
2021-11-16 15:21:21 +00:00
Michael Catanzaro
5e6c2e1e2c gtlsconnection: use a vfunc to implement get_negotiated_protocol()
The current code is unsafe to use from multiple threads at once.
GIOStream functions like this are supposed to be semi-threadsafe. It's
allowed for them to be called on both a reader thread and a writer
thread at the same time. Of course, it's still tricky and dangerous,
because it's only *really* threadsafe if the handshake has finished,
and API users have no plausible way to know that because the API
does not require performing an explicit handshake operation. But that's
a glib-networking problem. We can at least avoid the most obvious
threadsafety issue here in the API layer.

Note that we'll need to implement the new vfunc in glib-networking for
this to actually work.

Fixes #2393
2021-06-21 09:28:23 -05:00
Michael Catanzaro
bf37392045 tls: add functions to get protocol version and ciphersuite name
This adds g_tls_connection_get_protocol_version(),
g_tls_connection_get_ciphersuite_name(), and DTLS variants. This will
allow populating TLS connection information in the WebKit web inspector.

This is WIP because we found it's not quite possibly to implement
correctly with GnuTLS. See glib-networking!151.
2021-06-03 10:56:15 -05:00
Ruslan Marchenko
44524b9daa Add g_(d)tls_connection_get_channel_binding_data calls and enums
* Add g_tls_connection_get_channel_binding_data API call
 * Add g_dtls_connection_get_channel_binding_data API call
 * Add get_binding_data method to GTlsConnection class
 * Add get_binding_data method to GDtlsConnection interface
 * Add GTlsChannelBindingType enum with tls-unique and
   tls-server-end-point types
 * Add GTlsChannelBindingError enum and G_TLS_CHANNEL_BINDING_ERROR
   quark
 * Add new API calls to documentation reference gio-sections-common
2020-06-25 12:40:34 +00:00
Michael Catanzaro
4db1336ff6 gtlsconnection: Improve documentation of peer-certificate[-errors]
In glib-networking#127, it was reported that we don't properly implement
the documented behavior of these properties. However, we cannot fix it
because libsoup relies on the implemented behavior, and it's hard to
change that without cascading breakage. The practical solution is to
adjust our documentation to match reality. There should be no downsides
to this, and compat risk of changing the documentation is much smaller
than risk of changing the implementation, so I think this is the best we
can make of an unfortunate situation. See glib-networking#127 for full
discussion and glib-networking#129 for the regression when we attempted
to match the documented behavior.
2020-06-10 09:56:47 -05:00
Philip Withnall
1154a3b6fb gtlsconnection: Add missing (nullable) annotations
And the same set of annotations on `GDtlsConnection` too.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Fixes: #2038
2020-02-17 18:17:06 +00:00
Michael Catanzaro
bbbaae9fb7 Fully deprecate TLS rehandshakes
Previously, the documentation indicated that it was possible to call
g_tls_connection_handshake() after an initial handshake to trigger a
rehandshake, but only if TLS 1.2 or older is in use. However, there is
no documented way to ensure TLS 1.2 gets used. Nowadays, TLS 1.3 is used
by default.

I'm removing support for rehandshaking from glib-networking, as part of
a large refactoring where keeping rehandshakes would have entailed
significant additional complexity. So let's update the documentation to
indicate this is no longer ever supported. Applications should not
notice any difference.

Also, sync some previous handshake and rehandshake changes from
GTlsConnection to GDtlsConnection that were missed by mistake. I
try to remember to always update GDtlsConnection when touching
GTlsConnection documentation, but it's easy to forget.
2020-01-07 14:52:20 -06:00
Michael Catanzaro
8f88783a7f gtlsconnection: add missing G_PARAM_DEPRECATED
The use-system-certdb function has been deprecated since 2.30 and is
just missing the deprecation flag to warn developers.
2019-11-18 13:52:39 -06:00
Michael Catanzaro
7b3824fa62 gtlsconnection: add missing deprecation annotation
GTlsConnection:rehandshake-mode has been deprecated since 2.60 using
the G_PARAM_DEPRECATED flag, but I forgot to add the right annotation to
the documentation. Oops.

The associated getter/setter functions were both deprecated properly.
2019-11-18 13:52:39 -06:00
Michael Catanzaro
79999c8723 gtlsconnection: document rehandshake-mode is no longer supported 2019-11-18 13:52:39 -06:00
Michael Catanzaro
b75dd395ba gtlsconnection: clarify handshake() documentation
This tries to clarify some confusing aspects of the
g_tls_connection_handshake() that can trip up experienced developers.
2019-11-13 20:57:26 -06:00
Christian Hergert
22ba4411cc gio: remove use of generic marshaller from GIO objects
Using the generic marshaller has drawbacks beyond performance. One such
drawback is that it breaks the stack unwinding from the Linux kernel due
to having unsufficient data to walk past ffi_call_unixt64. That means that
performance profiling by application developers looks grouped among
seemingly unrelated code paths.

While we can't fix the kernel unwinding here, we can provide proper
c_marshallers and va_marshallers for objects within Gio so that
performance profiling of applications is more reliable.

Related to GNOME/Initiatives#10
2019-06-17 16:29:09 -07:00
Philip Withnall
40ff475977 Annotate various types and macros as deprecated
These have all been documented as deprecated for a long time, but we’ve
never had a way to programmatically mark them as deprecated. Do that
now.

This is based on the list of deprecations from the reverted commit
80fcb1bc2.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Fixes: #638
2019-05-30 10:39:11 +01:00
Michael Gratton
d7aedeff29 gio: Update bad cert error in accept-certificate and GTlsError docs
This makes the documented error returned when the cert is rejected
consistent with both self and reality.
2019-01-08 22:40:54 +11:00
Scott Hutton
9032e8897d Implement support for ALPN in GTlsConnection, GDtlsConnection 2018-12-18 16:32:55 -08:00
Michael Catanzaro
85f7d493d7 Deprecate TLS rehandshake APIs
Allowing unsafe rehandshakes used to be required for web compatibility,
but this is no longer a concern in 2018. So there should no longer be
compatibility benefits to calling this function. All it does is make
your TLS connection insecure.

Also, rehandshaking no longer exists at all in TLS 1.3.

At some point (maybe soon!) glib-networking will begin ignoring the
rehandshake mode, so let's deprecate it now.
2018-11-20 22:07:58 -06:00
Michael Catanzaro
2031e37dfc Update documentation of g_tls_connection_handshake() one last time
Let's entirely deprecate calling this function for rehandshaking. The
current documentation is OK, but guarantees defined behavior (to attempt
a rehandshake) when TLS 1.2 is in use. But there's no way to force TLS
1.2, and also no way to check which version of TLS is in use. I really
should have deprecated use of this function for rehandshaking entirely
last time I updated it.

Fortunately, there should be no compatibility risk for existing code,
because rehandshaking has no visible effects at the API level.
2018-11-20 22:04:50 -06:00
Michael Catanzaro
68878ab50b Update documentation of g_tls_connection_handshake() again
I made a mistake when last updating the documentation in 94a99ae9. I
wrote that, with TLS 1.3, this would perform a rekey instead of a
rehandshake. In fact, that's only true for client connections. For
server connections, it's a no-op.

I was a bit nervous about how to document the behavior anyway, because
we really don't know what behavior will be reasonable with non-GnuTLS
crypto backends. This behavior is reasonable for the GnuTLS backend, but
might not necessarily make sense for OpenSSL. Ideally, we would
discourage API users from doing things which could have unexpected
effects, so instead of documenting what the GnuTLS backend does, I think
it'd be better to document that this is "undefined but not dangerous,"
since of course we want to make sure that existing code that doesn't
know about TLS 1.3 is not broken.
2018-11-12 14:49:30 -06:00
Michael Catanzaro
94a99ae917 Update documentation of g_tls_connection_handshake
Rehandshaking is not a thing in TLS 1.3. In that case,
g_tls_connection_handshake() should instead perform a re-key.
2018-07-27 10:48:50 -05:00
Sébastien Wilmet
3bf4a720c3 gio/: LGPLv2+ -> LGPLv2.1+
Sub-directories inside gio/ already processed in a previous commit:
- fam/
- gdbus-2.0/ (which contains only codegen/)
- gvdb/
- inotify/
- tests/
- win32/
- xdgmime/

Other sub-directories inside gio/:
- completion/: no license headers
- kqueue/: not LGPL, BSD-style license

https://bugzilla.gnome.org/show_bug.cgi?id=776504
2017-05-29 19:53:34 +02:00
Christian Hergert
18a33f72db introspection: use (nullable) or (optional) instead of (allow-none)
If we have an input parameter (or return value) we need to use (nullable).
However, if it is an (inout) or (out) parameter, (optional) is sufficient.

It looks like (nullable) could be used for everything according to the
Annotation documentation, but (optional) is more specific.
2016-11-22 14:14:37 -08:00
Piotr Drąg
10c490cdfe Use Unicode in translatable strings
See https://developer.gnome.org/hig/stable/typography.html

https://bugzilla.gnome.org/show_bug.cgi?id=772221
2016-10-12 21:30:42 +02:00
Philip Withnall
c3d6934f18 gio: Add DTLS interfaces
Add a new GDtlsConnection interface, plus derived GDtlsClientConnection
and GDtlsServerConnection interfaces, for implementing Datagram TLS
support in glib-networking.

A GDtlsConnection is a GDatagramBased, so may be used as a normal
datagram socket, wrapping all datagrams from a base GDatagramBased in
DTLS segments.

Test cases are included in the implementation in glib-networking.

https://bugzilla.gnome.org/show_bug.cgi?id=752240
2016-01-18 14:25:06 +00:00
Philip Withnall
3add5e2837 gio: Document thread safety of the streams API
Specifically, GIOStream and the TLS connection streams.

Includes wording adapted from suggestions by Dan Winship
<danw@gnome.org>.

https://bugzilla.gnome.org/show_bug.cgi?id=735754
2016-01-11 15:58:42 +00:00
Philip Withnall
1ac2a606fc gtlsconnection: Fix a typo in the documentation 2015-11-06 11:27:24 +01:00
William Jon McCann
20f4d1820b docs: use "Returns:" consistently
Instead of "Return value:".
2014-02-19 19:41:52 -05:00
Matthias Clasen
e7fd3de86d Eradicate links and xrefs
These are all replaced by markdown ref links.
2014-02-08 12:26:56 -05:00
Matthias Clasen
3232425785 Docs: replace <literal> by ` 2014-02-06 08:07:16 -05:00
Daniel Mustieles
078dbda148 Updated FSF's address 2014-01-31 14:31:55 +01:00
Cosimo Cecchi
62570a52b1 gio: don't quote quark names for G_DEFINE_QUARK 2012-08-28 13:16:25 -04:00
Matthias Clasen
60d2cb665e Use G_DEFINE_QUARK for quarks in GIO 2012-08-28 00:08:08 -04:00
Robert Ancell
4143842eb4 Add missing allow-none annotations for function parameters.
Found using:
find . -name '*.c' | xargs grep 'or %NULL' | grep ' \* @' | grep -v '@error' | grep -v allow-none
2012-03-31 20:34:28 +11:00
Martin Pitt
782f839383 [gi] Add missing Gio transfer annotations 2011-08-11 11:38:20 +02:00
Stef Walter
0f99cfa882 GTlsDatabase and related objects
The database is an abstract object implemented by the various TLS
backends, which is used by GTlsConnection to lookup certificates
and keys, as well as verify certificate chains.

Also add GTlsInteraction, which can be used to prompt the user
for a password or PIN (used with the database).

https://bugzilla.gnome.org/show_bug.cgi?id=636572
2011-08-04 08:54:55 +02:00
Johan Dahlin
ec98953e42 Pass in NULL instead of g_cclosure_marshal_generic
NULL is now a shortcut for g_cclosure_marshal_generic, so avoid
referencing it directly.

https://bugzilla.gnome.org/show_bug.cgi?id=654917
2011-07-19 14:38:34 -03:00
Colin Walters
b74e2a720a Stop using glib-genmarshal at build time
To help cross compilation, don't use glib-genmarshal in our
build.  This is easy now that we have g_cclosure_marshal_generic().

In gobject/, add gmarshal.[ch] to git (making the existing entry
points stubs).

In gio/, simply switch to using g_cclosure_marshal_generic().

https://bugzilla.gnome.org/show_bug.cgi?id=652168
2011-06-20 17:24:07 -04:00
Matthias Clasen
01f63b19f9 Fix links in gio docs 2011-06-04 18:48:19 -04:00
Brian Cameron
37ef8cbba5 Fix for bug #637720. void functions should not return a value. 2010-12-22 01:37:21 -06:00
Dan Winship
f5c3e0d3d5 Change the handling of the peer certificate in GTlsConnection
Make the certificate and peer-certificate properties virtual, and add
peer-certificate-errors as well. Change the documentation on
peer-certificate to say that it's not set until after the handshake
succeeds (which means notify::peer-certificate can be used to tell
when a handshake has completed).
2010-12-07 14:58:42 +01:00
Dan Winship
4f6efb681d Change the semantics of GTlsConnection:require-close-notify
We were combining "allow un-notified closes" and "close without
notifying" into a single property, which meant that it was impossible
to "be liberal in what you accept and conservative in what you send".
Change require-close-notify to only be about the peer behavior, and
make our connections always close-notify properly when closing (while
noting that you can just close the base-io-stream directly if you want
to do an unclean close).
2010-12-07 10:41:06 +01:00
Dan Winship
95cba18349 Remove GTlsConnection::need-certificate
Trying to do this as a signal won't work well with either
GTlsCertificateDB (in which case looking up a certificate in the db is
a blocking/asynchronous act) or session resumption support (in which
case the certificate or lack thereof is part of the session definition
and so needs to be known immediately). Make the caller use
g_tls_connection_set_certificate() ahead of time (or when retrying)
instead.
2010-12-07 10:41:05 +01:00
Dan Winship
d6e94070dd Add GTlsConnection:use-system-certdb
This can be set FALSE if you don't want to validate certificates
against the system database.
2010-12-07 10:41:05 +01:00
Matthias Clasen
eed36d38d1 Various doc tweaks 2010-11-28 23:55:43 -05:00
Dan Winship
59d62726de Add initial TLS (SSL) support to gio
This adds an extension point for TLS connections to gio, with a
gnutls-based implementation in glib-networking.

Full TLS support is still a work in progress; the current API is
missing some features, and parts of it may still be changed before
2.28.

https://bugzilla.gnome.org/show_bug.cgi?id=588189
2010-11-26 15:57:11 -05:00