3 * StatusNet - the distributed open-source microblogging tool
4 * Copyright (C) 2010, StatusNet, Inc.
6 * A sample module to show best practices for StatusNet plugins
10 * This program is free software: you can redistribute it and/or modify
11 * it under the terms of the GNU Affero General Public License as published by
12 * the Free Software Foundation, either version 3 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Affero General Public License for more details.
20 * You should have received a copy of the GNU Affero General Public License
21 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 * @author James Walker <james@status.net>
25 * @copyright 2010 StatusNet, Inc.
26 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
27 * @link http://status.net/
31 const ENCODING = 'base64url';
33 const NS = 'http://salmon-protocol.org/ns/magic-env';
35 protected $actor = null; // Profile of user who has signed the envelope
37 protected $data = null; // When stored here it is _always_ base64url encoded
38 protected $data_type = null;
39 protected $encoding = null;
40 protected $alg = null;
41 protected $sig = null;
44 * Extract envelope data from an XML document containing an <me:env> or <me:provenance> element.
46 * @param string XML source
47 * @return mixed associative array of envelope data, or false on unrecognized input
49 * @fixme will spew errors to logs or output in case of XML parse errors
50 * @fixme may give fatal errors if some elements are missing or invalid XML
51 * @fixme calling DOMDocument::loadXML statically triggers warnings in strict mode
53 public function __construct($xml=null, Profile $actor=null) {
55 $dom = new DOMDocument();
56 if (!$dom->loadXML($xml)) {
57 throw new ServerException('Tried to load malformed XML as DOM');
58 } elseif (!$this->fromDom($dom)) {
59 throw new ServerException('Could not load MagicEnvelope from DOM');
61 } elseif ($actor instanceof Profile) {
62 // So far we only allow setting with _either_ $xml _or_ $actor as that's
63 // all our circumstances require. But it may be confusing for new developers.
64 // The idea is that feeding XML must be followed by interpretation and then
65 // running $magic_env->verify($profile), just as in SalmonAction->prepare(...)
66 // and supplying an $actor (which right now has to be a User) will require
67 // defining the $data, $data_type etc. attributes manually afterwards before
68 // signing the envelope..
69 $this->setActor($actor);
74 * Retrieve Salmon keypair first by checking local database, but
75 * if it's not found, attempt discovery if it has been requested.
77 * @param Profile $profile The profile we're looking up keys for.
78 * @param boolean $discovery Network discovery if no local cache?
80 public function getKeyPair(Profile $profile, $discovery=false) {
81 if (!$profile->isLocal()) common_debug('Getting magic-public-key for non-local profile id=='.$profile->getID());
82 $magicsig = Magicsig::getKV('user_id', $profile->getID());
84 if ($discovery && !$magicsig instanceof Magicsig) {
85 if (!$profile->isLocal()) common_debug('magic-public-key not found, will do discovery for profile id=='.$profile->getID());
86 // Throws exception on failure, but does not try to _load_ the keypair string.
87 $keypair = $this->discoverKeyPair($profile);
89 $magicsig = new Magicsig();
90 $magicsig->user_id = $profile->getID();
91 $magicsig->importKeys($keypair);
92 // save the public key for this profile in our database.
93 // TODO: If the profile generates a new key remotely, we must be able to replace
94 // this (of course after callback-verification).
96 } elseif (!$magicsig instanceof Magicsig) { // No discovery request, so we'll give up.
97 throw new ServerException(sprintf('No public key found for profile (id==%d)', $profile->id));
100 assert($magicsig->publicKey instanceof Crypt_RSA);
106 * Get the Salmon keypair from a URI, uses XRD Discovery etc. Reasonably
107 * you'll only get the public key ;)
109 * The string will (hopefully) be formatted as described in Magicsig specification:
111 * @return string formatted as Magicsig keypair
113 public function discoverKeyPair(Profile $profile)
115 $signer_uri = $profile->getUri();
116 if (empty($signer_uri)) {
117 throw new ServerException(sprintf('Profile missing URI (id==%d)', $profile->getID()));
120 $disco = new Discovery();
122 // Throws exception on lookup problems
124 $xrd = $disco->lookup($signer_uri);
125 } catch (Exception $e) {
126 // Diaspora seems to require us to request the acct: uri
127 $xrd = $disco->lookup($profile->getAcctUri());
130 common_debug('Will try to find magic-public-key from XRD of profile id=='.$profile->getID());
132 if (Event::handle('MagicsigPublicKeyFromXRD', array($xrd, &$pubkey))) {
133 $link = $xrd->get(Magicsig::PUBLICKEYREL);
134 if (is_null($link)) {
136 throw new Exception(_m('Unable to locate signer public key.'));
138 $pubkey = $link->href;
140 if (empty($pubkey)) {
141 throw new ServerException('Empty Magicsig public key. A bug?');
144 // We have a public key element, let's hope it has proper key data.
146 $parts = explode(',', $pubkey);
147 if (count($parts) == 2) {
148 $keypair = $parts[1];
150 // Backwards compatibility check for separator bug in 0.9.0
151 $parts = explode(';', $pubkey);
152 if (count($parts) == 2) {
153 $keypair = $parts[1];
157 if ($keypair === false) {
158 // For debugging clarity. Keypair did not pass count()-check above.
159 // TRANS: Exception when public key was not properly formatted.
160 throw new Exception(_m('Incorrectly formatted public key element.'));
167 * The current MagicEnvelope spec as used in StatusNet 0.9.7 and later
168 * includes both the original data and some signing metadata fields as
169 * the input plaintext for the signature hash.
173 public function signingText() {
174 return implode('.', array($this->data, // this field is pre-base64'd
175 Magicsig::base64_url_encode($this->data_type),
176 Magicsig::base64_url_encode($this->encoding),
177 Magicsig::base64_url_encode($this->alg)));
182 * @param <type> $text
183 * @param <type> $mimetype
184 * @param Magicsig $magicsig Magicsig with private key available.
186 * @return MagicEnvelope object with all properties set
188 * @throws Exception of various kinds on signing failure
190 public function signMessage($text, $mimetype)
192 if (!$this->actor instanceof Profile) {
193 throw new ServerException('No profile to sign message with is set.');
194 } elseif (!$this->actor->isLocal()) {
195 throw new ServerException('Cannot sign magic envelopes with remote users since we have no private key.');
198 // Find already stored key
199 $magicsig = Magicsig::getKV('user_id', $this->actor->getID());
200 if (!$magicsig instanceof Magicsig) {
201 // and if it doesn't exist, it is time to create one!
202 $magicsig = Magicsig::generate($this->actor->getUser());
204 assert($magicsig instanceof Magicsig);
205 assert($magicsig->privateKey instanceof Crypt_RSA);
207 // Prepare text and metadata for signing
208 $this->data = Magicsig::base64_url_encode($text);
209 $this->data_type = $mimetype;
210 $this->encoding = self::ENCODING;
211 $this->alg = $magicsig->getName();
213 // Get the actual signature
214 $this->sig = $magicsig->sign($this->signingText());
218 * Create an <me:env> XML representation of the envelope.
220 * @return string representation of XML document
222 public function toXML(Profile $target=null, $flavour=null) {
223 $xs = new XMLStringer();
224 $xs->startXML(); // header, to point out it's not HTML or anything...
225 if (Event::handle('StartMagicEnvelopeToXML', array($this, $xs, $flavour, $target))) {
226 // fall back to our default, normal Magic Envelope XML.
227 // the $xs element _may_ have had elements added, or could get in the end event
228 $xs->elementStart('me:env', array('xmlns:me' => self::NS));
229 $xs->element('me:data', array('type' => $this->data_type), $this->data);
230 $xs->element('me:encoding', null, $this->encoding);
231 $xs->element('me:alg', null, $this->alg);
232 $xs->element('me:sig', null, $this->getSignature());
233 $xs->elementEnd('me:env');
235 Event::handle('EndMagicEnvelopeToXML', array($this, $xs, $flavour, $target));
237 return $xs->getString();
241 * Extract the contained XML payload, and insert a copy of the envelope
242 * signature data as an <me:provenance> section.
244 * @return DOMDocument of Atom entry
246 * @fixme in case of XML parsing errors, this will spew to the error log or output
248 public function getPayload()
250 $dom = new DOMDocument();
251 if (!$dom->loadXML(Magicsig::base64_url_decode($this->data))) {
252 throw new ClientException('Malformed XML in Salmon payload');
255 switch ($this->data_type) {
256 case 'application/atom+xml':
257 if ($dom->documentElement->namespaceURI !== Activity::ATOM
258 || $dom->documentElement->tagName !== 'entry') {
259 throw new ServerException(_m('Salmon post must be an Atom entry.'));
261 $prov = $dom->createElementNS(self::NS, 'me:provenance');
262 $prov->setAttribute('xmlns:me', self::NS);
263 $data = $dom->createElementNS(self::NS, 'me:data', $this->data);
264 $data->setAttribute('type', $this->data_type);
265 $prov->appendChild($data);
266 $enc = $dom->createElementNS(self::NS, 'me:encoding', $this->encoding);
267 $prov->appendChild($enc);
268 $alg = $dom->createElementNS(self::NS, 'me:alg', $this->alg);
269 $prov->appendChild($alg);
270 $sig = $dom->createElementNS(self::NS, 'me:sig', $this->getSignature());
271 $prov->appendChild($sig);
273 $dom->documentElement->appendChild($prov);
276 throw new ClientException('Unknown Salmon payload data type');
281 public function getSignature()
283 if (empty($this->sig)) {
284 throw new ServerException('You must first call signMessage before getSignature');
289 public function getSignatureAlgorithm()
294 public function getData()
299 public function getDataType()
301 return $this->data_type;
304 public function getEncoding()
306 return $this->encoding;
310 * Find the author URI referenced in the payload Atom entry.
312 * @return string URI for author
313 * @throws ServerException on failure
315 public function getAuthorUri() {
316 $doc = $this->getPayload();
318 $authors = $doc->documentElement->getElementsByTagName('author');
319 foreach ($authors as $author) {
320 $uris = $author->getElementsByTagName('uri');
321 foreach ($uris as $uri) {
322 return $uri->nodeValue;
325 throw new ServerException('No author URI found in Salmon payload data');
329 * Attempt to verify cryptographic signing for parsed envelope data.
330 * Requires network access to retrieve public key referenced by the envelope signer.
332 * Details of failure conditions are dumped to output log and not exposed to caller.
334 * @param Profile $profile profile used to get locally cached public signature key
335 * or if necessary perform discovery on.
339 public function verify(Profile $profile)
341 if ($this->alg != 'RSA-SHA256') {
342 common_log(LOG_DEBUG, 'Salmon error: bad algorithm: '._ve($this->alg));
346 if ($this->encoding != self::ENCODING) {
347 common_log(LOG_DEBUG, 'Salmon error: bad encoding: '._ve($this->encoding));
352 $magicsig = $this->getKeyPair($profile, true); // Do discovery too if necessary
353 } catch (Exception $e) {
354 common_log(LOG_DEBUG, "Salmon error: getKeyPair for profile id=={$profile->getID()}: "._ve($e->getMessage()));
358 if (!$magicsig->verify($this->signingText(), $this->getSignature())) {
359 common_log(LOG_INFO, 'Salmon signature verification failed for profile id=='.$profile->getID());
360 // TRANS: Client error when incoming salmon slap signature does not verify cryptographically.
361 throw new ClientException(_m('Salmon signature verification failed.'));
363 common_debug('Salmon signature verification successful for profile id=='.$profile->getID());
364 $this->setActor($profile);
369 * Extract envelope data from an XML document containing an <me:env> or <me:provenance> element.
371 * @param DOMDocument $dom
372 * @return mixed associative array of envelope data, or false on unrecognized input
374 * @fixme may give fatal errors if some elements are missing
376 protected function fromDom(DOMDocument $dom)
378 $env_element = $dom->getElementsByTagNameNS(self::NS, 'env')->item(0);
380 $env_element = $dom->getElementsByTagNameNS(self::NS, 'provenance')->item(0);
387 $data_element = $env_element->getElementsByTagNameNS(self::NS, 'data')->item(0);
388 $sig_element = $env_element->getElementsByTagNameNS(self::NS, 'sig')->item(0);
390 $this->data = preg_replace('/\s/', '', $data_element->nodeValue);
391 $this->data_type = $data_element->getAttribute('type');
392 $this->encoding = $env_element->getElementsByTagNameNS(self::NS, 'encoding')->item(0)->nodeValue;
393 $this->alg = $env_element->getElementsByTagNameNS(self::NS, 'alg')->item(0)->nodeValue;
394 $this->sig = preg_replace('/\s/', '', $sig_element->nodeValue);
398 public function setActor(Profile $actor)
400 if ($this->actor instanceof Profile) {
401 throw new ServerException('Cannot set a new actor profile for MagicEnvelope object.');
403 $this->actor = $actor;
406 public function getActor()
408 if (!$this->actor instanceof Profile) {
409 throw new ServerException('No actor set for this magic envelope.');
415 * Encode the given string as a signed MagicEnvelope XML document,
416 * using the keypair for the given local user profile. We can of
417 * course not sign a remote profile's slap, since we don't have the
420 * Side effects: will create and store a keypair on-demand if one
421 * hasn't already been generated for this user. This can be very slow
424 * @param string $text XML fragment to sign, assumed to be Atom
425 * @param User $user User who cryptographically signs $text
427 * @return MagicEnvelope object complete with signature
429 * @throws Exception on bad profile input or key generation problems
431 public static function signAsUser($text, User $user)
433 $magic_env = new MagicEnvelope(null, $user->getProfile());
434 $magic_env->signMessage($text, 'application/atom+xml');