Namespace: go.std.crypto.rsa

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the crypto/rsa package.

Package rsa implements RSA encryption as specified in PKCS #1 and RFC 8017.

RSA is a single, fundamental operation that is used in this package to
implement either public-key encryption or public-key signatures.

The original specification for encryption and signatures with RSA is PKCS #1
and the terms "RSA encryption" and "RSA signatures" by default refer to
PKCS #1 version 1.5. However, that specification has flaws and new designs
should use version 2, usually called by just OAEP and PSS, where
possible.

Two sets of interfaces are included in this package. When a more abstract
interface isn't necessary, there are functions for encrypting/decrypting
with v1.5/OAEP and signing/verifying with v1.5/PSS. If one needs to abstract
over the public key primitive, the PrivateKey type implements the
Decrypter and Signer interfaces from the crypto package.

The RSA operations in this package are not implemented using constant-time algorithms.

Index

• *CRTValue
• *OAEPOptions
• *PKCS1v15DecryptOptions
• *PSSOptions
• *PrecomputedValues
• *PrivateKey
• *PublicKey
• CRTValue
• DecryptOAEP
• DecryptPKCS1v15
• DecryptPKCS1v15SessionKey
• EncryptOAEP
• EncryptPKCS1v15
• ErrDecryption
• ErrMessageTooLong
• ErrVerification
• GenerateKey
• GenerateMultiPrimeKey
• OAEPOptions
• PKCS1v15DecryptOptions
• PSSOptions
• PSSSaltLengthAuto
• PSSSaltLengthEqualsHash
• PrecomputedValues
• PrivateKey
• PublicKey
• SignPKCS1v15
• SignPSS
• VerifyPKCS1v15
• VerifyPSS
• arrayOfCRTValue
• arrayOfOAEPOptions
• arrayOfPKCS1v15DecryptOptions
• arrayOfPSSOptions
• arrayOfPrecomputedValues
• arrayOfPrivateKey
• arrayOfPublicKey

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

• PSSSaltLengthAuto

  Int v1.0

  PSSSaltLengthAuto causes the salt in a PSS signature to be as large
  as possible when signing, and to be auto-detected when verifying.
  

• PSSSaltLengthEqualsHash

  Int v1.0

  PSSSaltLengthEqualsHash causes the salt length to equal the length
  of the hash used in the signature.
  

Variables

• ErrDecryption

  Var v1.0

  ErrDecryption represents a failure to decrypt a message.
  It is deliberately vague to avoid adaptive attacks.
  

• ErrMessageTooLong

  Var v1.0

  ErrMessageTooLong is returned when attempting to encrypt a message which is
  too large for the size of the public key.
  

• ErrVerification

  Var v1.0

  ErrVerification represents a failure to verify a signature.
  It is deliberately vague to avoid adaptive attacks.
  

Functions, Macros, and Special Forms

• DecryptOAEP

  Function v1.0

  (DecryptOAEP hash random priv ciphertext label)
  

  DecryptOAEP decrypts ciphertext using RSA-OAEP.
  
  OAEP is parameterised by a hash function that is used as a random oracle.
  Encryption and decryption of a given message must use the same hash function
  and sha256.New() is a reasonable choice.
  
  The random parameter, if not nil, is used to blind the private-key operation
  and avoid timing side-channel attacks. Blinding is purely internal to this
  function – the random data need not match that used when encrypting.
  
  The label parameter must match the value given when encrypting. See
  EncryptOAEP for details.
  
  Go input arguments: (hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.hash/Hash hash, ^go.std.io/Reader random, ^*PrivateKey priv, ^arrayOfByte ciphertext, ^arrayOfByte label]
  
  Joker returns: [^arrayOfByte, ^Error]

• DecryptPKCS1v15

  Function v1.0

  (DecryptPKCS1v15 random priv ciphertext)
  

  DecryptPKCS1v15 decrypts a plaintext using RSA and the padding scheme from PKCS #1 v1.5.
  If random != nil, it uses RSA blinding to avoid timing side-channel attacks.
  
  Note that whether this function returns an error or not discloses secret
  information. If an attacker can cause this function to run repeatedly and
  learn whether each instance returned an error then they can decrypt and
  forge signatures as if they had the private key. See
  DecryptPKCS1v15SessionKey for a way of solving this problem.
  
  Go input arguments: (random io.Reader, priv *PrivateKey, ciphertext []byte)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.io/Reader random, ^*PrivateKey priv, ^arrayOfByte ciphertext]
  
  Joker returns: [^arrayOfByte, ^Error]

• DecryptPKCS1v15SessionKey

  Function v1.0

  (DecryptPKCS1v15SessionKey random priv ciphertext key)
  

  DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding scheme from PKCS #1 v1.5.
  If random != nil, it uses RSA blinding to avoid timing side-channel attacks.
  It returns an error if the ciphertext is the wrong length or if the
  ciphertext is greater than the public modulus. Otherwise, no error is
  returned. If the padding is valid, the resulting plaintext message is copied
  into key. Otherwise, key is unchanged. These alternatives occur in constant
  time. It is intended that the user of this function generate a random
  session key beforehand and continue the protocol with the resulting value.
  This will remove any possibility that an attacker can learn any information
  about the plaintext.
  See “Chosen Ciphertext Attacks Against Protocols Based on the RSA
  Encryption Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology
  (Crypto '98).
  
  Note that if the session key is too small then it may be possible for an
  attacker to brute-force it. If they can do that then they can learn whether
  a random value was used (because it'll be different for the same ciphertext)
  and thus whether the padding was correct. This defeats the point of this
  function. Using at least a 16-byte key will protect against this attack.
  
  Go input arguments: (random io.Reader, priv *PrivateKey, ciphertext []byte, key []byte)
  
  Go returns: error
  
  Joker input arguments: [^go.std.io/Reader random, ^*PrivateKey priv, ^arrayOfByte ciphertext, ^arrayOfByte key]
  
  Joker returns: ^Error

• EncryptOAEP

  Function v1.0

  (EncryptOAEP hash random pub msg label)
  

  EncryptOAEP encrypts the given message with RSA-OAEP.
  
  OAEP is parameterised by a hash function that is used as a random oracle.
  Encryption and decryption of a given message must use the same hash function
  and sha256.New() is a reasonable choice.
  
  The random parameter is used as a source of entropy to ensure that
  encrypting the same message twice doesn't result in the same ciphertext.
  
  The label parameter may contain arbitrary data that will not be encrypted,
  but which gives important context to the message. For example, if a given
  public key is used to encrypt two types of messages then distinct label
  values could be used to ensure that a ciphertext for one purpose cannot be
  used for another by an attacker. If not required it can be empty.
  
  The message must be no longer than the length of the public modulus minus
  twice the hash length, minus a further 2.
  
  Go input arguments: (hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.hash/Hash hash, ^go.std.io/Reader random, ^*PublicKey pub, ^arrayOfByte msg, ^arrayOfByte label]
  
  Joker returns: [^arrayOfByte, ^Error]

• EncryptPKCS1v15

  Function v1.0

  (EncryptPKCS1v15 random pub msg)
  

  EncryptPKCS1v15 encrypts the given message with RSA and the padding
  scheme from PKCS #1 v1.5. The message must be no longer than the
  length of the public modulus minus 11 bytes.
  
  The random parameter is used as a source of entropy to ensure that
  encrypting the same message twice doesn't result in the same
  ciphertext.
  
  WARNING: use of this function to encrypt plaintexts other than
  session keys is dangerous. Use RSA OAEP in new protocols.
  
  Go input arguments: (random io.Reader, pub *PublicKey, msg []byte)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.io/Reader random, ^*PublicKey pub, ^arrayOfByte msg]
  
  Joker returns: [^arrayOfByte, ^Error]

• GenerateKey

  Function v1.0

  (GenerateKey random bits)
  

  GenerateKey generates an RSA keypair of the given bit size using the
  random source random (for example, crypto/rand.Reader).
  
  Go input arguments: (random io.Reader, bits int)
  
  Go returns: (*PrivateKey, error)
  
  Joker input arguments: [^go.std.io/Reader random, ^Int bits]
  
  Joker returns: [^*PrivateKey, ^Error]

• GenerateMultiPrimeKey

  Function v1.0

  (GenerateMultiPrimeKey random nprimes bits)
  

  GenerateMultiPrimeKey generates a multi-prime RSA keypair of the given bit
  size and the given random source, as suggested in [1]. Although the public
  keys are compatible (actually, indistinguishable) from the 2-prime case,
  the private keys are not. Thus it may not be possible to export multi-prime
  private keys in certain formats or to subsequently import them into other
  code.
  
  Table 1 in [2] suggests maximum numbers of primes for a given size.
  
  [1] US patent 4405829 (1972, expired)
  [2] http://www.cacr.math.uwaterloo.ca/techreports/2006/cacr2006-16.pdf
  
  Go input arguments: (random io.Reader, nprimes int, bits int)
  
  Go returns: (*PrivateKey, error)
  
  Joker input arguments: [^go.std.io/Reader random, ^Int nprimes, ^Int bits]
  
  Joker returns: [^*PrivateKey, ^Error]

• SignPKCS1v15

  Function v1.0

  (SignPKCS1v15 random priv hash hashed)
  

  SignPKCS1v15 calculates the signature of hashed using
  RSASSA-PKCS1-V1_5-SIGN from RSA PKCS #1 v1.5. Note that hashed must
  be the result of hashing the input message using the given hash
  function. If hash is zero, hashed is signed directly. This isn't
  advisable except for interoperability.
  
  If random is not nil then RSA blinding will be used to avoid timing
  side-channel attacks.
  
  This function is deterministic. Thus, if the set of possible
  messages is small, an attacker may be able to build a map from
  messages to signatures and identify the signed messages. As ever,
  signatures provide authenticity, not confidentiality.
  
  Go input arguments: (random io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.io/Reader random, ^*PrivateKey priv, ^go.std.crypto/Hash hash, ^arrayOfByte hashed]
  
  Joker returns: [^arrayOfByte, ^Error]

• SignPSS

  Function v1.0

  (SignPSS rand priv hash digest opts)
  

  SignPSS calculates the signature of digest using PSS.
  
  digest must be the result of hashing the input message using the given hash
  function. The opts argument may be nil, in which case sensible defaults are
  used. If opts.Hash is set, it overrides hash.
  
  Go input arguments: (rand io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^go.std.io/Reader rand, ^*PrivateKey priv, ^go.std.crypto/Hash hash, ^arrayOfByte digest, ^*PSSOptions opts]
  
  Joker returns: [^arrayOfByte, ^Error]

• VerifyPKCS1v15

  Function v1.0

  (VerifyPKCS1v15 pub hash hashed sig)
  

  VerifyPKCS1v15 verifies an RSA PKCS #1 v1.5 signature.
  hashed is the result of hashing the input message using the given hash
  function and sig is the signature. A valid signature is indicated by
  returning a nil error. If hash is zero then hashed is used directly. This
  isn't advisable except for interoperability.
  
  Go input arguments: (pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte)
  
  Go returns: error
  
  Joker input arguments: [^*PublicKey pub, ^go.std.crypto/Hash hash, ^arrayOfByte hashed, ^arrayOfByte sig]
  
  Joker returns: ^Error

• VerifyPSS

  Function v1.0

  (VerifyPSS pub hash digest sig opts)
  

  VerifyPSS verifies a PSS signature.
  
  A valid signature is indicated by returning a nil error. digest must be the
  result of hashing the input message using the given hash function. The opts
  argument may be nil, in which case sensible defaults are used. opts.Hash is
  ignored.
  
  Go input arguments: (pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions)
  
  Go returns: error
  
  Joker input arguments: [^*PublicKey pub, ^go.std.crypto/Hash hash, ^arrayOfByte digest, ^arrayOfByte sig, ^*PSSOptions opts]
  
  Joker returns: ^Error

Types

• *CRTValue

  Concrete Type v1.0

  CRTValue contains the precomputed Chinese remainder theorem values.
  

• *OAEPOptions

  Concrete Type v1.0

  OAEPOptions is an interface for passing options to OAEP decryption using the
  crypto.Decrypter interface.
  

• *PKCS1v15DecryptOptions

  Concrete Type v1.0

  PKCS1v15DecrypterOpts is for passing options to PKCS #1 v1.5 decryption using
  the crypto.Decrypter interface.
  

• *PSSOptions

  Concrete Type v1.0

  PSSOptions contains options for creating and verifying PSS signatures.
  

• HashFunc

  Receiver for *PSSOptions v1.0

  ([])
  

  HashFunc returns opts.Hash so that PSSOptions implements crypto.SignerOpts.
  

• *PrecomputedValues

  Concrete Type v1.0

• *PrivateKey

  Concrete Type v1.0

  A PrivateKey represents an RSA key
  

• Decrypt

  Receiver for *PrivateKey v1.0

  ([rand ciphertext opts])
  

  Decrypt decrypts ciphertext with priv. If opts is nil or of type
  *PKCS1v15DecryptOptions then PKCS #1 v1.5 decryption is performed. Otherwise
  opts must have type *OAEPOptions and OAEP decryption is done.
  

• Equal

  Receiver for *PrivateKey v1.0

  ([x])
  

  Equal reports whether priv and x have equivalent values. It ignores
  Precomputed values.
  

• Precompute

  Receiver for *PrivateKey v1.0

  ([])
  

  Precompute performs some calculations that speed up private key operations
  in the future.
  

• Public

  Receiver for *PrivateKey v1.0

  ([])
  

  Public returns the public key corresponding to priv.
  

• Sign

  Receiver for *PrivateKey v1.0

  ([rand digest opts])
  

  Sign signs digest with priv, reading randomness from rand. If opts is a
  *PSSOptions then the PSS algorithm will be used, otherwise PKCS #1 v1.5 will
  be used. digest must be the result of hashing the input message using
  opts.HashFunc().
  
  This method implements crypto.Signer, which is an interface to support keys
  where the private part is kept in, for example, a hardware module. Common
  uses should use the Sign* functions in this package directly.
  

• Size

  Receiver for *PrivateKey v1.0

  ([])
  

  Size returns the modulus size in bytes. Raw signatures and ciphertexts
  for or by this public key will have the same size.
  

• Validate

  Receiver for *PrivateKey v1.0

  ([])
  

  Validate performs basic sanity checks on the key.
  It returns nil if the key is valid, or else an error describing a problem.
  

• *PublicKey

  Concrete Type v1.0

  A PublicKey represents the public part of an RSA key.
  

• Equal

  Receiver for *PublicKey v1.0

  ([x])
  

  Equal reports whether pub and x have the same value.
  

• Size

  Receiver for *PublicKey v1.0

  ([])
  

  Size returns the modulus size in bytes. Raw signatures and ciphertexts
  for or by this public key will have the same size.
  

• CRTValue

  Concrete Type v1.0

  CRTValue contains the precomputed Chinese remainder theorem values.
  

• OAEPOptions

  Concrete Type v1.0

  OAEPOptions is an interface for passing options to OAEP decryption using the
  crypto.Decrypter interface.
  

• PKCS1v15DecryptOptions

  Concrete Type v1.0

  PKCS1v15DecrypterOpts is for passing options to PKCS #1 v1.5 decryption using
  the crypto.Decrypter interface.
  

• PSSOptions

  Concrete Type v1.0

  PSSOptions contains options for creating and verifying PSS signatures.
  

• PrecomputedValues

  Concrete Type v1.0

• PrivateKey

  Concrete Type v1.0

  A PrivateKey represents an RSA key
  

• PublicKey

  Concrete Type v1.0

  A PublicKey represents the public part of an RSA key.
  

• arrayOfCRTValue

  Concrete Type v1.0

  CRTValue contains the precomputed Chinese remainder theorem values.
  

• arrayOfOAEPOptions

  Concrete Type v1.0

  OAEPOptions is an interface for passing options to OAEP decryption using the
  crypto.Decrypter interface.
  

• arrayOfPKCS1v15DecryptOptions

  Concrete Type v1.0

  PKCS1v15DecrypterOpts is for passing options to PKCS #1 v1.5 decryption using
  the crypto.Decrypter interface.
  

• arrayOfPSSOptions

  Concrete Type v1.0

  PSSOptions contains options for creating and verifying PSS signatures.
  

• arrayOfPrecomputedValues

  Concrete Type v1.0

• arrayOfPrivateKey

  Concrete Type v1.0

  A PrivateKey represents an RSA key
  

• arrayOfPublicKey

  Concrete Type v1.0

  A PublicKey represents the public part of an RSA key.