Operating System - OpenVMS
1748058 Members
4880 Online
108758 Solutions
New Discussion юеВ

Re: Documentation for ENCRYPT

 
John McL
Trusted Contributor

Documentation for ENCRYPT

We're investigating using AES encryption to pass certain data out via a webserver (e.g. in a clickable URL) and decrypt when it comes back. I've hit a problem when experimenting with the ENCRYPT routines - poor documentation and no examples.

The Utility Routines Manual (v8.3, 2006) says little about the encrypted and decrypted data length - supposedly the descriptors are dynamically adjusted but mine in C aren't. It has no examples and says that ENCRYPT$ENCRYPT can be used for decryption. It also says under every listing of "Condition Values Returned" the useful(!) message "ENCRYPT$xyz - An error reported by the Encryption Software. The xyz portion identifies the message." but doesn't tell you where to find the further information.

I eventually found the document "Encryption for OpenVMS" dated 2001 (any changes since then?) and while it also has the ENCRYPT$xyz message at least it says to find the details in its appendix. Alas no examples, no discussion of data length and the same comment about ENCRYPT$ENCRYPT also decrypting.

I'd appreciate any pointers to some decent documentation and/or examples. Any warnings or gotcha's would also be helpful.
6 REPLIES 6
Hoff
Honored Contributor

Re: Documentation for ENCRYPT

How about some source code?

In particular, are the string descriptors created here being created and managed as dynamic descriptors?

(Apologies on what may be an obvious question and something you've already looked at, but it's been my experience that this whole area can be very confusing to C programmers working on OpenVMS.)
Hoff
Honored Contributor

Re: Documentation for ENCRYPT

And if you're not familiar with this descriptor stuff, see the routine:

RmsShowDate()

in...

http://h71000.www7.hp.com/wizard/wiz_2821.html

...this for C code which sets up a descriptor and then allocations storage for it via lib$sget1_dd().

The OpenVMS FAQ also has some details on this (first URL), and then the (second) article touches (very!) briefly on this topic.

http://labs.hoffmanlabs.com/node/1
http://labs.hoffmanlabs.com/node/273

And if you're already familiar with descriptors, please ignore the above.
John McL
Trusted Contributor

Re: Documentation for ENCRYPT

In answer to your question I use static descriptors and the code is attached. (NB. a company-specific header file has been removed but using the standard header stuff should be all that's required.)

I've pressed on with my work because I can't be sure if responses will appear quickly or not.

Now I'm using ENCRYPT$ENCRYPT and ENCRYPT$DECRYPT to try to get the data lengths. The first matches the input string (89 bytes) but the DECRYPT comes back with 128 bytes. I expected maybe 96 as multiple of 16.
John McL
Trusted Contributor

Re: Documentation for ENCRYPT

Update - might save someone else some work...

If I explicitly modify the C descriptor for the encrypted text to use the returned 'output_length' value from the ENCRYPT$ENCRYPT function the correct text size is produced by the ENCRYPT$DECRYPT function. (This is probably linked to the encryption form that I'm using but I've not tested that yet.)
Ian Miller.
Honored Contributor

Re: Documentation for ENCRYPT

The routine expects the descriptor to contain the real length of the string and as you are3 using a static descriptor then you have to update the descriptor yourself - no surprise there.

You may find a dynamic string descriptor a simpler solution.

____________________
Purely Personal Opinion
John McL
Trusted Contributor

Re: Documentation for ENCRYPT

I switched over to the OpenSLL EVP routines. While there was an example (SSL$EXAMPLES:SSL$AES.C) but no good documentation, at least I could find some on the web.

I have to say that the documentation for ENCRYPT is some of the worst I have seen from OpenVMS people in a long time. It needs separate sections for DES and AES encryption, some coding examples, better descriptions of errors and decent proof reading (e.g. last paragraph before description of P1 for ENCRYPT$ENCRYPT).

P.S. Ian M mentioned static descriptors requiring manual adjustment to length. I had already tried dynamic descriptors and that failed. According to the documentation ny of descriptor of type DCS$K_DTYPE_T should work and that's what C uses, so maybe this failure to adjust the length field in the descriptor is something else that needs investigation.