security: interface for the libxslt security framework

## security

security - interface for the libxslt security framework

the libxslt security framework allow to restrict the access to new resources (file or URL) from the stylesheet at runtime.

Author(s): Daniel Veillard

## Synopsis

    typedef enum xsltSecurityOption;
    typedef struct _xsltSecurityPrefs xsltSecurityPrefs;
    typedef xsltSecurityPrefs * xsltSecurityPrefsPtr;
    int	xsltCheckRead			(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const xmlChar * URL);
    int	xsltCheckWrite			(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const xmlChar * URL);
    void	xsltFreeSecurityPrefs		(xsltSecurityPrefsPtr sec);
    xsltSecurityPrefsPtr	xsltGetDefaultSecurityPrefs	(void);
    xsltSecurityCheck	xsltGetSecurityPrefs	(xsltSecurityPrefsPtr sec,
    						 xsltSecurityOption option);
    xsltSecurityPrefsPtr	xsltNewSecurityPrefs	(void);
    int	xsltSecurityAllow		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value);
    typedef int xsltSecurityCheck		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value);
    int	xsltSecurityForbid		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value);
    int	xsltSetCtxtSecurityPrefs	(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt);
    void	xsltSetDefaultSecurityPrefs	(xsltSecurityPrefsPtr sec);
    int	xsltSetSecurityPrefs		(xsltSecurityPrefsPtr sec,
    					 xsltSecurityOption option,
    					 xsltSecurityCheck func);

## Description

## Details

### Enum xsltSecurityOption

    enum xsltSecurityOption {
        XSLT_SECPREF_READ_FILE = 1
        XSLT_SECPREF_WRITE_FILE = 2
        XSLT_SECPREF_CREATE_DIRECTORY = 3
        XSLT_SECPREF_READ_NETWORK = 4
        XSLT_SECPREF_WRITE_NETWORK = 5
    };

### Structure xsltSecurityPrefs

    struct _xsltSecurityPrefs {
    The content of this structure is not made public by the API.
    } xsltSecurityPrefs;

### Typedef xsltSecurityPrefsPtr

    xsltSecurityPrefs * xsltSecurityPrefsPtr;

### Function type xsltSecurityCheck

    int	xsltSecurityCheck		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value)

User provided function to check the value of a string like a file path or an URL ...

`sec`: |
`ctxt`: |
`value`: |
`Returns`: |

### xsltCheckRead ()

    int	xsltCheckRead			(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const xmlChar * URL)

Check if the resource is allowed to be read

`sec`: | the security options
`ctxt`: | an XSLT transformation context
`URL`: | the resource to be read
`Returns`: | 1 if read is allowed, 0 if not and -1 in case or error.

### xsltCheckWrite ()

    int	xsltCheckWrite			(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const xmlChar * URL)

Check if the resource is allowed to be written, if necessary makes some preliminary work like creating directories

`sec`: | the security options
`ctxt`: | an XSLT transformation context
`URL`: | the resource to be written
`Returns`: | 1 if write is allowed, 0 if not and -1 in case or error.

### xsltFreeSecurityPrefs ()

    void	xsltFreeSecurityPrefs		(xsltSecurityPrefsPtr sec)

Free up a security preference block

`sec`: | the security block to free

### xsltGetDefaultSecurityPrefs ()

    xsltSecurityPrefsPtr	xsltGetDefaultSecurityPrefs	(void)

Get the default security preference application-wide

`Returns`: | the current xsltSecurityPrefsPtr in use or NULL if none

### xsltGetSecurityPrefs ()

    xsltSecurityCheck	xsltGetSecurityPrefs	(xsltSecurityPrefsPtr sec,
    						 xsltSecurityOption option)

Lookup the security option to get the callback checking function

`sec`: | the security block to update
`option`: | the option to lookup
`Returns`: | NULL if not found, the function otherwise

### xsltNewSecurityPrefs ()

    xsltSecurityPrefsPtr	xsltNewSecurityPrefs	(void)

Create a new security preference block

`Returns`: | a pointer to the new block or NULL in case of error

### xsltSecurityAllow ()

    int	xsltSecurityAllow		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value)

Function used to always allow an operation

`sec`: | the security block to use
`ctxt`: | an XSLT transformation context
`value`: | unused
`Returns`: | 1 always

### xsltSecurityForbid ()

    int	xsltSecurityForbid		(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt,
    					 const char * value)

Function used to always forbid an operation

`sec`: | the security block to use
`ctxt`: | an XSLT transformation context
`value`: | unused
`Returns`: | 0 always

### xsltSetCtxtSecurityPrefs ()

    int	xsltSetCtxtSecurityPrefs	(xsltSecurityPrefsPtr sec,
    					 xsltTransformContextPtr ctxt)

Set the security preference for a specific transformation

`sec`: | the security block to use
`ctxt`: | an XSLT transformation context
`Returns`: | -1 in case of error, 0 otherwise

### xsltSetDefaultSecurityPrefs ()

    void	xsltSetDefaultSecurityPrefs	(xsltSecurityPrefsPtr sec)

Set the default security preference application-wide

`sec`: | the security block to use

### xsltSetSecurityPrefs ()

    int	xsltSetSecurityPrefs		(xsltSecurityPrefsPtr sec,
    					 xsltSecurityOption option,
    					 xsltSecurityCheck func)

Update the security option to use the new callback checking function

`sec`: | the security block to update
`option`: | the option to update
`func`: | the user callback to use for this option
`Returns`: | -1 in case of error, 0 otherwise