diff options
author | Federico Mena Quintero <federico@gnome.org> | 2019-02-18 12:57:13 -0600 |
---|---|---|
committer | Federico Mena Quintero <federico@gnome.org> | 2019-02-18 12:57:13 -0600 |
commit | ff0c33f4e7a0fae061a1c4630a8a4e90de60d786 (patch) | |
tree | e85582e173742f0ded64671eb5a664cf475fe8bf | |
parent | 7ffd9b87b4dbc9380c5c91c76a51f7fbe5324889 (diff) | |
download | librsvg-wip/rust-api.tar.gz |
Add toplevel docs for librsvg_cratewip/rust-api
-rw-r--r-- | librsvg/rsvg-handle.c | 20 | ||||
-rw-r--r-- | librsvg_crate/src/lib.rs | 88 |
2 files changed, 101 insertions, 7 deletions
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c index 336d522e..faf34352 100644 --- a/librsvg/rsvg-handle.c +++ b/librsvg/rsvg-handle.c @@ -30,11 +30,16 @@ * RsvgHandle from an SVG file, or from a memory buffer that contains SVG data, * or in the most general form, from a #GInputStream that will provide SVG data. * + * Librsvg can load SVG images and render them to Cairo surfaces, + * using a mixture of SVG's [static mode] and [secure static mode]. + * Librsvg does not do animation nor scripting, and can load + * references to external data only in some situations; see below. + * * Librsvg supports reading <link * href="https://www.w3.org/TR/SVG11/">SVG 1.1</link> data, and is * gradually adding support for features in <link * href="https://www.w3.org/TR/SVG2/">SVG 2</link>. Librsvg also supports - * SVGZ files, which is just an SVG stream compressed with the GZIP algorithm. + * SVGZ files, which are just an SVG stream compressed with the GZIP algorithm. * * # The "base file" and resolving references to external files * @@ -56,11 +61,12 @@ * When processing an SVG, librsvg will only load referenced files if they are * in the same directory as the base file, or in a subdirectory of it. That is, * if the base file is <filename>/foo/bar/baz.svg</filename>, then librsvg will - * only try to load referenced files (from SVG's "image" element, for example, - * or from content included through XML entities) if those files are in - * <filename>/foo/bar/<!-- -->*</filename> or in - * <filename>/foo/bar/<!-- -->*<!-- -->/.../<!-- -->*</filename>. This is so that malicious - * SVG files cannot include files that are in a directory above. + * only try to load referenced files (from SVG's + * <literal><image></literal> element, for example, or from content + * included through XML entities) if those files are in <filename>/foo/bar/<!-- + * -->*</filename> or in <filename>/foo/bar/<!-- -->*<!-- -->/.../<!-- + * -->*</filename>. This is so that malicious SVG files cannot include files + * that are in a directory above. * * The full set of rules for deciding which URLs may be loaded is as follows; * they are applied in order. A referenced URL will not be loaded as soon as @@ -81,7 +87,7 @@ * </listitem> * * <listitem> - * If referenced URLs are absolute, rathen than relative, then they must + * If referenced URLs are absolute, rather than relative, then they must * have the same scheme as the base URL. For example, if the base URL has a * "<literal>file</literal>" scheme, then all URL references inside the SVG must * also have the "<literal>file</literal>" scheme, or be relative references which diff --git a/librsvg_crate/src/lib.rs b/librsvg_crate/src/lib.rs index 508aa53a..7d462729 100644 --- a/librsvg_crate/src/lib.rs +++ b/librsvg_crate/src/lib.rs @@ -1,3 +1,91 @@ +//! Load and render SVG images into Cairo surfaces. +//! +//! This crate can load SVG images and render them to Cairo surfaces, +//! using a mixture of SVG's [static mode] and [secure static mode]. +//! Librsvg does not do animation nor scripting, and can load +//! references to external data only in some situations; see below. +//! +//! Librsvg supports reading [SVG 1.1] data, and is gradually adding +//! support for features in [SVG 2]. Librsvg also supports SVGZ +//! files, which are just an SVG stream compressed with the GZIP +//! algorithm. +//! +//! # Basic usage +//! +//! * Create a [`LoadOptions`] struct. +//! * Get an [`SvgHandle`] from the [`LoadOptions`]. +//! * Get a [`CairoRenderer`] from the [`SvgHandle`] and render to a Cairo context. +//! +//! [`LoadOptions`]: struct.LoadOptions.html +//! [`SvgHandle`]: struct.SvgHandle.html +//! [`CairoRenderer`]: struct.CairoRenderer.html +//! +//! # The "base file" and resolving references to external files +//! +//! When you load an SVG, librsvg needs to know the location of the "base file" +//! for it. This is so that librsvg can determine the location of referenced +//! entities. For example, say you have an SVG in <filename>/foo/bar/foo.svg</filename> +//! and that it has an image element like this: +//! +//! ```ignore +//! <image href="resources/foo.png" .../> +//! ``` +//! +//! In this case, librsvg needs to know the location of the toplevel +//! `/foo/bar/foo.svg` so that it can generate the appropriate +//! reference to `/foo/bar/resources/foo.png`. +//! +//! ## Security and locations of referenced files +//! +//! When processing an SVG, librsvg will only load referenced files if +//! they are in the same directory as the base file, or in a +//! subdirectory of it. That is, if the base file is +//! `/foo/bar/baz.svg`, then librsvg will only try to load referenced +//! files (from SVG's `<image>` element, for example, or from content +//! included through XML entities) if those files are in `/foo/bar/*` +//! or in `/foo/bar/*/.../*`. This is so that malicious SVG files +//! cannot include files that are in a directory above. +//! +//! The full set of rules for deciding which URLs may be loaded is as follows; +//! they are applied in order. A referenced URL will not be loaded as soon as +//! one of these rules fails: +//! +//! 1. All `data:` URLs may be loaded. These are sometimes used to +//! include raster image data, encoded as base-64, directly in an SVG +//! file. +//! +//! 2. All other URL schemes in references require a base URL. For +//! example, this means that if you load an SVG with +//! [`LoadOptions.read`](struct.LoadOptions.html#method.read) without +//! providing a `base_url`, then any referenced files will not be +//! allowed (e.g. raster images to be loaded from other files will not +//! work). +//! +//! 3. If referenced URLs are absolute, rather than relative, then +//! they must have the same scheme as the base URL. For example, if +//! the base URL has a "`file`" scheme, then all URL references inside +//! the SVG must also have the "`file`" scheme, or be relative +//! references which will be resolved against the base URL. +//! +//! 4. If referenced URLs have a "`resource`" scheme, that is, if they +//! are included into your binary program with GLib's resource +//! mechanism, they are allowed to be loaded (provided that the base +//! URL is also a "`resource`", per the previous rule). +//! +//! 5. Otherwise, non-`file` schemes are not allowed. For example, +//! librsvg will not load `http` resources, to keep malicious SVG data +//! from "phoning home". +//! +//! 6. A relative URL must resolve to the same directory as the base +//! URL, or to one of its subdirectories. Librsvg will canonicalize +//! filenames, by removing "`..`" path components and resolving symbolic +//! links, to decide whether files meet these conditions. +//! +//! [static mode]: https://www.w3.org/TR/SVG2/conform.html#static-mode +//! [secure static mode]: https://www.w3.org/TR/SVG2/conform.html#secure-static-mode +//! [SVG 1.1]: https://www.w3.org/TR/SVG11/ +//! [SVG 2]: https://www.w3.org/TR/SVG2/ + #![warn(unused)] extern crate cairo; extern crate gio; |