Scripting Server

Card - Reference Documentation

CryptoScript interpreter

Index of Methods

Properties

Type Name Description
ByteString response Last response APDU received from ICC

Constructor

Prototype

CryptoScript(Key key, Number stacksize)

Description

Create a new CryptoScript interpreter bound to a key with a given stack size.

Arguments

Type Name Description
Key key The key object for which the script shall be executed
Number stacksize The number of bytes allocated for the execution stack

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var key = new Key();
var csi = new CryptoScript(key, 1000);

isEmpty()

Prototype

boolean isEmpty

Description

Return true if stack is empty

Return

Boolean True if stack is empty

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


assert(csi.isEmpty());

getStack()

Prototype

ByteString[] getStack()

Description

Return the current evaluation stack, with the topmost stack entry in index 0 of the array.

Return

ByteString[] List of stack elements

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var stack = csi.getStack();
assert(stack.length == 0);

push()

Prototype

push(ByteString value)

Description

Push a byte string onto the stack

This method records an op code if recording is enabled with record().

Arguments

Type Name Description
ByteString value The ByteString to push onto the stack

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var ref = new ByteString("012345", HEX);
csi.push(ref);
var stack = csi.getStack();
assert(stack.length == 1);
assert(stack[0].equals(ref));
csi.pop();
assert(csi.isEmpty());

top()

Prototype

ByteString top()

Description

Return copy of topmost stack element

This method records an op code if recording is enabled with record().

For convenience, this method returns the topmost element, while in the SmartCard-HSM the topmost element is only removed, but not returned anywhere.

Return

ByteString Copy of the topmost element on the stack

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.push(ref);
assert(csi.top().equals(ref), "top() failed");
csi.pop();
assert(csi.isEmpty());

pop()

Prototype

ByteString pop()

Description

Take topmost element from stack

This method does not record an op code.

Return

ByteString Copy of the topmost element on the stack

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.push(ref);
assert(csi.pop().equals(ref), "pop() failed");

record()

Prototype

record()

Description

Start recording the op code sequence for later retrieval using collect().

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


// See collect() for an example

collect()

Prototype

ByteString collect()

Description

Collect sequence of op codes generated after calling record.

The resulting byte string can be executed using eval() or the CryptoScript interpreter in the SmartCard-HSM.

Return

ByteString Sequence of op codes

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var ref = new ByteString("012345", HEX);

// Start recording op codes
csi.record();

// Push reference and record op code
csi.push(ref);

// Collect all recorded op codes
var code = csi.collect();

// Element is still on stack
assert(csi.pop().equals(ref));
assert(csi.isEmpty());

// Playback recorded op code sequence
csi.eval(code);

// Result must be the same
assert(csi.pop().equals(ref));
assert(csi.isEmpty());

eval()

Prototype

eval(ByteString sequence)

Description

Evaluate a secure of op codes recorded with collect()

Arguments

Type Name Description
ByteString sequence Sequence of op codes

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


//Do nothing
csi.eval(new ByteString("0000", HEX));

dup()

Prototype

dup()

Description

Duplicate topmost stack element.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

csi.push(ref);
csi.dup();

var code = csi.collect();

csi.pop().equals(ref);
csi.pop().equals(ref);
assert(csi.isEmpty());

// Replay
csi.eval(code);

csi.pop().equals(ref);
csi.pop().equals(ref);
assert(csi.isEmpty());

swap()

Prototype

swap()

Description

Swap two topmost stack elements.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var ref2 = new ByteString("Hello", ASCII);

csi.push(ref);
csi.push(ref2);
csi.swap();

var code = csi.collect();

csi.pop().equals(ref);
csi.pop().equals(ref2);
assert(csi.isEmpty());

//Replay
csi.eval(code);

csi.pop().equals(ref);
csi.pop().equals(ref2);
assert(csi.isEmpty());

concat()

Prototype

concat()

Description

Concat two topmost stack elements.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var ref1 = new ByteString("My ", ASCII);
var ref2 = new ByteString("first ", ASCII);
var ref3 = new ByteString("CryptoScript", ASCII);

csi.push(ref1);
csi.push(ref2);
csi.push(ref3);
csi.concat();
csi.top().toString(ASCII).equals("first CryptoScript");
csi.concat();

var code = csi.collect();

csi.pop().equals(new ByteString("My first CryptoScript", ASCII));
assert(csi.isEmpty());

//Replay
csi.eval(code);

csi.pop().equals(new ByteString("My first CryptoScript", ASCII));
assert(csi.isEmpty());

range()

Prototype

range(from, length)

Description

Extract the range of bytes from the topmost operand on the stack.

A positive value in from denotes the 0-based offset in the byte array. A negative value denotes the offset relative to the end of the byte array, i.e. a value of -1 denotes the last byte in the array.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var op = new ByteString("010203", HEX);

csi.push(op);
csi.range(0, 1);
assert(csi.pop().equals(op.left(1)));

csi.range(1, 1);
assert(csi.pop().equals(op.bytes(1, 1)));

csi.range(2, 1);
assert(csi.pop().equals(op.bytes(2, 1)));

csi.range(-1, 1);
assert(csi.pop().equals(op.right(1)));

csi.pop();
assert(csi.isEmpty());

var code = csi.collect();
print(code);

//Replay
csi.eval(code);

assert(csi.isEmpty());

xor()

Prototype

xor()

Description

XOR the two topmost operands on the stack.

The resulting operand has the same size than the longer operands. The short operand is repeated as often as required to process the longer operand.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var opA5 = new ByteString("A5", HEX);
var opA5s = new ByteString("A5A5A5", HEX);
var op0 = new ByteString("000000", HEX);

csi.push(opA5);
csi.dup();
csi.xor();

assert(csi.pop().equals(op0.left(1)));
assert(csi.isEmpty());


csi.push(opA5s);
csi.push(opA5);
csi.xor();

assert(csi.pop().equals(op0));
assert(csi.isEmpty());


csi.push(opA5);
csi.push(opA5s);
csi.xor();

assert(csi.pop().equals(op0));
assert(csi.isEmpty());

var code = csi.collect();
print(code);

//Replay
csi.eval(code);

assert(csi.isEmpty());

sha1()

Prototype

sha1()

Description

Apply SHA-1 digest to topmost element on the stack and push result.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var ref = new ByteString("Hello World", ASCII);
csi.push(ref);
csi.sha1();

var crypto = new Crypto();
var digest = crypto.digest(Crypto.SHA_1, ref);

var code = csi.collect();
print(code);

assert(csi.pop().equals(digest));
csi.pop();
assert(csi.isEmpty());

//Replay
csi.eval(code);

assert(csi.pop().equals(digest));
csi.pop();
assert(csi.isEmpty());

sha256()

Prototype

sha1()

Description

Apply SHA-256 digest to topmost element on the stack and push result.

This method records an op code if recording is enabled with record().

Return

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


csi.record();

var ref = new ByteString("Hello World", ASCII);
csi.push(ref);
csi.sha256();

var crypto = new Crypto();
var digest = crypto.digest(Crypto.SHA_256, ref);

var code = csi.collect();
print(code);

assert(csi.pop().equals(digest));
csi.pop();
assert(csi.isEmpty());

//Replay
csi.eval(code);

assert(csi.pop().equals(digest));
csi.pop();
assert(csi.isEmpty());