example_test.go

     1  // Copyright 2016 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package rsa_test
     6  
     7  import (
     8  	"crypto"
     9  	"crypto/aes"
    10  	"crypto/cipher"
    11  	"crypto/rand"
    12  	"crypto/rsa"
    13  	"crypto/sha256"
    14  	"crypto/x509"
    15  	"encoding/hex"
    16  	"encoding/pem"
    17  	"fmt"
    18  	"os"
    19  	"strings"
    20  )
    21  
    22  func ExampleGenerateKey() {
    23  	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
    24  	if err != nil {
    25  		fmt.Fprintf(os.Stderr, "Error generating RSA key: %s", err)
    26  		return
    27  	}
    28  
    29  	der, err := x509.MarshalPKCS8PrivateKey(privateKey)
    30  	if err != nil {
    31  		fmt.Fprintf(os.Stderr, "Error marshalling RSA private key: %s", err)
    32  		return
    33  	}
    34  
    35  	fmt.Printf("%s", pem.EncodeToMemory(&pem.Block{
    36  		Type:  "PRIVATE KEY",
    37  		Bytes: der,
    38  	}))
    39  }
    40  
    41  func ExampleGenerateKey_testKey() {
    42  	// This is an insecure, test-only key from RFC 9500, Section 2.1.
    43  	// It can be used in tests to avoid slow key generation.
    44  	block, _ := pem.Decode([]byte(strings.ReplaceAll(
    45  		`-----BEGIN RSA TESTING KEY-----
    46  MIIEowIBAAKCAQEAsPnoGUOnrpiSqt4XynxA+HRP7S+BSObI6qJ7fQAVSPtRkqso
    47  tWxQYLEYzNEx5ZSHTGypibVsJylvCfuToDTfMul8b/CZjP2Ob0LdpYrNH6l5hvFE
    48  89FU1nZQF15oVLOpUgA7wGiHuEVawrGfey92UE68mOyUVXGweJIVDdxqdMoPvNNU
    49  l86BU02vlBiESxOuox+dWmuVV7vfYZ79Toh/LUK43YvJh+rhv4nKuF7iHjVjBd9s
    50  B6iDjj70HFldzOQ9r8SRI+9NirupPTkF5AKNe6kUhKJ1luB7S27ZkvB3tSTT3P59
    51  3VVJvnzOjaA1z6Cz+4+eRvcysqhrRgFlwI9TEwIDAQABAoIBAEEYiyDP29vCzx/+
    52  dS3LqnI5BjUuJhXUnc6AWX/PCgVAO+8A+gZRgvct7PtZb0sM6P9ZcLrweomlGezI
    53  FrL0/6xQaa8bBr/ve/a8155OgcjFo6fZEw3Dz7ra5fbSiPmu4/b/kvrg+Br1l77J
    54  aun6uUAs1f5B9wW+vbR7tzbT/mxaUeDiBzKpe15GwcvbJtdIVMa2YErtRjc1/5B2
    55  BGVXyvlJv0SIlcIEMsHgnAFOp1ZgQ08aDzvilLq8XVMOahAhP1O2A3X8hKdXPyrx
    56  IVWE9bS9ptTo+eF6eNl+d7htpKGEZHUxinoQpWEBTv+iOoHsVunkEJ3vjLP3lyI/
    57  fY0NQ1ECgYEA3RBXAjgvIys2gfU3keImF8e/TprLge1I2vbWmV2j6rZCg5r/AS0u
    58  pii5CvJ5/T5vfJPNgPBy8B/yRDs+6PJO1GmnlhOkG9JAIPkv0RBZvR0PMBtbp6nT
    59  Y3yo1lwamBVBfY6rc0sLTzosZh2aGoLzrHNMQFMGaauORzBFpY5lU50CgYEAzPHl
    60  u5DI6Xgep1vr8QvCUuEesCOgJg8Yh1UqVoY/SmQh6MYAv1I9bLGwrb3WW/7kqIoD
    61  fj0aQV5buVZI2loMomtU9KY5SFIsPV+JuUpy7/+VE01ZQM5FdY8wiYCQiVZYju9X
    62  Wz5LxMNoz+gT7pwlLCsC4N+R8aoBk404aF1gum8CgYAJ7VTq7Zj4TFV7Soa/T1eE
    63  k9y8a+kdoYk3BASpCHJ29M5R2KEA7YV9wrBklHTz8VzSTFTbKHEQ5W5csAhoL5Fo
    64  qoHzFFi3Qx7MHESQb9qHyolHEMNx6QdsHUn7rlEnaTTyrXh3ifQtD6C0yTmFXUIS
    65  CW9wKApOrnyKJ9nI0HcuZQKBgQCMtoV6e9VGX4AEfpuHvAAnMYQFgeBiYTkBKltQ
    66  XwozhH63uMMomUmtSG87Sz1TmrXadjAhy8gsG6I0pWaN7QgBuFnzQ/HOkwTm+qKw
    67  AsrZt4zeXNwsH7QXHEJCFnCmqw9QzEoZTrNtHJHpNboBuVnYcoueZEJrP8OnUG3r
    68  UjmopwKBgAqB2KYYMUqAOvYcBnEfLDmyZv9BTVNHbR2lKkMYqv5LlvDaBxVfilE0
    69  2riO4p6BaAdvzXjKeRrGNEKoHNBpOSfYCOM16NjL8hIZB1CaV3WbT5oY+jp7Mzd5
    70  7d56RZOE+ERK2uz/7JX9VSsM/LbH9pJibd4e8mikDS9ntciqOH/3
    71  -----END RSA TESTING KEY-----`, "TESTING KEY", "PRIVATE KEY")))
    72  	testRSA2048, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
    73  
    74  	fmt.Println("Private key bit size:", testRSA2048.N.BitLen())
    75  }
    76  
    77  // RSA is able to encrypt only a very limited amount of data. In order
    78  // to encrypt reasonable amounts of data a hybrid scheme is commonly
    79  // used: RSA is used to encrypt a key for a symmetric primitive like
    80  // AES-GCM.
    81  //
    82  // Before encrypting, data is “padded” by embedding it in a known
    83  // structure. This is done for a number of reasons, but the most
    84  // obvious is to ensure that the value is large enough that the
    85  // exponentiation is larger than the modulus. (Otherwise it could be
    86  // decrypted with a square-root.)
    87  //
    88  // In these designs, when using PKCS #1 v1.5, it's vitally important to
    89  // avoid disclosing whether the received RSA message was well-formed
    90  // (that is, whether the result of decrypting is a correctly padded
    91  // message) because this leaks secret information.
    92  // DecryptPKCS1v15SessionKey is designed for this situation and copies
    93  // the decrypted, symmetric key (if well-formed) in constant-time over
    94  // a buffer that contains a random key. Thus, if the RSA result isn't
    95  // well-formed, the implementation uses a random key in constant time.
    96  func ExampleDecryptPKCS1v15SessionKey() {
    97  	// The hybrid scheme should use at least a 16-byte symmetric key. Here
    98  	// we read the random key that will be used if the RSA decryption isn't
    99  	// well-formed.
   100  	key := make([]byte, 32)
   101  	if _, err := rand.Read(key); err != nil {
   102  		panic("RNG failure")
   103  	}
   104  
   105  	rsaCiphertext, _ := hex.DecodeString("aabbccddeeff")
   106  
   107  	if err := rsa.DecryptPKCS1v15SessionKey(nil, rsaPrivateKey, rsaCiphertext, key); err != nil {
   108  		// Any errors that result will be “public” – meaning that they
   109  		// can be determined without any secret information. (For
   110  		// instance, if the length of key is impossible given the RSA
   111  		// public key.)
   112  		fmt.Fprintf(os.Stderr, "Error from RSA decryption: %s\n", err)
   113  		return
   114  	}
   115  
   116  	// Given the resulting key, a symmetric scheme can be used to decrypt a
   117  	// larger ciphertext.
   118  	block, err := aes.NewCipher(key)
   119  	if err != nil {
   120  		panic("aes.NewCipher failed: " + err.Error())
   121  	}
   122  
   123  	// Since the key is random, using a fixed nonce is acceptable as the
   124  	// (key, nonce) pair will still be unique, as required.
   125  	var zeroNonce [12]byte
   126  	aead, err := cipher.NewGCM(block)
   127  	if err != nil {
   128  		panic("cipher.NewGCM failed: " + err.Error())
   129  	}
   130  	ciphertext, _ := hex.DecodeString("00112233445566")
   131  	plaintext, err := aead.Open(nil, zeroNonce[:], ciphertext, nil)
   132  	if err != nil {
   133  		// The RSA ciphertext was badly formed; the decryption will
   134  		// fail here because the AES-GCM key will be incorrect.
   135  		fmt.Fprintf(os.Stderr, "Error decrypting: %s\n", err)
   136  		return
   137  	}
   138  
   139  	fmt.Printf("Plaintext: %s\n", plaintext)
   140  }
   141  
   142  func ExampleSignPKCS1v15() {
   143  	message := []byte("message to be signed")
   144  
   145  	// Only small messages can be signed directly; thus the hash of a
   146  	// message, rather than the message itself, is signed. This requires
   147  	// that the hash function be collision resistant. SHA-256 is the
   148  	// least-strong hash function that should be used for this at the time
   149  	// of writing (2016).
   150  	hashed := sha256.Sum256(message)
   151  
   152  	signature, err := rsa.SignPKCS1v15(nil, rsaPrivateKey, crypto.SHA256, hashed[:])
   153  	if err != nil {
   154  		fmt.Fprintf(os.Stderr, "Error from signing: %s\n", err)
   155  		return
   156  	}
   157  
   158  	fmt.Printf("Signature: %x\n", signature)
   159  }
   160  
   161  func ExampleVerifyPKCS1v15() {
   162  	message := []byte("message to be signed")
   163  	signature, _ := hex.DecodeString("ad2766728615cc7a746cc553916380ca7bfa4f8983b990913bc69eb0556539a350ff0f8fe65ddfd3ebe91fe1c299c2fac135bc8c61e26be44ee259f2f80c1530")
   164  
   165  	// Only small messages can be signed directly; thus the hash of a
   166  	// message, rather than the message itself, is signed. This requires
   167  	// that the hash function be collision resistant. SHA-256 is the
   168  	// least-strong hash function that should be used for this at the time
   169  	// of writing (2016).
   170  	hashed := sha256.Sum256(message)
   171  
   172  	err := rsa.VerifyPKCS1v15(&rsaPrivateKey.PublicKey, crypto.SHA256, hashed[:], signature)
   173  	if err != nil {
   174  		fmt.Fprintf(os.Stderr, "Error from verification: %s\n", err)
   175  		return
   176  	}
   177  
   178  	// signature is a valid signature of message from the public key.
   179  }
   180  
   181  func ExampleEncryptOAEP() {
   182  	secretMessage := []byte("send reinforcements, we're going to advance")
   183  	label := []byte("orders")
   184  
   185  	// crypto/rand.Reader is a good source of entropy for randomizing the
   186  	// encryption function.
   187  	rng := rand.Reader
   188  
   189  	ciphertext, err := rsa.EncryptOAEP(sha256.New(), rng, &test2048Key.PublicKey, secretMessage, label)
   190  	if err != nil {
   191  		fmt.Fprintf(os.Stderr, "Error from encryption: %s\n", err)
   192  		return
   193  	}
   194  
   195  	// Since encryption is a randomized function, ciphertext will be
   196  	// different each time.
   197  	fmt.Printf("Ciphertext: %x\n", ciphertext)
   198  }
   199  
   200  func ExampleDecryptOAEP() {
   201  	ciphertext, _ := hex.DecodeString("4d1ee10e8f286390258c51a5e80802844c3e6358ad6690b7285218a7c7ed7fc3a4c7b950fbd04d4b0239cc060dcc7065ca6f84c1756deb71ca5685cadbb82be025e16449b905c568a19c088a1abfad54bf7ecc67a7df39943ec511091a34c0f2348d04e058fcff4d55644de3cd1d580791d4524b92f3e91695582e6e340a1c50b6c6d78e80b4e42c5b4d45e479b492de42bbd39cc642ebb80226bb5200020d501b24a37bcc2ec7f34e596b4fd6b063de4858dbf5a4e3dd18e262eda0ec2d19dbd8e890d672b63d368768360b20c0b6b8592a438fa275e5fa7f60bef0dd39673fd3989cc54d2cb80c08fcd19dacbc265ee1c6014616b0e04ea0328c2a04e73460")
   202  	label := []byte("orders")
   203  
   204  	plaintext, err := rsa.DecryptOAEP(sha256.New(), nil, test2048Key, ciphertext, label)
   205  	if err != nil {
   206  		fmt.Fprintf(os.Stderr, "Error from decryption: %s\n", err)
   207  		return
   208  	}
   209  
   210  	fmt.Printf("Plaintext: %s\n", plaintext)
   211  
   212  	// Remember that encryption only provides confidentiality. The
   213  	// ciphertext should be signed before authenticity is assumed and, even
   214  	// then, consider that messages might be reordered.
   215  }
   216
View as plain text