#### PWD

#### Synopsis

    HELP:   OpenSSL-compatible password-based decryption
    TYPE:   OBJECT
    SYNTAX: PWD(ALGO=AES/TDES/CAST5/CAST128/IDEA/BLOWFISH/BF/CAMELLIA,KEYLEN=num/KL064/KL128/KL192/KL256/KL08/KL16/KL24/KL32,MODE=ECB/CBC/OFB/CFB/CTR/GCM,PADDING=NONE/NOPAD/PKCS,KDF/PW2KEY=OLDSSL/PBKDF2,MD/HASH=MD5/SHA1/SHA224/SHA256/SHA384/SHA512/SHA3-224/SHA3-256/SHA3-384/SHA3-512,ITER=num,PASSWORD='str')

#### Description

OpenSSL-compatible decryption based on passwords. This object is a subset of CNV.EDC(). For more information see the corresponding page of the `XCNV` command.

The key for decryption is derived from the password and a salt value that is stored as header in the encrypted file. If no salt is found at the start of the file, decryption is not done (SKPFMT=SUPPREDU). To use keys, key labels or other advanced encryption options, please use the EDC object.

Please be aware that there is no reliable way to determine if the provided password is correct other than by interpreting the decryption output. However, if the file is encrypted in a mode that uses padding (CBC), there is a chance of roughly 99.5% that decryption fails with an incorrect password due to bad padding bytes in the decryption output. Other modes don't use padding and decryption will always complete, but with unreadable output data.

For the above reasons it makes no sense to specify more than one password-based decryption object. You cannot use it to try different passwords.

Below you can find an example for OpenSSL-compatible encryption on mainframe and the corresponding decryption on any platform supported by OpenSSL.

Write a compressed, encrypted and base64-encoded dataset to a remote system:

    //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV=DD:PARM'
    //STEPLIB  DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR
    //SYSOUT   DD SYSOUT=*
    //SYSPRINT DD SYSOUT=*
    //PARM     DD *
       READ.RECORD(
          FILE='HLQ.TEXT.DSN'
          CCSID='1141'
          CHRMODE=SUBSTITUTE
       )
       WRITE.TEXT(
          FILE='ssh://user@server/text.gz.ssl.b64'
          METHOD=UNIX
          SUPTWS
          CCSID='UTF-8'
          COMPRESS.GZIP()
          ENCRYPT.PWD(
             ALGO=AES
             KEYLEN=KL256
             MODE=CBC
             KDF=PBKDF2
             PASSWORD=a'hugo'
          )
          ENCODE.BASE64(
             CHRSET=ASCII
             LINE=76
             DELIM=NL
          )
       )
    /*

The output is written with Unix-style newline characters (NL). Trailing whitespace will be suppressed (SUPTWS) and the character conversion is done from German EBCDIC (IBM-1141) to UTF-8. The resulting text file is compressed with GZIP and encrypted using password-based AES-256-CBC encryption and the PBKDF2 key derivation function. OpenSSL requires line endings for decoding (`openssl enc -d base64`). Therefore, the `LINE` and `DELIM` parameters in the `BASE64` object are needed.

Below is the command line call for decoding it with FLCL:

    :> flcl conv "read.binary(file='text.gz.ssl.b64'
                    decode decrypt.pwd(
                      algo=aes
                      keylen=kl256
                      mode=cbc
                      kdf=pbkdf2
                      pass=a'hugo'))
                  write.binary(file=text.txt)"

The encoding is automatically detected and removed because the header containing the salt value is found. For decryption, the algorithm parameters and the passphrase must be specified. The `DECODE` switch enables automatic GZIP decompression. The result is the text file which was prepared on the mainframe system.

The same can be done with OpenSSL and GZIP standard utilities:

    :> openssl enc -d -base64 -in text.gz.ssl.b64 |
       openssl enc -d -aes-256-cbc -pbkdf2 -pass pass:hugo |
       gzip -d > text.txt

#### Arguments

- `NUMBER: ALGO=AES/TDES/CAST5/CAST128/IDEA/BLOWFISH/BF/CAMELLIA - Algorithm used for decryption [AES]`
  - `AES - Advanced encryption standard (Rijndael)`
  - `TDES - Triple DES (Data encryption standard)`
  - `CAST5 - CAST5/CAST-128 (Carlisle Adams, Stafford Tavares)`
  - `CAST128 - CAST-128/CAST5 (Carlisle Adams, Stafford Tavares)`
  - `IDEA - International Data Encryption Algorithm`
  - `BLOWFISH - Blowfish from Bruce Schneier`
  - `BF - Blowfish from Bruce Schneier`
  - `CAMELLIA - Camellia from Japan (Mitsubishi Electric and NTT)`
- `NUMBER: KEYLEN=num/KL064/KL128/KL192/KL256/KL08/KL16/KL24/KL32 - Key length if passphrase used`
  - `KL064 - Key length 64 bits (8 bytes)`
  - `KL128 - Key length 128 bits (16 bytes)`
  - `KL192 - Key length 192 bits (24 bytes)`
  - `KL256 - Key length 256 bits (32 bytes)`
  - `KL08 - Key length 8 bytes (64 bits)`
  - `KL16 - Key length 16 bytes (128 bits)`
  - `KL24 - Key length 24 bytes (192 bits)`
  - `KL32 - Key length 32 bytes (256 bits)`
- `NUMBER: MODE=ECB/CBC/OFB/CFB/CTR/GCM - Mode of operation [if TAG then GCM else CBC]`
  - `ECB - Electronic codebook mode`
  - `CBC - Cipher block chaining mode`
  - `OFB - Output feedback mode`
  - `CFB - Cipher feedback mode`
  - `CTR - Counter mode`
  - `GCM - Galois/Counter Mode`
- `NUMBER: PADDING=NONE/NOPAD/PKCS - Padding for CBC or ECB mode [PKCS]`
  - `NONE - No padding (remaining data must have a multiple of the block length)`
  - `NOPAD - No padding (remaining data must have a multiple of the block length)`
  - `PKCS - OpenSSL conform PKCS padding`
- `NUMBER: KDF/PW2KEY=OLDSSL/PBKDF2 - Password to key derivation function [OLDSSL]`
  - `OLDSSL - Legacy OpenSSL key derivation (avoid use, default: SHA-256 with 1 round, hint: OpenSSL < 1.1.0 used MD5)`
  - `PBKDF2 - PBKDF2 key derivation function (default: SHA-256 with 10000 rounds, available from OpenSSL 1.1.1)`
- `NUMBER: MD/HASH=MD5/SHA1/SHA224/SHA256/SHA384/SHA512/SHA3-224/SHA3-256/SHA3-384/SHA3-512 - Hash algorithm for key derivation [SHA256]`
  - `MD5 - Message Digest 5 with 128 bits`
  - `SHA1 - Secure Hash Algorithm 1 with 160 bits`
  - `SHA224 - Secure Hash Algorithm 2 with 224 bits`
  - `SHA256 - Secure Hash Algorithm 2 with 256 bits`
  - `SHA384 - Secure Hash Algorithm 2 with 384 bits`
  - `SHA512 - Secure Hash Algorithm 2 with 512 bits`
  - `SHA3-224 - Secure Hash algorithm 3 with 224 bits`
  - `SHA3-256 - Secure Hash Algorithm 3 with 256 bits`
  - `SHA3-384 - Secure Hash Algorithm 3 with 384 bits`
  - `SHA3-512 - Secure Hash Algorithm 3 with 512 bits`
- `NUMBER: ITER=num - Iteration count for PBKDF2, implies METHOD=PBKDF2 if specified [10000]`
- `STRING: PASSWORD='str' - Salted passphrase for decryption`