[wsf-c-dev] WSF4PHP API addtions

[James Clark]

> > In general, it's bad to pass filenames around.  Unless the contents of
> > the file is large (which it is not in this case), pass the contents as a
> > PHP string.
> >
> >   
> -1. The keystore can be large and its binary(e.g.PKCS12/PFX format).

I was talking about the private key, which is small, not the keystore.
>  
> Better to leave it for rampart to load the file from the given filename. 

In a C-level API, you should avoid filenames as much as you can.  The
problem is that filenames introduce a lot of system dependencies:

- one big, hairy issue is filename encodings; you can't just rely on
fopen to do the right thing; for example, on Windows you need to
transcode on UTF-16 and call the Unicode version of the function; on
Linux, you need to figure the filesystem is using UTF-8 or something
else

- another problem is that often applications provide their own file I/O
layer that allows people to treat things that aren't actually filenames
as if they were; for example, PHP has such a layer that allows users to
use URLs as filenames (provided an appropriate config option is set); so
if you get a "filename" from PHP, a good quality extension will treat in
the same way as other "filenames" are treated in PHP, which means it
needs to be accessed using PHP's I/O layer not using stdio directly

- you need to handle relative filenames; what's the right current
directory for interpreting them

- shell expansions on filenames; do you want to expand ~ to the home
directory like the shell does

- there can be security issues in accessing files

- the data may not be in a file anywhere (for example, recent versions
of Linux have an API for storing keys in a secure way - see keys.txt)

At the C-level an API without filenames is much more general and
flexible.

At the PHP-level, filenames are OK BUT they MUST go through the PHP I/O
layer.

> I think most of these configuration problems 
> will be wiped out once the WS Security Policy is implemented.

Some will be, but some will remain.  In particular:

- providing a private key for encryption
- providing credentials for authentication

are not part of policy.  They're conceptually quite different.  So we
have to find general solutions to these.

Here's what I would suggest for encryption  Provide an option
"encryptionPrivateKey" whose value is a PHP object, representing a
private key used for encryption. Then provide a variety of functions to
create suitable objects in convenient ways, e.g.

  "encryptionPrivateKey" => 
    ws_private_key_from_pem_file("foo.pem", "mypassphrase")

The PHP encryption private key object should provide a method for each
key transport algorithm (e.g. RSA 1.5 and OAEP) that takes a symmetric
key and any appropriate parameters and returns the symmetric key
encrypted with the private key.

Your implementation of the object might wrap an OpenSSL EVP_PKEY.

This gives a solution that is 100% general: it can work even if the
private key is on a smart card (and isn't allowed off the smart key).
Yet it's also easy to use.

James