# Smart Card Shell

- - Home
- - GPError
  - GPSystem
  - ByteString
  - ByteBuffer
  - TLV
  - TLVList
  - Card
  - Atr
  - Key
  - Crypto
  - Application
  - GPApplication
  - GPSecDomain
- - ASN1
  - CardFile
  - IsoSecureChannel
  - ApplFactory
  - GPXML
  - JsScript
  - CardSim
- - X509
  - CRL
  - KeyStore
  - Signed CMS
  - Enveloped CMS
  - CMS Generator
  - XMLSignature
  - SSS
  - OCSPQuery
  - LDAP
  - SOAP
  - URLConnection
- - PKCS11Provider
  - PKCS11Session
  - PKCS11Object
- - OutlineNode
  - Dialog
  - Task
- - Tools
  - Modules
- - OpenSCDP

# Card - Reference Documentation

CryptoScript interpreter

## Index of Methods

- Card() constructor
- isEmpty()
- getStack()
- push()
- top()
- pop()
- record()
- collect()
- eval()
- dup()
- swap()
- concat()
- range()
- xor()
- sha1()
- sha256()

## 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());

© Copyright 2003 - 2024 CardContact Systems GmbH , Minden, Germany