Rsa class¶

class cryptosyspki.Rsa¶

RSA encryption and key management.

class AdvOpts¶

Advanced options.

DEFAULT = 0¶: Default

MGF1_SHA1 = 8388608¶

Force the MGF hash function to be SHA-1 (default = same as encoding set by Rsa.HashAlg)

Type:: RSA-OAEP only

class EME¶

Encoding method for encryption.

OAEP = 16¶: EME-OAEP encoding method

PKCSV1_5 = 0¶: EME-PKCS1-v1_5 encoding method (default)

class Format¶

Format for saved RSA key.

BINARY = 0¶: Binary DER-encoded (default)

DEFAULT = 0¶: Default

PEM = 65536¶: PEM-encoded

SSL = 131072¶: PEM-encoded compatible with OpenSSL

class HashAlg¶

Hash algorithm for RSA signatures.

MD5(as per RFC 1321) = 1¶: MD5 (as per RFC 1321)

SHA1 = 0¶: SHA-1 (default)

SHA224 = 6¶: SHA-224

SHA256 = 3¶: SHA-256

SHA384 = 4¶: SHA-384

SHA512 = 5¶: SHA-512

class PbeScheme¶

Password-based encryption scheme to encrypt the private key file.

DEFAULT = 0¶: pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12

PBKDF2_AES128 = 4128¶: PBKDF2 using aes128-CBC

PBKDF2_AES192 = 4144¶: PBKDF2 using aes192-CBC

PBKDF2_AES256 = 4160¶: PBKDF2 using aes256-CBC

PBKDF2_DESEDE3 = 4112¶: PBKDF2 using des-EDE3-CBC

class PublicExponent¶

Choice for public exponent (e).

RSAEXP_EQ_17 = 2¶: Set exponent equal to 17 (F2)

RSAEXP_EQ_257 = 3¶: Set exponent equal to 257 (F3)

RSAEXP_EQ_3 = 0¶: Set exponent equal to 3 (F0)

RSAEXP_EQ_5 = 1¶: Set exponent equal to 5 (F1)

RSAEXP_EQ_65537 = 4¶: Set exponent equal to 65537 (F4)

class XmlOptions¶

Bitwise flags when converting between RSA key and XML.

EXCLPRIVATE = 16¶: Exclude private key even if present

HEXBINARY = 256¶: Create XML using non-standard hexadecimal encoding (to_xml only)

REQPRIVATE = 32¶: Require the private key to exist in the XML input or fail (from_xml only)

RSAKEYVALUE = 1¶: Create in .NET-compatible RSAKeyValue format (to_xml only)

static decode_digest_for_signature(data, full_digestinfo=False)¶

Extract digest (or digestinfo) from an EMSA-PKCS1-v1_5-encoded block.

Parameters:

data (bytes) -- Encoded message for signature.
full_digestinfo (bool) -- If True, extract the full DigestInfo; otherwise just extract the message digest itself.

Returns:

Decoded data.

Return type:

bytes

static decode_msg_for_encryption(data, method=0)¶

Extract message from a PKCS#1 EME-encoded block.

Parameters:

data (bytes) -- Encoded block.
method (Rsa.EME) -- Encoding method used [default = EME.PKCSV1_5].

Returns:

Decoded message.

Return type:

bytes

static decrypt(data, prikeyfileorstring, password='', method=0, hashalg=0, advopts=0)¶

Decrypt a message encrypted using RSA encryption.

Parameters:

data (bytes) -- Data to be decrypted (must be exactly the same length as the key modulus size).
prikeyfileorstring (str) -- Name of the private key file, or a string containing the key in PEM format, or a valid internal private key string.
password (str) -- Password for encrypted private key, or "" if password is not required.
method (Rsa.EME) -- Encoding method used [default = EME.PKCSV1_5].
hashalg (Rsa.HashAlg) -- Hash function for EME-OAEP encoding, otherwise ignored.
advopts (Rsa.AdvOpts) -- Advanced options for EME-OAEP only.

Returns:

Decrypted data.

Return type:

bytes

static encode_msg_for_encryption(keybytes, message, method=0)¶

Create an encoded message for encryption (EME).

Parameters:

keybytes (int) -- Number of bytes in the key.
message (bytes) -- Message to be encoded.
method (Rsa.EME) -- Encoding method to use [default = EME.PKCSV1_5].

Returns:

Encoded block.

Return type:

bytes

static encode_msg_for_signature(keybytes, message, hashalg=0, digest_only=False)¶

Create an encoded message for signature (EMSA-PKCS1-v1_5 only).

Parameters:

keybytes (int) -- Number of bytes in the key
message (bytes) -- Message to be encoded (or digest value if digest_only=True)
hashalg (Rsa.HashAlg) -- Message digest algorithm to use [default = SHA-1]
digest_only (bool) -- Set True to pass the message digest value instead of the message itself.

Returns:

Encoded block.

Return type:

bytes

static encrypt(data, pubkeyfileorstring, method=0, hashalg=0, advopts=0, params='')¶

Encrypt a short message using RSA encryption.

Parameters:

data (bytes) -- Data to be encrypted (must be at least 11 bytes shorter than the key modulus size).
pubkeyfileorstring (str) -- Name of the public key file or X.509 certificate, or a string containing the key or certificate in PEM format, or a valid internal public key string.
method (Rsa.EME) -- Encoding method to use [default = EME.PKCSV1_5].
hashalg (Rsa.HashAlg) -- Hash function for EME-OAEP encoding, otherwise ignored.
advopts (Rsa.AdvOpts) -- Advanced options for EME-OAEP only.
params (str) -- For specialist use.

Returns:

Encrypted data.

Return type:

bytes

static from_xmlstring(xmlstr, opts=0)¶

Return an RSA key string in internal format from an XML string.

Creates an internal private key string if the XML contains private key parameters, otherwise an internal public key string.

Parameters:

xmlstr (str) -- The XML string to use to reconstruct the RSA key.
opts (XmlOptions) -- Option flags.

Returns:

Key string in internal format or empty string on error.

Return type:

str

static get_privatekey_from_pfx(outputfile, pfxfile)¶

Extract an encrypted private key from a PKCS-12 PKCS8ShroudedKeyBag, saving the output directly as a new file.

The first pkcs-12-pkcs-8ShroudedKeyBag found in the PFX file will be extracted and saved directly as a BER-encoded EncryptedPrivateKeyInfo file. No decryption or other conversion is carried out.

Parameters:

outputfile (str) -- Name of file to create.
pfxfile (str) -- Name of PFX (.p12) file.

Returns:

If successful, it returns the number of bytes written to the output file.

Return type:

int

static key_bits(keystr)¶

Return number of significant bits in RSA key modulus.

Parameters:: keystr (str) -- Internal key string (private or public).
Returns:: Number of significant bits in key.
Return type:: int

static key_bytes(keystr)¶

Return number of bytes (octets) in RSA key modulus.

Parameters:: keystr (str) -- Internal key string (private or public).
Returns:: Number of bytes in key.
Return type:: int

static key_hashcode(keystr)¶

Compute the hash code of an "internal" RSA public or private key string.

Should be the same for a matching private and public key.

Parameters:: keystr (str) -- Internal key string.
Returns:: A 32-bit hash code for the key encoded in hex.
Return type:: str

static key_isprivate(keystr)¶

Determine if keystring is a private key.

Parameters:: keystr (str) -- Internal key string.
Returns:: True if the key string contains a valid RSA private key, or False if a valid RSA public key.
Return type:: bool
Raises:: PKIError -- If keystring is invalid.

static key_match(prikeystr, pubkeystr)¶

Determine if a pair of "internal" RSA private and public key strings are matched.

Parameters:

prikeystr (str) -- Internal RSA private key string
pubkeystr (str) -- Internal RSA public key string

Returns:

True if the keystrings are valid and matched, or False if the keystrings are valid but not matched.

Return type:

bool

Raises:

PKIError -- If a key string is invalid.

static key_value(keystr, fieldname)¶

Extract a base64-encoded RSA key value from internal key string.

The output is a continuous string of base64 characters suitable for a <RSAKeyValue> node in an XML-DSIG document.

Parameters:

keystr (str) -- Public or private key in internal string format
fieldname (str) -- Name of field to be extracted: "Modulus" or "Exponent"

Returns:

Value encoded in base64 or an empty string on error

Return type:

str

static make_keys(pubkeyfile, prikeyfile, nbits, exponent, password, pbes=0, params='', fileformat=0)¶

Generate a new RSA public/private key pair.

Parameters:

pubkeyfile (str) -- Output filename for public key
prikeyfile (str) -- Output filename for (encrypted) private key
nbits (int) -- Required key modulus size in bits (min 96)
exponent (PublicExponent) -- Exponent (Fermat Prime)
password (str) -- Password string for encrypted private key
pbes (Rsa.PbeScheme) -- Encryption scheme to encrypt private key.
params (str) --
Optional parameters. A set of attribute "name=value" pairs separated by a semicolon (;) .
count=<integer>
To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048].

prf=<hmac-name>
To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;". Valid values are (case-insensitive):
hmacwithSHA1 (default)

hmacwithSHA224

hmacwithSHA256

hmacwithSHA384

hmacwithSHA512
rngseed=<string>
To add some user-supplied entropy for the key generation process, e.g. "rngseed=NaCl;".
fileformat (Rsa.Format) -- Format to save file [default = DER binary]

Returns:

Zero if successful.

Return type:

int

static publickey_from_private(intkeystr)¶

Return an internal RSA public key string from an internal RSA private key string.

Parameters:: intkeystr (str) -- Private key in "internal" format
Returns:: Internal representation of the public key.
Return type:: str

static raw_private(block, prikeystr)¶

Return RSA transformation of block using private key.

Parameters:

block (bytes) -- Data (must be same byte length as key modulus).
prikeystr (str) -- Private key in internal string format.

Returns:

Transformed data.

Return type:

bytes

static raw_public(block, pubkeystr)¶

Return RSA transformation of block using public key.

Parameters:

block (bytes) -- Data (must be same byte length as key modulus).
pubkeystr (str) -- Public key in internal string format.

Returns:

Transformed data.

Return type:

bytes

static read_private_key(keyfileorstr, password='')¶

Return an internal private key string from a file or string containing an RSA private key.

Parameters:

keyfileorstr (str) -- Either the name of file containing the private key or a string containing the key in PEM format or XML format.
password (str) -- password for key file, if encrypted.

Returns:

Private key string in internal format.

Return type:

str

static read_public_key(keyfileorstr)¶

Return an internal public key string from a file or string containing an RSA public key.

Parameters:: keyfileorstr (str) -- Either the name of file containing the public key or a string containing the key in PEM format or XML format.
Returns:: Public key string in internal format.
Return type:: str

static save_enc_key(outputfile, intkeystr, password, pbescheme=0, params='', fileformat=0)¶

Save an internal RSA private key string to an encrypted private key file.

Parameters:

outputfile (str) -- Name of file to create
intkeystr (str) -- Private key in internal format
password (str) -- Password to encrypt key file.
pbescheme (Rsa.PbeScheme) -- Encryption scheme to encrypt private key.
params (str) --
Optional parameters. A set of attribute "name=value" pairs separated by a semicolon (;) .
count=<integer>
To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048].

prf=<hmac-name>
To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;". Valid values are (case-insensitive):
hmacwithSHA1 (default)

hmacwithSHA224

hmacwithSHA256

hmacwithSHA384

hmacwithSHA512
fileformat (Rsa.Format) -- File format [default = DER-encoded binary file]

Returns:

Zero if successful.

Return type:

int

Note

The named argument count has been removed as of [v22.0] - use "count=nnn;" in params instead.

static save_key(outputfile, keystr, fileformat=0)¶

Save an internal RSA key string (public or private) to an unencrypted key file.

Parameters:

outputfile (str) -- Name of file to create
keystr (str) -- Key string (public or private) in internal format
fileformat (Rsa.Format) -- File format [default = DER-encoded binary file]

Returns:

Zero if successful.

Return type:

int

static to_xmlstring(keystr, opts=0, prefix='')¶

Return an XML string representation of an RSA internal key string.

Parameters:

keystr (str) -- Internal key string
opts (XmlOptions) -- Option flags.
prefix (str) -- Prefix to add to elements, e.g. "ds" or "ds:".

Returns:

XML string or empty string on error

Return type:

string