ArcGIS for Developers

MessageAuthenticationCode QML Type

Provides a way to generate hashed message authentication codes (HMACs). More...

Import Statement: import ArcGIS.AppFramework 1.0

Properties

Methods

Detailed Description

The MessageAuthenticationCode component provides a way to generate hashed message authentication codes (HMACs), using a cryptographic algorithm and a provided key to hash provided text or binary data. There is no functionality within the AppFramework to decrypt these hashes once encrypted, as they are intended for communication with external systems such as the Amazon Web Services REST API.

This code sample demonstrates the behavior of MessageAuthenticationCode. Enter text to hash, and optionally a key, and the resulting HMAC will be displayed below.

Item {
        MessageAuthenticationCode {
                id: macObj
                // hexOutput and KeyAsBytes are true by default
                algorithm: CryptographicHash.Md4
                key: AppFramework.binaryData("key");
                onResultChanged: {
                        macText.text = result.data.toString();
                }
        }

        TextField {
                id: input
                placeholderText: qsTr("Enter text to hash")
                width: parent.width - 10
                onTextChanged: {
                        // Set input text as data that you want to hash
                        macObj.data = text
                }
        }

        TextField {
                id: secretKey
                placeholderText: qsTr("Enter Key")
                width: parent.width - 10
                anchors.top: input.bottom
                onTextChanged: {
                        macObj.key = AppFramework.binaryData(text);
                }
        }

        Text {
                id: displayText
                text: qsTr ("Mac: ")
                anchors.top: secretKey.bottom
        }

        TextArea {
                id: macText
                width: parent.width - displayText.width - 10
                wrapMode: Text.Wrap
                readOnly: true
                anchors.left: displayText.right
                anchors.verticalCenter: displayText.verticalCenter
        }
}

Property Documentation

algorithm : CryptographicHash::Algorithm

The algorithm being used to hash the authentication code. This is informed by the Algorithm enum in CryptographicHash.


data : object

The binary or text message to hash.


[read-only] error : string

Returns an error if the hashing process has failed.


hexOutput : bool

If true, the resulting HMAC will be output as hexidecimal. Default value is true.


key : BinaryData

The secret key used to hash the message.


keyAsBytes : bool

If true, the input for the key property will be stored as bytes. Default value is true.


[read-only] result : BinaryData

Returns the final authentication code.


[read-only] resultValid : bool

Returns true if the result of the hashing process is valid. Otherwise, returns false.


Method Documentation

BinaryData hmacSHA256(data, binarydata key)

A shortcut method to immediately encrypt the given data, with the provided string and using the SHA-256 algorithm.

The data parameter

The message to encrypt into the authentication code.

The key parameter

The key used to encrypt the message into the authentication code.


BinaryData hmacSHA256(data, binarydata key, bool keyAsBytes)

A shortcut method to immediately encrypt the given data, with the provided string and using the SHA-256 algorithm. The boolean value determines whether the key will be read as bytes.

This code sample displays a segment of a greater usage of this method, packaging the hashed code as a request to a server.

Item {
        function getCached(key) {
                var cached = app.settings.value(key, "");
                if(cached > "") {
                        return JSON.parse(cached);
                } else {
                        return undefined;
                }
        }

        function setCached(key, value){
                app.settings.setValue(key, JSON.stringify(value));
        }

        function clearCached(key) {
                app.settings.setValue(key, "");
        }

        //---------------------------------------------------------------------------------------

        function request(options, callback) {
                var req = new XMLHttpRequest();
                req.onreadystatechange = function(){
                        if (req.readyState === XMLHttpRequest.DONE) {
                                //console.log("pinpoint request response", JSON.stringify(req.getAllResponseHeaders()));
                                callback(JSON.parse(req.responseText > "" ? req.responseText:"{}"), req.getAllResponseHeaders());
                        }
                }
                req.open(options.method, options.url);
                var keys = Object.keys(options.headers);
                for(var index in keys) {
                        var key = keys[index];
                        req.setRequestHeader(key, options.headers[key]);
                }
                req.send(JSON.stringify(options.body));
        }

        //---------------------------------------------------------------------------------------

        // SHA256 hmac
        function hmac(key, data, asBytes, hexOutput) {
                macObj.hexOutput = hexOutput;
                var result = macObj.hmacSHA256(data, key, asBytes);
                return result;
        }

        MessageAuthenticationCode {
                id: macObj
                algorithm: CryptographicHash.Sha_256
        }
}

The data parameter

The message to encrypt into the authentication code.

The key parameter

The key used to encrypt the message into the authentication code.

The keyAsBytes parameter

True if the key will be read as bytes. Otherwise it will be read as text.


reset()

Resets the message data. Calling this method doesn't affect the key.