Official Maltego Documentation » Server Guides » iTDS Server » Additional Functionality

Additional Functionality


Additional iTDS Functionality

Paired Configuration

Exporting a Configuration File in the Maltego Client

Paired configuration is a way of attaching a Maltego configuration to a particular seed and to make it discoverable when someone follows the seed installation process. Exporting configurations is a way of quickly and easily sharing a pre-configured Maltego environment so that you do not need to go through the tedious process of having to set up each individual client. The process of exporting configurations to a file from the Maltego client is explained in the Maltego userguide.

Once you have exported your config to a .mtz file you no longer need to use the Maltego client as you will be able to configure everything from the iTDS.

Implementation in the iTDS

To add the configuration you have created with the above steps navigate to the "Paired Configurations" section of the iTDS. From here you can create a new paired configuration. You can only have a single paired configuration per seed. An example of adding our previously exported configuration can be seen below:

Once you have added the paired configuration you can modify the seed(s) from the seed section to include the configuration:

After you have added the paired configuration, all Maltego client's that have the seed installed will get the configurations.

Transform Settings

Overview

Transform settings are a means of allowing an additional input when running a transform. Often these are configured as "popups" where the user is prompted for a question. An example of this can be seen splitting an IP address into a Netblock (the popup asks the size of the netblock to split into):

Implementation

Popup settings can be configured on the iTDS via the 'transform settings' section of the web interface. These settings look as follows:

It is important to note the following when configuring a setting:

  • Name - This is the variable name and is what is used within the transform.
  • Display Name - This is what is exposed to the client, with the previous example this would be "Block Size".
  • Default Value - This value is only used if the setting is NOT a popup.
  • Optional - Describes whether a setting must be filled in for this transform or not.
  • Popup - Requests that the setting 'pops up' to the analyst when running a transform.

Note:There is no difference between a setting that pops up and one that does not in terms of implementation.

Changing Popup Settings

If you do mark a setting as 'remember' and it no longer pops up or if you wish to have a setting that was originally not marked as a popup to be one again you can enable/disable this within the client. To do this click on 'Manage Transforms' under the Manage tab. From here you need to find the transform, click on the setting and enable or disable popup as seen below:

Example Code

This code example briefly shows retrieving a setting that has a Name of 'popupVar' in PHP:

//include our MaltegoTDS class(es)
include_once("Maltego.php");

//set return content-type to be XML
header ("content-type: text/xml");

$maltegoInput = new MaltegoTransformInput();
$maltegoTransform = new MaltegoTransformResponse();


if ($maltegoInput->getEntity())
{
	//fetch the popup value (it is a transform field)
	$enteredName = $maltegoInput->transformFields["popupVar"];
	//return as phrase entity containing the above popup value
	$maltegoTransform->addEntity("maltego.Phrase","hello" . $enteredName);
	$maltegoTransform->returnOutput();
}
else
{
	$maltegoTransform->addException("No input entity found");
	$maltegoTransform->throwExceptions();
} 

Another example of using Transform Settings with the .

OAuth Integration

Introduction

OAuth is an open standard for authorization. It allows Maltego users to log into third party providers with their credentials and have an access token returned to the tool. This access token can then be sent to the transform which in turn can request information from the provider on behalf of the end user.

Within the iTDS there are two types of providers that can be added:

  1. A new provider – one that has not been seen before on this server (and likely within your client).
  2. A previously used provider – one that has been used previously in the tool so that you can re-use the access token.

OAuth within the Maltego Client

Within the Maltego client, the OAuth providers can be found under the Transforms tab by clicking on the "Manage Services" button:

After clicking on that button you will be presented with the Service Manager panel that describe the available OAuth providers configured as well as the ability to login and logout of the various providers:

Within the application, if any transforms require OAuth tokens, you will be prompted to login before the transform is run.

Configuring the OAuth providers

The OAuth settings required for a provider are as follows:

  • Authenticator name - This is the overall OAuth provider name.
  • Description - A description of the OAuth provider, something like "LinkedIn Provider".
  • Version - Which version of OAuth being used, the currently supported versions are OAuth 2.0 and OAuth 1.0a.
  • Access token endpoint - The endpoint that the Maltego client will request for the access token.
  • Request token endpoint - The endpoint that the Maltego client will send the user to for application approval.
  • Authorization URL - URL used to by the client to approve/grant access tokens.
  • Application/API key - API or Application key that the developer is issued from the provider.
  • Application/API secret - API or Application secret/private key that the developer is issued from the provider.
  • Icon - Base64 of the 64x64 pixel Icon to be used within the Maltego client application.
  • Access token variable name - The variable name used within the transforms (this is what the transform will receive).
  • Variable description - Simply describes the variable used.
  • Public Key - The public key used to encrypt the access token when it is sent to the transform code itself.

Configuring the iTDS for a NEW OAuth provider (LinkedIn)

In this section we will look at an example provider, in this case LinkedIn, but it should be relatively similar with all major providers.

The first step is to configure the application on the provider network, usually in the developer section and would be something like the following:

The next step is configuring where the OAuth provider (In this example LinkedIn) will redirect the browser to after the end user has accepted the application:

After adding the application with the provider and configuring it as above you will receive your API and secret keys for your specific calls as follows:

Configuring the OAuth settings on the iTDS

Now we have created our application with the provider we can configure the iTDS to use these settings within Maltego. If you are running your own internal OAuth application this information might already be provided for you. Browse to the iTDS interface. From the main page select "OAuth Settings" and then select "Add OAuth Setting" at the bottom of the list.

Initially you are given the option to either re-use previous OAuth configurations or create a new one. In this case we want to create a new OAuth configuration and can select the “New OAuth configuration” checkbox. From there we will be asked to provide the details for this configuration (as described previously in this document).

The most important fields to remember are the Authenticator name, Access Token Variable Name and Public key (and private key as described in the following section) as these are the fields you will need to provide if you wish for other developers to use the same OAuth tokens within their transforms.

Why do we use a Public and Private Key?

Because tokens that are used within the OAuth communications are 50% of the authorization process (the other being the application keys), these tokens cannot be transmitted in the clear. As such this process is done with a public and private key in the following manner:

  • Maltego client knows about the public encryption key and this is sent during the discovery process.
  • Maltego client will retain the OAuth tokens after the analyst has logged into the provider.
  • When running the transform Maltego will send the tokens as follows:
    • Encrypt the token and token secret with the public encryption key (RSA/ECB/PKCS1Padding).
    • Base64 encode both of them.
    • Concatenate these two base64, encrypted strings joined by a ‘$’ symbol.
    • The final string would be B64(Crypt(Token))$B64(Crypt(TokenSecret)).
  • The transform will know what the private key (either one generated when creating the OAuth configuration or one you already had) and be able to decode the token in the following way:
    • Separate the string on the $ symbol.
    • Base64 decode each section.
    • Decrypt the token and token secret with the private key.
  • Transform can then use the token and token secret to execute the API call against the provider to get the data

Public and private keys can be generated on the iTDS by clicking on the ‘Generate an RSA key pair’ link on the Add OAuth settings page:

Note You will note that the private key is NOT saved anywhere, it will be up to the developers to securely store this private key privately..

Configuring the iTDS for a previous OAuth provider (LinkedIn)

For this example we will be configuring the OAuth settings as per our current provider (LinkedIn) with the following:

Meta Information

This is the meta information used to describe the OAuth setting.

Name: paterva.oauth.linkedin
Description: LinkedIn OAuth example
Version: OAuth 1.0a

Provider Information

This information is provided from the OAuth provider (LinkedIn)

Access token endpoint: https://api.linkedin.com/uas/oauth/accessToken
Request token endpoint: https://api.linkedin.com/uas/oauth/requestToken
Authorization URL: https://api.linkedin.com/uas/oauth/authenticate?oauth_token={token}
Application Key: 77t9jux0135g3v
Application Secret: E5kLMplGRdwpsqLo

Other Information

This information is used within the application (Icon), the iTDS (Public Key) or in the transform code (Access token variable name). The icon field is a Base64 encoded 64x64 pixel icon to be used within the tool.

Icon: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAfxJREFUeNqUk89r1EAUx78zmWncH83abluoUAhFFNRa/Af8AxShXsSz4MGD4MGjnsSrXgQvni0UxPSw4KH+CQtSqpZWNFDo4rqRbay7biaZODPb3WSlFfYdkvdm3uc7b15eyMzd1eVqtew5TtHFGBaGHT8IDlfY9FTRe3Djintu1hmHx86P0H2+XvdYxSm4P7vA250D7LVCLDqWSfgaJliYOVl0/hTB9FTJZfaEha2ghyQFFsoUz26eNwn332yjeRidKBD8BphFwOI4QTdK+qsszaWkiETy32tolsUqKYr7iRu7B7i39sn461stVJ3CCMAowVylqE6mfQGhBeLYONooIXh564LxX9ffY//hVeNv7v/C5TOTaHcFHte+4HMgYFEKzdIkUXAikagqpJTHlqphbacLHE+un8X3dqfPKJZqkKepUpNIZdYDkhNYrTfwqLY7FBFHjGapVGUMApbDSpwN/afvfHgfWlkvVJ5mNMt0GUMBmgmUbTbSvH+baRjFMl2OpYI/QuKoucYmJzIBa5Q3sWY0S/XDVgs9pZbSTIHbPJsItZ7f075mNEtm77xKry1dxHZHoq0+gp07eWC9KDbvwV5FwYtcorb5UV0hEv5es+FempsH5/bxI1fiI6EQPXxrNtT8CJ9Ubr9YVhPkqbLG+p2JlD5kuvJXgAEAMvzqSyjfahkAAAAASUVORK5CYII=

Access Token Variable Name: maltego.web.api.key.linkedin
Variable Description: OAuth token variable
Public Key 
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDcAKHjZy3cUS7SLXGUiH0mPeD6
KvVZHhaaggRJz5ZiN+hHUDZFciOAiTa4FmjMwDR/2wYoPjXdVj8Tt9WRump+SWaL
PNEDQd5LQtw+r4kYiKnPzXGKUmLQgkfcitJRlOJ05+xjktMlEDKud1CEutI+/VC4
+0DAGwY9/oAnRj/aAQIDAQAB
-----END PUBLIC KEY-----


Once this has been completed you can click on ‘Add OAuth Setting’ at the bottom of the page to add this OAuth setting.

Pairing OAuth Settings with Transforms

Due to OAuth settings being specific per transform – one could have multiple transforms each using their own provider or none. OAuth settings are paired with transforms rather than with a specific seed. Within the iTDS interface for adding transforms you will now see a new section that will allow you to pick the OAuth settings required for this transform:

Implementing OAuth Settings in Code

This is a brief snippet of PHP code using the LinkedIn OAuth library as a reference of it being used within the transform:

//LinkedIn OAuth Library
	include_once("oauth/linkedinoauth.php");
	// Encrypted OAuth key
	$key = $maltegoInput->transformFields["maltego.web.api.key.linkedin"]; 
	//Our Private Key *DO NOT SHARE THIS*
	$real_private_key = '-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBANwAoeNnLdxRLtIt
cZSIfSY94Poq9VkeFpqCBEnPlmI36EdQNkVyI4CJNrgWaMzANH/bBig+Nd1WPxO3
1ZG6an5JZos80QNB3ktC3D6viRiIqc/NcYpSYtCCR9yK0lGU4nTn7GOS0yUQMq53
UIS60j79ULj7QMAbBj3+gCdGP9oBAgMBAAECgYAvE9OQnduqcZTbVO4hIrPlIwip
f9fQoiekGH5ibRF5Iw2JdRin86y1LKeQ7PqwFdEmKvA+XFGac4I77fK9pG51AftQ
wgHriyHlpocXXESakLiWuI/6kPjooyBYsPTgjJcsFW/XnHUUTCwEZXfOIusG1Alz
KnXPINmKIJeGIIjRoQJBAPoDysJLcdHRcyeYS3rJReDFgqSHQ66gR4gX7moxK2DK
Kr2Tp51c4TuacN0RWIf2+6g5VOhK5jabMhTNlzQi2usCQQDhROkgE7SKPLq+4m/b
4y9KhIMsAXA+DkxMiIED56gl7z3QdpROBRLiwR7DD1pxMT736m0z8lE6RlZaHVaI
IQvDAkAW4a325ky+dTrizs9pp24byjfQswiAvO6PCBGr6mAb9aS/wPnALzX17IaT
1PiTSQlzNfwNXn1/VejZeo9yGBaNAkBvsAfZlIuFoliAfaoyHjB7RLn4Xno0+kfQ
BjnZIskWjchbC/+5swBLFq7WzUztJBpxNnSQNcsaFneH1FXrxl6bAkBvolQxT61l
I29vP3dS1zSgqvRbos9jl63o6Igl6ombyVb6Nqp+LSEuabFKYMWGwLJs0I7NrhbJ
b8yegsQP+/8Z
-----END PRIVATE KEY-----';
	
	//Lets seperate the two encrypted sections
	$parts = explode("$",$key);
	//B64 decode each section
	$token = base64_decode($parts[0]);
	$secret = base64_decode($parts[1]);

	//Decrypt each segment with our private key
	openssl_private_decrypt($token, $decrypted_token, $real_private_key,OPENSSL_PKCS1_PADDING);
	openssl_private_decrypt($secret, $decrypted_secret, $real_private_key,OPENSSL_PKCS1_PADDING);

	$consumer_key = "77t9jux0135g3v"; // API key
	$consumer_secret = "E5kLMplGRdwpsqLo"; // API Secret
	
	//Lets create a new LinkedIn Object and fetch the current user details
	$linkedInObj = new LinkedInOAuth($consumer_key,$consumer_secret,$decrypted_token,$decrypted_secret);
	//Fetch current user data
	$profile_result = $linkedInObj->oAuthRequest('http://api.linkedin.com/v1/people/~');
	$profile_data = simplexml_load_string($profile_result);
	//Create 
	$ent = $mt->addEntity("maltego.Person",$profile_data[0]->{'first-name'} . " " . $profile_data[0]->{'last-name'});
	$mt->returnOutput();

Where Next?

More information on writing your own custom transforms in Python for the iTDS can be found on the iTDS transforms page. This page will cover more of the advanced aspects of the transform library.

Code examples for both Python and PHP can also be found from the iTDS Transform example page.


Official Maltego Documentation
-»
Server Guides
-»
iTDS Server
-»
Additional Functionality

© Copyright 2017, Paterva PTY Limited