Update docs

Author: cicnavi

docs/3-federation.md

@@ -285,3 +285,60 @@ try {
 }
 
 ```
+
+## Prepare Entity Statements
+
+You can use an Entity Statement Factory to quickly create Entity Statements.
+Since Entity Statements are signed JWTs (JWS), you have to have your private
+key prepared which will be used to sign them. 
+
+```php
+
+use SimpleSAML\OpenID\Codebooks\ClaimsEnum;
+use SimpleSAML\OpenID\Jwk;
+use SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum;
+
+/** @var \SimpleSAML\OpenID\Federation $federationTools */
+
+// You can use the JWK Tools to create a JWK decorator from a private key file.
+$jwkTools = new Jwk();
+
+// Prepare a signing key decorator. Check other methods on `jwkDecoratorFactory`
+// for alternative ways to create a key decorator. 
+$signingKey = $jwkTools->jwkDecoratorFactory()->fromPkcs1Or8KeyFile(
+    '/path/to/private/key.pem',
+);
+
+// Set the signature algorithm to use.
+$signatureAlgorithm = SignatureAlgorithmEnum::ES256;
+
+// Use any logic necessary to prepare JWT payload data.
+$issuedAt = new DateTimeImmutable('now', new DateTimeZone('UTC'));
+
+$jwtPayload = [
+    ClaimsEnum::Iss->value => 'https://example.com/issuer',
+    ClaimsEnum::Iat->value => $issuedAt->getTimestamp(),
+    ClaimsEnum::Nbf->value => $issuedAt->getTimestamp(),
+    ClaimsEnum::Sub->value => 'subject-id',
+    // ...
+];
+
+// Use any logic necessary to prepare JWT header data.
+$jwtHeader = [
+    ClaimsEnum::Kid->value 'abc123',
+    //...
+];
+
+// Build Entity Statement instance.
+$entityStatement = $federationTools->entityStatementFactory()->fromData(
+    $signingKey,
+    $signatureAlgorithm,
+    $jwtPayload,
+    $jwtHeader,
+);
+
+// Get Entity Statement token string (JWS). Default serialization is
+// JwsSerializerEnum::Compact.
+$entityStatementToken = $entityStatement->getToken();
+
+```

docs/4-vci.md

@@ -42,7 +42,8 @@ $verifiableCredentialTools = new VerifiableCredentials(
     $timestampValidationLeeway,
 );
 
-// You can also use the JWK Tools to create a JWK decorator from a private key file.
+// You can also use the JWK Tools to create a JWK decorator from a private key
+// file.
 $jwkTools = new Jwk();
 ```
 
@@ -56,6 +57,7 @@ The following example shows how to create a SD-JWT VC.
 ```php
 
 use SimpleSAML\OpenID\Codebooks\ClaimsEnum;
+use SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum;
 
 /** @var \SimpleSAML\OpenID\VerifiableCredentials $verifiableCredentialTools */
 /** @var \SimpleSAML\OpenID\Jwk $jwkTools */
@@ -81,7 +83,7 @@ foreach ($disclosedData as $key => $value) {
     $disclosureBag->add($disclosure);
 }
 
-$issuedAt = new \DateTimeImmutable();
+$issuedAt = new DateTimeImmutable('now', new DateTimeZone('UTC'));
 
 // Use any logic necessary to prepare basic JWT payload data.
 $jwtPayload = [
@@ -94,8 +96,9 @@ $jwtPayload = [
     // ...
 ];
 
-// Use any logic necessary to prepare SD JWT header data.
+// Use any logic necessary to prepare JWT header data.
 $jwtHeader = [
+    ClaimsEnum::Kid->value 'abc123',
     //...
 ];
 
@@ -116,6 +119,7 @@ $verifiableCredential = $verifiableCredentialTools->sdJwtVcFactory()->fromData(
     $disclosureBag,
 );
 
-// Get the credential token string.
+// Get the credential token string (JWS). Default serialization is
+// JwsSerializerEnum::Compact.
 $token = $verifiableCredential->getToken();
 ```