#### PWD

#### Synopsis

    HELP:   OpenSSL-compatible password-based encryption
    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 encryption based on passwords. This object is a subset of CNV.EDC(). For more information see the corresponding page of the `XCNV` command.

The encryption key is derived from the password and randomly generated salt value. This salt value is prepended to the output for use during decryption. Only OpenSSL-compatible password-based encryption is supported by this object. To use keys, key labels or other advanced encryption options, please use the EDC object.

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 encryption [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 [longest possible]`
  - `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 [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 encryption`