A-Shell Reference

Reviewed and revised April 2024

xcall CRYPTO, opcode, status, src, decoding, dst, encoding, cflags {, cipher, key, keybits, cmode, padding {, cbsrc {, iv {, aad, authtag}}}}

CRYPTO provides a collection of cryptographic-related functions.

Parameters

opcode  (Num)  [in]

One of the following:

 

status  (Signed Num)  [out]

Returns the result status of the operation: >= 0 for success (number of bytes output to dst), <0 for errors (see CRYPTERR_xxx in CRYPTO.DEF)

src  (String or BLOB)  [in]

Supplies the input data for the operation. May be either a filespec (AMOS or native), a string, or an arbitrary length of binary data. In the case of an X variable containing binary data, the number of bytes must be specified in the cbsrc parameter. Otherwise the length can be determined from the file size or the string length. Note that in the case of an encoded src string—e.g. hex or base64, the string must be null terminated. See cflags.

decoding  (String)  [in]

Specifies a type of character decoding to perform on the src prior to any further processing, from the table below:

 

dst  (String or BLOB)  [in/out]

The output of the operation.  May be a filespec in AMOS or native format (replacing an existing file or creating a new one), or a string (S) or unformatted (X) variable. If a dynamic variable is used (S,0 or X,0) it must be pre-sized to at least the required size. See cflags.

encoding  (String)  [in]

Specifies a type of character encoding to perform on the dst after the main cryptographic operation, from the same table of encoding choices listed above for the decoding parameter.

cflags  (Num)  [in]

Specifies zero or more options from the following:

Hex-Decimal Values

 

cipher  (Num)  [in]

For encryption/decryption, cryptographic algorithm to use.

 

key  (String or BLOB)  [in]

Key to use for encryption/decryption. For the RSA cipher, must be a file containing the public and/or private key. Supported file formats are: PEM, XML, JWK, DER (PCKCS1 or PKCS8). (See History Note for required library version.) If the file format requires a password, specify it in the aad parameter. For the other ciphers, it may be the key itself, or the name of the file containing the key. As a convenience the key may be specified in hex-encoded format; see cflags. Note that the key size must correspond with the keybits parameter.

keybits  (Num)  [in]

Number of bits in the encryption key. Not required for the RSA cipher, since it can be determined from the PEM file. For AES, the options are 128, 192, or 256 bits. This corresponds 16, 24, or 32 bytes (or twice that if the key is hex-encoded).

mode  (Num)  [in]

For AES cipher, the cipher mode:

 

padding  (Num)  [in]

For the AES cipher, the padding scheme to use:

 

Note that the stream cipher modes (CTR,CFB,OFB,GCM) do not require or use padding and thus ignore the padding parameter; the use of CRYPT_PAD_NA is recommended for clarity. Without padding, the encrypted text is the same size as the plain text, assuming the same encoding. The block cipher modes (ECB and CBC) do require one of the other padding options, all of which will increase the encrypted text size up to a multiple of the block size (i.e. a multiple of 16).

cbsrc  (Num)  [in]

Number of data bytes in the src parameter. Only required when the src is not a file and contains binary data. (If not specified in this case, the raw parameter size will be used.)

iv  (String or BLOB)  [in]

Initialization vector for optional use with CRYPTOP_ENCRYPT/DECRYPT opcodes with the AES cipher (all cipher modes except ECB). For cipher modes other than GCM or ECB, it should match the cipher block size, i.e. 16 bytes for AES (128 bits, not to be confused with the key size). For GCM cipher mode, 96 bits or less is recommended for best efficiency and interoperability. In all cases, it should be unique for any given key, preferably randomly generated. For GCM, it is only necessary that each iv not be used more than once. The same iv used for the encryption must be supplied to the decryption. The iv may be specified as raw bytes (preferably using an X format variable), or as a string of hex digits (in which case the CRYPF_IVHEX flag must be specified.)

aad (String, null terminated)  [in]

Additional authentication data, used in the following two cases:

authtag (String, 33+ bytes)  [in/out]

Required for AES-GCM encryption/decryption. During encryption, an authentication tag is generated from the combination of the aad and the message text and output to this parameter in the form of a string of 32 hex digits. This computed value must then be passed along with the origional aad to the decryption.

 

Comments

Unused parameters, needed as placeholders for later parameters, should be set to "" if of type string or 0 if of type numeric .

AES is a symmetric block cipher, meaning that the same key is used for both encryption and decryption, and that the process works one block at a time. The block length for AES is 128 bits (16 bytes).  This is independent of the key length, which can be 128, 192, or 256 bits. Several different cipher modes are available, which divide into the block modes (ECB and CBC), which pad the text to a multiple of the block size, and stream modes (CTR, CFB, OFB, and GCM) which do not use padding and thus generate encrypted text the same size as the plain text.

ECB mode is relatively weak, using the same key on every block, and thus is normally only used for very short messages for which a different random key is generated for each message.  The other modes are suitable for any size message. CBC increases the security by deriving a new key for each block from the output of the encryption of the previous block. An initialization vector (IV) is typically supplied for use with the first block. In most cases it is essential that the IV be unique for each message, especially if the same key is used for multiple messages.

CTR, CFB, OFB and GCM are all variations of CBC, except that they are stream oriented (not requiring padding to a multiple of the block size). GCM also combines additional authentication data (AAD) with the message (to identify or label the message, i.e. supply metadata for it). An 128 bit authentication tag is generated for the combination of the AAD and the message, and is used along with the AAD to authenticate the decryption (i.e. make sure the decrypted data is not just internally valid, but valid in the context of the specified metadata).

The RSA public/private cipher is asymmetric (different keys used for encryption and decryption). It is extremely useful in situations where a private party (holding the private key) is exchanging messages with the public (which can share the public key). However, it is limited to messages no longer than the key modulus, which is typically 1024 or 2048 bits (128 or 256 bytes), so it is typically used for messages that are naturally short, such as AES keys and message digests.

See Also

History

2022 October, A-Shell 6.5.1721, ASHNET 1.4.186:  CRYPTO encryption/decryption using RSA public/private keys now supports additional file formats beyond PEM: XML, JWK, DER (PKCS1 or PKCS8, raw or base64 encoded). If a password is required, specify it in the aad (additional authentication data) parameter and set the prior unused params to "" or 0 according to their types.

2018 May, A-Shell 6.5.1635:  Add opcode CRYPTOP_HMAC to create HMACs (Hash-based Message Authentication Codes).

2016 December, A-Shell 6.3.1539:  Major upgrade of routine. Added parameters iv, aad, authtag; added five cipher modes (cmode) to use with AES algorithm; added support for Unix; updated ASHINC:cipher.def. Note that CRYPTO as now documented above requires ASHNET 1.9.156.

2014 May, A-Shell 6.1.1385:  Added opcode 6, CRYPTOP_GENPUBKEY.

2013 July, A-Shell 6.1.1355:  Routine added to A-Shell. Note that it requires ASHNET 1.5.137 or higher.

Subtopics

•Public/Private Key

•HMACs

•CRYPTO Examples