BigNumber object

HashCryptStreams

BigNumber object

1. Creation and ProgID
2. Overview
3. Members reference

Creation and ID-s

Threading model: Both
Program ID: newObjects.crypt.Number
ClassID: {53A9F5FB-CBD1-4AF0-A72B-47B20E6AEAE7}
Threading model: Free
ProgramID: newObjects.crypt.Number.free
ClassID: {9E06C3FA-62A2-409d-8F61-EFA64C96AE01}

Overview

This object implements basic arithmetic and some more extended operations with long numbers. By "long" we mean numbers with unlimited length. The programming language you use can provide you with arithmetic operations over 32 bit, 64 bit some languages with even greater numbers, but there is always a limit and it is not too far. So, when you need to perform such operations with much greater numbers (for example 512 bit, 1024 bit or even numbers long 4096 and more bits) you cannot do that directly.

Basically the RSACrypt object is implemented with the same code that backs this object. In fact you can implement RSA yourself and not use the built-in object and it will cost you only a few lines of code. For example the RSACrypt.Encrypt method is as simple as bn.ModExp(SecretKey,Modulus) where bn is the a BigNumber object containing the message. Of course the use of this object is not limited to the opportunity to re-implementing RSA yourself - there are other interesting algorithms and some other areas where big numbers may come handy.

Note that the number can be initialized with data in various ways - you can pass binary data (array of bytes) or put a string representation of the number (see the Value, Hex, Binary and Text properties). This enables you to use almost any existent source of data and convert it to a number with minimal effort. Of course some applications will need more complex operations with the raw data before converting it to a big number. For that purpose you should consider the SFBinaryData object from the ActiveX Pack1's core DLL. It provides wide variety of binary data manipulations that enable you to cut/convert the data you need to work with. For example you may need to extract the contents of a field in a binary header of certain file, or you may need to ensure the byte order is correct and so on. There is no point in duplicating these features in the BigNumber object - its purpose is only to provide the arithmetic.

Lets demonstrate a basic usage:

Set bn = Server.CreateObject("newObjects.crypt.Number")
' In NSBAsic this will be AddObject "newObjects.crypt.Number", bn
bn.Value = "12345678901234567890123456789012345678901234567890"
' Lets multiply it by another big number. No need to go through CreateObject again
' you can create new BigNumber objects from the existing ones much easier
Set bn2 = bn.NewNumber("9876543210987654321098765432109876543210")
Set result = bn.Mul(bn2)
' And display the result somewhere
Response.Write bn.Value
' in NSBasic you may use MsgBox bn.Value for instance
' And lets display it as Hex:
Response.Write bn.Hex

Note that the result of an operation is a new BigNumber object, thus the operations are performed in the general form of Set = object.Operation(arguments). Where object is the first BigNumber participating in the operation and the other arguments are supplied as parameters.

The members follow a convention that enables you to skip the creation of a new BigNumber object in order to pass it as argument. You can supply the argument(s) as decimal strings or as binary data directly. They will be processed and converted to big numbers internally. However, note that while the object can be initialized from almost everything (decimal, hexdecimal string, binary data, even text) you can pass direct arguments to the operation methods only some of these formats (decimal string, binary data, or prepared BigNumber object). This is a kind of sacrifice in the name of usage convenience. Enabling more formats to be specified as arguments will require additional parameters that describe the arguments and make the object's usage more difficult. When you need to specify an argument in format not supported in argument just create a BigNumber before calling the method and use the appropriate property to init it (see Hex, Text, Binary, Value properties below).

Note the NewNumber method. It enables you create new BigNumber objects without need to call CreateObject, AddObject or whatever is the standard object creation mechanism in the language you use. This is much shorter and faster. If you have a lot of work with big numbers, better create one in the beginning and use to create others as needed.

Reference

	Binary	Syntax: object.Binary = v v = object.Binary Initializes/gets the number from/as a binary data (array of bytes - variant containing VT_UI1 \| VT_ARRAY)
	Hex	Syntax: object.Hex = v v = object.Hex Initializes/gets the number from/as a hexdecimal string. Example: mynum.Hex = "0F56ACe3b36234e"
	Text	Syntax: object.Text[(cp)] = v v = object.Text[(cp)] Initializes the number from a text. This property is here for some convenience, what it does is to represent as a big number the passed string. The string is converted using the specified code page (optional - if omitted the current code page is used). If the cp (code page) parameter is set to -1 the string is processed as UNICODE. the resulting buffer from the conversion is loaded into the number. If UNICODE is selected no little/big endian conversion is performed. The property can be used if you need to perform some encryption or other processing with strings when it will be used in your application(s) only. However for applications that aim to implement certain standards more precise conversions must be used. We recommend the SFBinaryData object as means to compose/decompose a data block for encryption/decryption. The standards usually involve more than simple strings thus a specialized object for binary block manipulation is more appropriate for the tasks required. Once composed outside the data block can be assigned using the Binary property.
	Value	Syntax: object.Value = v v = object.Value DEFAULT property. Assigns/gets the number value. When assigning you can pass a decimal string representation of the number, a binary data (same as the Binary property), another BigNumber object, another object which has default property returning binary data or a number represented as decimal string. When reading the property the number is returned as decimal string. Example: mynum.Value = "123456789012345678901234567890" decnum = mynum.Value
	Add	Syntax: Set result = object.Add(num) Adds the number to num and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data). Example: Set result = mynum.Add("12345678901234567890")
	Cmp	Syntax: r = object.Cmp(num) Compares the object with the num. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data). The returned result is: -1 - if object < num 0 - if object = num 1 - if object > num
	Dec	Syntax: object.Dec([v]) Decrements the number by 1 or by the specified value if v is not omitted.
	Div	Syntax: Set result = object.Div(num) Divides the object by the passed num and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data).
	GCD	Syntax: Set result = object.GCD(num) Finds the Greater Common Divisor of the object and the passed num and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data).
	Inc	Syntax: object.Inc([v]) Increments the number by 1 or by the specified value if v is not omitted.
	Mod	Syntax: Set result = object.Mod(num) Returns the remainder of the division of the object by the passed num as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data).
	ModExp	Syntax: Set result = object.ModExp(e,m) Calculates object^e mod m and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data).
	ModInv	Syntax: Set result = object.ModExp(m) Calculates modular inverse of the object (modulo m).
	Mul	Syntax: Set result = object.Mul(num) Multiplies the object and the passed num and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data).
	NewNumber	Syntax: Set result = object.NewNumber([init]) Creates a new BigNumber object. If init is omitted it is initialized to 0, otherwise the new object is initialized with init. The init can be everything you can assign to the Value property (another BigNumber, decimal string, binary data). Consider this as a shorter more convenient way to create new BigNumber objects when you already have some in use. Use it instead of CreateObject (AddObject in NSBasic, Server.CreateObject in ALP) to reduce the code needed.
	Random	Syntax: Set result = object.Random(size [,ensuresize [, odd]]) Creates and returns a new BigNumber initialized with random value. The new object is initialized so that its length is size bytes (when represented as binary data). As the random generation cannot guarantee that you wont be receiving 0 as most significant byte (or part of it) the actual size may be less than the size specified. To combat this you can use the optional Boolean parameter ensuresize. If specified an set to True the new number is exactly the specified size and its 2 most significant bits are always set. If you want the new random number to be odd use the next optional Boolean parameter - odd. Pass True to force odd numbers to be generated. For example RSA sets both optional parameters to True when it generates random numbers. Example: Set mynum = othernum.Random(256,True,True) ' Generates random number 256 bytes long (2048 bits) which is odd.
	Sub	Syntax: Set result = object.Sub(num) Subtracts num from the object and returns the result as new BigNumber object. The num can be everything you can assign to the Value property (another BigNumber, decimal string, binary data). Example: Set result = num1.Sub("123456789012345678901234567890")

...