Public/Private Key
Module Implementation: OpenSSLCryptoInterfacePKEY
This module implements various public/private key algorithms such as asymmetric encrypt/decrypt, key agreement, digital signatures and enveloping.
Note: Internal classes are italicized and will only contain a short description.
See the class-side examples in the OpenSSLPublicPrivateKeyExamples class for additional usage detail.
PKey
OpenSSLEnvelopeCtx: Internal state object used during open/seal digital enveloping.
OSSslDH: OSSslDHKey internal pkey struct accessor.
OSSslDSA: OSSslDSAKey internal pkey struct accessor.
OSSslRSA: OSSslRSAKey internal pkey struct accessor.
OSSslEC: OSSslECKey internal pkey struct accessor.
OSSslECBuiltinCurve: OpenSSL preconstructed curves
OSSslECGroup: Eliptic Curve group definition
OSSslECMethod: Eliptic Curve Methods supported by OpenSSL
OSSslECMethod: Point on an Eliptic Curve
OSSslPKey
Abstract superclass of all Asymmetric public key algorithms. It contains most of the functionality relating to public/private key storage and conversion.
Class methods: Creation
createNewFromBytes: aStringOrByteArray
Read the Private/Public key from a DER or PEM encoded data.
Arguments:
aStringOrByteArray - data in <String> or <ByteArray> form
Answers:
<OSSslPKey subclass> - Pkey instance
<OpenSSLError compatible error> - error object
createNewFromBytes: aStringOrByteArray password: aPassword
Read the Private/Public key from a DER or PEM encoded data. If the data is password protected, then aPassword will be a String.If not password is required, then aPassword will be nil.
Arguments:
aStringOrByteArray - data in <String> or <ByteArray> form
aPassword - Optional password <String>. Could be nil for no passwd.
Answers:
<OSSslPKey subclass> - Pkey instance
<OpenSSLError compatible error> - error object
createNewFromFile: aFilename
Read the Private/Public key from a DER or PEM encoded file with full path name aFilename.
Arguments:
aFilename - full path name to file
Answers:
<OSSslPKey subclass> - Pkey instance
<OpenSSLError compatible error> - error object
createNewFromFile: aFilename password: aPassword
Read the Private/Public key from a DER or PEM encoded file with full path name aFilename. If the data is password protected, then aPassword will be a String. If not password is required, then aPassword will be nil.
Arguments:
aFilename - full path name to file
aPassword - Optional password <String>. Could be nil for no passwd.
Answers:
<OSSslPKey subclass> - Pkey instance
<OpenSSLError compatible error> - error object
Instance methods: Accessing
size
Answers the maximum size of a signature in bytes.
Answers:
<Integer>
Instance methods: API - Digital Signatures
sign: aByteObject with: anOSSslDigest
Answers a digital signature for aByteObject using the digest anOSSslDigest and this pkey
Note: The Pkey algorithm must support digital signatures. If not, an error object is answered.
Arguments:
aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)
anOSSslDigest - <OSSslDigest> message digest algorithm
Answers:
<ByteArray> digital signature
verify: signature from: aByteObject with: anOSSslDigest
Answers a <Boolean> indicating if the digital signature for aByteObject using the digest anOSSslDigest and this pkey is verified
Note: The Pkey algorithm must support digital signatures. If not, an error object is answered.
Arguments:
aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)
anOSSslDigest - <OSSslDigest> message digest algorithm
Answers:
<Boolean> true if the digital signature is verified
Instance methods: Conversion
asDER
Answer this PKey encoded in DER format as a <ByteArray>.
Answers:
<ByteArray>
asPEM
Answer this PKey encoded in PEM format as a <String>.
Answers:
< String>
asPublicDER
DER-encode just the public portion of this key.
Answers:
<ByteArray>
asPublicKey
Answer a new managed instance of just the public key portion of this pkey.
Answers:
< OSSslPkey> public key
asPublicPEM
Export just the public portion of this key to PEM format.
Answers:
< String>
Instance methods: Key Generation
generateKey
Generates new random keys using existing key parameters.
Answers:
< OSSslPKey subclass>
generateKey:aKeyParameter
Generates new keys for the PKey using the @aKeyParameter.
Arguments:
aKeyParameter - @see the concrete PKey's class>>generateKey:for: for a description of what @aKeyParameter is
Answers:
< OSSslPKey subclass> self
Instance methods: Printing
printDEROn: aStreamOrBIO
Write the PKey in DER format to aStreamOrBIO. This allows Smalltalk stream to be used as well.
Arguments:
aStreamOrBIO - <WriteStream or compatible | OSSslBIO>
Answers:
<WriteStream or compatible | OSSslBIO>
printPEMOn: aStreamOrBIO
Write the PKey in PEM format to aStreamOrBIO. This allows Smalltalk stream to be used as well.
Arguments:
aStreamOrBIO - <WriteStream or compatible | OSSslBIO>
Answers:
<WriteStream or compatible | OSSslBIO>
printPEMOn: aStreamOrBIO cipher: aCipher password: aPassword
Write the PKey in PEM format to aStreamOrBIO using the supplied aCipher and aPassword. If only one of the chipher or password is supplied...they both will be ignored. The caller must supply a cipher AND password or neither. This allows Smalltalk stream to be used as well.
Arguments:
aStreamOrBIO - <WriteStream or compatible | OSSslBIO>
aCipher - <OSSslCipher> or nil
aPassword - <String> or nil.
Answers:
<WriteStream or compatible | OSSslBIO>
printPublicDEROn: aStreamOrBIO
Write the Public key version of the PKey in DER format to aStreamOrBIO. This allows Smalltalk stream to be used as well.
Arguments:
aStreamOrBIO - <WriteStream or compatible | OSSslBIO>
Answers:
<WriteStream or compatible | OSSslBIO>
printPublicPEMOn: aStreamOrBIO
Write the Public key version of the PKey in PEM format to aStreamOrBIO. This allows Smalltalk stream to be used as well.
Arguments:
aStreamOrBIO - <WriteStream or compatible | OSSslBIO>
Answers:
<WriteStream or compatible | OSSslBIO>
Instance methods: Testing
isPrivateKey
Answer true if this is a private key.
Answers:
<Boolean>
isPublicKey
Answer true if this HAS a public key.
Answers:
< Boolean>
supportsDigitalSignatures
Answer true if this PKey algorithm supports digital signatures.
Answers:
<Boolean>
supportsKeyTransport
Answer true if this PKey algorithm supports key transport (i.e. digital envelopes.)
Answers:
< Boolean>
supportsProbabilisticSignatureScheme
Answers true if this PKey algorithm supports PSS
Answers:
< Boolean>
OSSslDHKey
Implements the Diffie-Hellman key agreement protocol.
Class methods: Creation
createNew: bitsOrBitsAndGenerator
Create a new instance of the DH Key. This is done by generating the DH key using the arguments provided. The argument bitsOrBitsAndGenerator can be:
1. An <Association> with the key <Integer> length in BITS (safe prime to be generated) and a value <Integer> generator which is a small number > 1, typically 2 or 5.
2. An <Integer> to just define the bits...this is shorthand for a nil exponent described above.
Arguments:
bitsOrBitsAndGenerator - <Association> described above
Answers:
< OSSslDHKey> - DH key
Instance methods: Accessing
g
Answer the public g generator value as an <OSSslBigNumber>. This is a member of the Diffie-Hellman parameters.
Answers:
< OSSslBigNumber>
p
Answer the public p prime value as an <OSSslBigNumber>. This is a member of the Diffie-Hellman parameters
Answers:
< OSSslBigNumber>
publicValue
Answer the public key value of this DH key as an <OSSslBigNumber>. If no public key value is set, it will be generated first.
Answers:
< OSSslBigNumber>
Instance methods: API - Key Agreement
computeKey: publicValue
Computes and answers the shared secret from the private DH value and the other party's public value and stores it in shared secret.
Arguments:
publicValue - <Integer | OSSslBigNumber | OSSslAsn1Integer>
Answers:
<ByteArray> shared secret
generateKey
Performs the first step of a Diffie-Hellman key exchange by generating private and public DH values. By calling self>>computeKey, these are combined with the other party's public value to compute the shared key.
Answers:
< OSSslDHKey> - self
<OpenSSLError> - error object
publicValue
Answer the public key value of this DH key as an <OSSslBigNumber>. If no public key value is set, it will be generated first.
Answers:
< OSSslBigNumber>
Instance methods: Conversion
asPublicKey
Answer a new managed instance of just the DH public key.
Answers:
< OSSslDHKey> DH public key
Instance methods: Testing
isPrivateKey
Answer true if this is a private key.
Answers:
<Boolean>
isPublicKey
Answer true if this HAS a public key.
Answers:
< Boolean>
supportsDigitalSignatures
Diffie-Hellman is a key-agreement protocol.
It does not support digital signatures
Answers:
<Boolean> - false
supportsKeyTransport
Diffie-Hellman does not support key transport.
Answers:
< Boolean> - false
supportsProbabilisticSignatureScheme
Diffie-Hellman does not support PSS
Answers:
< Boolean> - false
Instance methods: Validation
check
Validates Diffie-Hellman parameters. Check that p is a safe prime, and that g is a suitable generator. In the case of an error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or DH_NOT_SUITABLE_GENERATOR are set in *codes. DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be checked, i.e. it does not equal 2 or 5.
Answers:
<Boolean> true if dh params pass validation
checkWithErrorCode
Validates Diffie-Hellman parameters. Check that p is a safe prime, and that g is a suitable generator. In the case of an error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or DH_NOT_SUITABLE_GENERATOR are set in *codes. DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be checked, i.e. it does not equal 2 or 5.
Answers:
<True> true if dh params are validated
<OpenSSLError> if the check failed with the reason placed in the OpenSSLError>>errorCode
OSSslDSAKey
Digital Signature Algorithm.
Class methods: Creation
createNew: bitsOrBitsAnd20ByteSeed
Create a new instance of the DSA Key. This is done by generating the DSA key using the arguments provided. The argument bitsOrBitsAndGenerator can be:
1. An <Association> with the key <Integer> length in BITS and a value <ByteArray> the seed WHICH MUST BE 20 BYTES TO BE VALID.
2. An <Integer> to just define the bits...this is shorthand for a nil exponent described above.
Arguments:
bitsOrBitsAnd20ByteSeed- <Association> described above
Answers:
< OSSslDSAKey> - DSA key
Instance methods: Conversion
asPublicKey
Answer a new managed instance of just the DSA public key
Answers:
< OSSslDSAKey> DSA public key
Instance methods: Testing
isPrivateKey
Answer true if this is a private key
Answers:
<Boolean>
isPublicKey
Answer true if this HAS a public key
Answers:
< Boolean>
supportsDigitalSignatures
Digital Signatures are supported by DSA.
Answers:
<Boolean> - true
supportsKeyTransport
DSA does not support key transport.
Answers:
< Boolean> - false
supportsProbabilisticSignatureScheme
DSA does not support PSS
Answers:
< Boolean> - false
OSSslECKey
Implements Elliptic Curve based cryptography algorithms
Class methods: Creation
createNew: aCurveOrGroup
Create a new instance of the EC Key Pair. The argument aCurveOrGroup can be:
1. An <OSSslECGroup> - EC Group Object
2. An <OSSslECBuiltinCurve> - EC Curve Object
Arguments:
aCurveOrGroup - described above
Answers:
< OSSslECKey> - EC key pair
Instance methods: Accessing
a
Answer the 'a' coefficient component of the elliptic curve.
Answers:
< OSSslBigNumber>
b
Answer the b coefficient component of the elliptic curve.
Answers:
< OSSslBigNumber>
group
Answers the EC_GROUP associated with this EC_KEY.
Answers:
< OSSslECGroup>
method
Answers the EC_METHOD implementation associated with the group of this PKey.
Answers:
< OSSslECMethod> - method associated with the group of this key
p
Answer the p prime component of the elliptic curve.
Answers:
< OSSslBigNumber>
publicValue
Answer the Public Value of the EC_KEY, which is an EC_POINT.
Answers:
< OSSslECPoint> - public value
Instance methods: API - Key Agreement
computeKey: publicValue
Computes and answers the shared secret from the private ECDH value and the other party's public value and stores it in shared secret.
Arguments:
publicValue - <OSSslECPoint>
Answers:
<ByteArray> shared secret
Instance methods: Conversion
asPublicKey
Answer the Public Key of the EC_KEY as an PKEY.
Answers:
< OSSslECKey> public key
Instance methods: Testing
isPrivateKey
Answer true if the pkey has a private key.
Answers:
<Boolean>
isPublicKey
Answer true if the key Is a public key.
Answers:
< Boolean>
supportsDigitalSignatures
Digital Signatures are supported by Elliptic Curve
Answers:
<Boolean> - true
supportsKeyTransport
EC does not support key transport in OpenSSL
Answers:
< Boolean> - false
supportsProbabilisticSignatureScheme
EC does not support PSS
Answers:
< Boolean> - false
Instance methods: Validation
check
Validates private EC Keys. It performs various sanity checks on the EC_KEY object to confirm that it is valid.
Answers:
<Boolean> true if validation passes, false otherwise
OSSslRSAKey
Implements the RSA algorithm. It can be used for secure symmetric key exchange as well as for digital signatures.
Class methods: Creation
createNew: bitsOrBitsAndExponent
Create a new instance of the RSA Key Pair. This is done by generating the RSA key using the arguments provided. The argument bitsOrBitsAndExponent can be:
1. An <Association> with the key <Integer> length in BITS and a value <Integer> the public exponent. If the exonent is nil, then the constant value OpenSSLCryptoConstants::RSA_F4 (6537) will be used.
2. An <Integer> to just define the bits...this is shorthand for a nil exponent described above. Arguments:
bitsOrBitsAndExponent - <Association> described above
Answers:
< OSSslRSAKey> - RSA key
Instance methods: API - Digital Signatures
signPss: aByteObject with: anOSSslDigest saltLength: aLength mgf1Digest: anOSSslMgf1Digest
Answers a digital signature for @aByteObject using the
Probabilistic Signature Scheme (RSA-PSS) with MGF1 mask gen function.
Note: The RSA Pkey must have a private key
If not, an error object is answered
Arguments:
aByteObject - @see implementors of isOpenSSLByteObject for types
anOSSslDigest - <OSSslDigest> message digest algorithm
aLength - <Integer> in octects of the salt
anOSSslMgf1Digest- <OSSslDigest> hash algorithm used in MGF1
Answers:
<ByteArray> digital signature of @aByteObject
verifyPss: signature from: aByteObject with: anOSSslDigest with: aLength saltLength: aLength mgf1Digest: anOSSslMgf1Digest
Answers a <Boolean> indicating if the digital signature for @aByteObject using the Probabilistic Signature Scheme (RSA-PSS) with MGF1 mask gen function is verified
Note: The RSA Pkey must have a private key. If not, an error object is answered.
Arguments:
Signature - @see implementors of isOpenSSLByteObject for types
aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)
anOSSslDigest - <OSSslDigest> message digest algorithm
aLength - <Integer> in octects of the salt
anOSSslMgf1Digest - <OSSslDigest> hash algorithm used in MGF1
Answers:
<Boolean> true if the digital signature is verified
Instance methods: Conversion
asPublicKey
Answer a new managed instance of just the public key from this key pair.
Answers:
< OSSslRSAKey > RSA public key
Instance methods: Testing
isPrivateKey
Answer true if this is a private key
Answers:
<Boolean>
isPublicKey
RSA always has a public key.
Answers:
< True>
supportsDigitalSignatures
RSA supports digital signatures.
Answers:
<Boolean> - true
supportsKeyTransport
RSA supports key transport.
Answers:
< Boolean> - true
supportsProbabilisticSignatureScheme
RSA supports PSS (RSA-PSS) in OpenSSL
Answers:
< Boolean> - true
Instance methods: Validation
check
Validates private RSA Keys.
It does not work on RSA public keys that have only the modulus and public exponent elements populated. Checks that p and q are in fact prime, and that n = p*q. Checks that d*e = 1 mod (p-1*q-1), and that dmp1, dmq1 and iqmp are set correctly or are NULL. Performs integrity checks on all the RSA key material, so the RSA key structure must contain all the private key data too. Therefore, it cannot be used with any arbitrary RSA key object, even if it is otherwise fit for regular RSA operation.
Answers:
<Boolean> true if public key or validated private key.
OpenSSLEnvelope
Object representation of a digital envelope.
Instance methods: Accessing
data
Depending on the context (seal or open), this answers the (encrypted or decrypted) data.
Answers:
<ByteArray | String | OSStringZ> - byte collection that knows its size
data: aByteObject
Depending on the context (seal or open), this sets the (encrypted or decrypted) data.
Answers:
aByteObject - <ByteArray | String | OSStringZ> - byte collection that knows its size
iv
Answer the initialization vector <ByteArray>.
Answers:
< ByteArray >
iv: aByteArray
Sets the initialization vector <ByteArray>.
Arguments:
aByteArray - <ByteArray> initialization vector
sessionKey
Answer the encrypted session key which was encrypted using a public key. The owning of the associated private key is the only one that can decrypt the session key.
Answers:
<ByteArray>
sessionKey: anEncryptedByteArray
Sets the encrypted session key which was encrypted using a public key. The owning of the associated private key is the only one that can decrypt the session key.
Arguments:
anEncryptedByteArray - <ByteArray>
Instance methods: API
discard
After opening an envelope, the caller should try and remember to discard it which cleanses the memory. If not, the GC will take care of it but its a good policy to leave sensitive information in memory only as long as needed. It is expected that the envelopes of multiple clients are not in the same memory space. When creating n number of envelopes, the encrypted data and iv point to the same object. The session key is unique per envelope. Therefore, you should not call it under these conditions because doing so will cleanse the data for all envelopes in the image.
Extensions
OSSslCipher
open: anEnvelope with: anOSSslPKey
Open anEnvelope <OpenSSLEnvelope> using the private key anOSSslPKey that was associated with the envelope when it was sealed.
Arguments:
anEnvelope - <OpenSSLEnvelope> sealed envelope
anOSSslPKey - <OSSslPKey> private key
Answers:
<ByteArray> - decrypted contents
seal: aByteObject withAll: aCollectionOfOSSslPKeys
Create envelopes (1 for each public key in aCollectionOfOSSslPKeys) and seal the envelopes <OpenSSLEnvelope> using the public keys.
Arguments:
aByteObject - a collection of bytes to encrypt THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)
aCollectionOfOSSslPKeys - <SequenceableCollection of <OSSslPKey>> public keys
Answers:
<Array of <OpenSSLEnvelope>> - collection of envelopes associated with the public keys in the same order defined in aCollectionOfOSSslPKeys
OSSslCipherCtx
open: anEnvelope with: anOSSslPKey
Open anEnvelope <OpenSSLEnvelope> using the private key anOSSslPKey that was associated with the envelope when it was sealed.
Arguments:
anEnvelope - <OpenSSLEnvelope> sealed envelope
anOSSslPKey - <OSSslPKey> private key
Answers:
<ByteArray> - decrypted contents
seal: aByteObject withAll: aCollectionOfOSSslPKeys
Create envelopes (1 for each public key in aCollectionOfOSSslPKeys) and seal the envelopes <OpenSSLEnvelope> using the public keys.
Arguments:
aByteObject - a collection of bytes to encrypt THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)
aCollectionOfOSSslPKeys - <SequenceableCollection of <OSSslPKey>> public keys
Answers:
<Array of <OpenSSLEnvelope>> - collection of envelopes associated with the public keys in the same order defined in aCollectionOfOSSslPKeys