CRYPTO

Parameters

opcode  (Num  [in]

One of the following:

Symbol	Opcode	Description
CRYPTOP_ENCRYPT	1	Encrypt the src  parameter into the dst parameter
CRYPTOP_DECRYPT	2	Descript the src parameter into the dst parameter
CRYPTOP_GENKEY	3	Generate a random symmetric key
CRYPTOP_ENCODE	4	Encode (or decode) src parameter into dst parameter
CRYPTOP_GENPUBKEY	6	Generate a Public/Private Key file pair, which see for details.
CRYPTOP_HMAC	7	Allows CRYPTO to create HMACs, which see for details.
Definition File: crypto.def

 

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 Raw)  [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:

Encoding/ Decoding	Description
“raw” (or “”)	None
“hex”	Hexadecimal format (each byte of data represented by two hex characters)
“base64”	MIME/base64 (each three bytes of data represented by four bytes from the 64-byte MIME character set); typical format for storing encrypted text
"url"	url format (non-printable characters represented using %xx notation

 

dst  (String or Raw)  [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:

Symbol	value	Description
CRYPF_NONE	&h0000	placeholder for no flags (i.e. all defaults)
CRYPF_SRCFILE	&h0001	src is a filespec (rather than the variable containing the source data)
CRYPF_SRCTEXT	&h0002	src data (after decoding) contains text (as opposed to binary data)
CRYPF_DSTFILE	&h0008	dst is a filespec (rather than a variable to receive the output)
CRYPF_DSTTEXT	&h0010	dst (prior to encoding) will be a text string (as opposed to binary data)
CRYPF_KEYFILE	&h0020	key is a file, rather than the variable containing the key. Applies to CRYPTO_CIPHER_RSA only
CRYPF_KEYHEX	&h0040	key is hex encoded (decode before using)
CRYPF_PUBKEY	&h0200	For RSA encryption/decryption, use the public key (otherwise the private key)
CRYPF_BIGENDIAN	&h0400	(Applies to type cipher CRYPTO_CIPHER_RSA only.) Use big-endian (openssl) byte order rather than the default little-endian (Microsoft) order
CRYPF_IVHEX	&h0800	IV is hex-encoded, else binary.
Definition File: crypto.def

Hex-Decimal Values

 

cipher  (Num)  [in]

For encryption/decryption, cryptographic algorithm to use.

cipher	value	Description
CRYPTO_CIPHER_NA	0	none / not applicable
CRYPTO_CIPHER_RSA	1	RSA (public/private key)
CRYPTO_CIPHER_AES	2	Advanced Encryption Standard (aka Rjindael) symmetric block cipher
Definition File: crypto.def

 

key  (String or Raw)  [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:

Cipher	Value	Description
CRYPTO_MODE_ECB	1	Electronic CookBook
CRYPTO_MODE_CBC	2	Cipher Block Chaining (block)
CRYPTO_MODE_RFC4716	3
CRYPTO_MODE_CTR	4	Counter Mode (stream)
CRYPTO_MODE_CFB	5	Cipher Feedback (stream)
CRYPTO_MODE_OFB	6	Output Feedback (stream)
CRYPTO_MODE_GCM	7	Galois/Counter Mode (stream)
Definition File: crypto.def

 

padding  (Num)  [in]

For the AES cipher, the padding scheme to use:

Cipher	Value	Description
CRYPTO_PAD_NA	-1	Padding not applicable; use with stream cipher modes CTR, CFB, OFG, GCM.
CRYPTO_PAD_PKCS5	0	Each padding byte equal to the number of padding bytes. If message length an even multiple of the block size, an extra block of padding is added.
CRYPTO_PAD_FIPS81	1	Last byte of padding indicates the number of bytes (including itself). Remaining padding bytes are random.
CRYPTO_PAD_RAND	2	Padding bytes are random. Decrypter must know the length of the message (i.e. the number of padding bytes)
CRYPTO_PAD_NULL	3	Padding bytes set to null. If message length is a multiple of the block size, no padding is used.
CRYPTO_PAD_SPACE	4	Padding bytes set to space. If message length is a multiple of the block size, no padding is used.
CRYPTO_PAD_SPACE	5	Padding bytes set to space. If message length is a multiple of the block size, no padding is used.
CRYPTO_PAD_SPACE	6	Padding bytes set to space. If message length is a multiple of the block size, no padding is used.
CRYPTO_PAD_SPACE	74	Padding bytes set to space. If message length is a multiple of the block size, no padding is used.
Definition File: crypto.def

 

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 Raw)  [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:

•   For RSA encryption/decryption, if the file containing the public and/or private key is password protected, supply the password here, either in plain text or using one of the password encryption modes supported by MX_PWCRYPT (using the default key and seed).

•   For the GCM cipher mode (see Comments), must be a string of hex digits. This is typically used to provide an identifying label or other association for the encrypted text, with the intent of making sure that the decrypted text is not just valid, but valid for a particular context/use. A corresponding authentication tag is generated (by combining the aad with the message and hashing and encrypting it) and output to the authtag parameter. The aad does not have to be kept secret, but both it and the corresponding authtag must be provided to the decryption routine in order to authenticate the result. The aad parameter can be null, but a unique authtag will still be generated and must be passed (along with the null aad) to the decryption).

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.